Skip to content
Sociable AI Documentation

Search API

Overview

Section titled “Overview”

The Search API runs a real-time, natural-language search over short-form social content and returns a ranked set of matching posts. You send a query and get the ranked results back in the same response. The indexed corpus is currently Instagram.

Need bulk export over historical post data instead? See the bulk Search API.

Base URL

Section titled “Base URL”
https://api.sociable.how/v1

All endpoints are relative to this base URL.

Latency

Section titled “Latency”

A typical request takes 30–60 seconds to return. This is expected, not an error — plan your integration around it:

  • Call the API server-to-server, never directly from a browser. A backend call keeps your API key secret and lets you control timeouts.
  • Set your client/socket read timeout to at least 90–120 seconds. Default HTTP client timeouts (often 30–60s) will cut the connection before results return.
  • Be ready to retry. If an intermediate proxy or load balancer drops a long request, you may receive a 504. A 504 is safe to retry.

Authentication

Section titled “Authentication”

Every request must include an API key, sent as a Bearer token:

Authorization: Bearer sk_live_<YOUR_API_KEY>

If the key is missing or invalid, the API returns 401.

Keys come in two environments, identified by their prefix:

  • sk_live_… — live keys for production traffic.
  • sk_test_… — test keys for development and integration work.

Treat your secret key like a password. It grants full access to the API under your account, so it must only ever be used from your backend — never embedded in a browser, mobile app, or any client-side code.

Getting an API key

Section titled “Getting an API key”

Generate and manage keys yourself in the dashboard under Settings → API Keys:

  • Create a new key and give it a recognizable name.
  • The key is shown once, at creation. Copy it then and store it securely — we keep only a hash and cannot show it to you again.
  • You can hold multiple keys at once and revoke any of them independently, so you can rotate keys without downtime.

Enterprise provisioning

Section titled “Enterprise provisioning”

For backend-only integrations, the cleanest path is still self-service: we enable your workspace, and your admin generates the key in Settings → API Keys so the secret is created on your side and never transmitted.

If we need to hand a key to you directly, we deliver it through a one-time secure link — never over email or chat. Rotate it immediately after setup by issuing a fresh key and revoking the delivered one.

Next steps

Section titled “Next steps”