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 receive the complete ranked set selected by the search engine in the same response. It supports topic relevance searches, recipes and how-to content, formats and exclusions, audience and location constraints, and filtered top-content feeds. 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://search-backend-s4c56s44ia-uk.a.run.app/v1

All endpoints are relative to this base URL.

Latency and retries

Section titled “Latency and retries”

A typical search takes 30–60 seconds, and thin searches can take longer while the API prepares a diagnosis and alternative queries. Plan integrations accordingly:

  • Call the API server-to-server, never directly from a browser.
  • Set the client/socket read timeout to at least 270 seconds.
  • Send an Idempotency-Key with every search request.
  • If a connection or gateway times out, retry with the same Idempotency-Key and identical body. The retry waits for an active request, returns a completed request, or reruns a request that reached its execution deadline.

Without an idempotency key, a retry can start a second search.

Authentication

Section titled “Authentication”

Every request requires an active Search API key. Send it as a Bearer token:

Authorization: Bearer sak_live_<KEY_PREFIX>.<SECRET>

The x-api-key header is also accepted, but Bearer authentication is recommended. Missing, invalid, and revoked keys return 401.

The same active key works with both the real-time general Search API and the bulk brand-search API. Brand whitelists apply only to bulk brand-search jobs; general search accepts any supported natural-language query.

Getting an API key

Section titled “Getting an API key”

Search API keys are currently provisioned manually by a Sociable AI operator through the key-provisioning CLI. The full secret is delivered once through a secure channel. Only its hash is stored, so the secret cannot be displayed again. Contact Sociable AI to create, rotate, or revoke a key.

Next steps

Section titled “Next steps”