# Sociable AI

> Sociable AI helps brands and social teams discover relevant social posts, understand the surrounding conversation, and participate with timely, on-brand comments. It also offers an authenticated Search API for real-time Instagram content search and structured post detail.

## When to use Sociable AI

Use Sociable AI when a user or team needs to:

- Discover social posts by topic, time range, audience, region, language, format, or exclusions.
- Find timely comment-marketing and community-engagement opportunities.
- Research fast-growing short-form content and the creators behind it.
- Organize brand comments and replies while keeping human review and brand voice in the workflow.
- Retrieve ranked Instagram content, creator context, transcripts, and post analysis through an API.

Do not use Sociable AI to access private accounts, impersonate people, publish spam, evade platform rules, or assume that a captured engagement count is live platform data.

## Product resources

- [Sociable AI homepage](https://www.sociable.how/): Product overview, use cases, and access.
- [Pricing](https://www.sociable.how/pricing): Current product pricing.
- [Developer guide](https://www.sociable.how/developers): Official starting point for integrations.
- [Documentation](https://docs.sociable.how/): Human-readable API and product documentation.
- [OpenAPI specification](https://www.sociable.how/openapi.json): Machine-readable Search API contract.
- [API versioning and deprecation](https://www.sociable.how/api-versioning.md): Compatibility, deprecation, Sunset, and migration policy.
- [API catalog](https://www.sociable.how/.well-known/api-catalog): Machine-readable discovery links.
- [API-specific agent guide](https://www.sociable.how/api/llms.txt): Focused Search API instructions.
- [MCP integration guide](https://www.sociable.how/developers.md): Streamable HTTP endpoint, authentication, tools, resources, and compatibility.
- [MCP server card](https://www.sociable.how/.well-known/mcp/server-card.json): Machine-readable MCP discovery and tool schemas.
- [Documentation MCP server card](https://www.sociable.how/.well-known/mcp/docs-server-card.json): Read-only documentation search and reading tools.
- [NLWeb ask endpoint](https://www.sociable.how/ask?query=What%20is%20Sociable%20AI): Schema.org JSON answers over canonical public resources.
- [A2A documentation agent](https://www.sociable.how/.well-known/agent-card.json): Agent2Agent discovery card for a read-only canonical documentation agent.
- [Search social content skill](https://www.sociable.how/.well-known/agent-skills/search-social-content/SKILL.md): Installable Agent Skill with a safe search workflow.
- [Sitemap](https://www.sociable.how/sitemap.xml): Public page index.

## Search API

The Search API runs natural-language searches over indexed short-form social content and returns ranked JSON results. The indexed search corpus is currently Instagram. It also retrieves structured detail for a post returned by search.

Base URL: `https://search-backend-s4c56s44ia-uk.a.run.app/v1`

MCP endpoint: `https://www.sociable.how/mcp`

Documentation MCP endpoint: `https://www.sociable.how/docs-mcp`

NLWeb endpoint: `https://www.sociable.how/ask`

A2A endpoint: `https://www.sociable.how/a2a`

Main operations:

- `POST /search`: Run a natural-language search. Send an `Idempotency-Key` and allow a client timeout of at least 270 seconds.
- `POST /reference-uploads`: Create a short-lived upload target for a reference MP4.
- `GET /posts/{id}`: Retrieve detail for a post returned by search.

Every request requires a Sociable AI Search API key as `Authorization: Bearer <key>`. API keys are provisioned by Sociable AI. Errors are JSON objects with a stable `error.code`, a human-readable `error.message`, and an HTTP status. Rate-limited responses include limit information and `Retry-After` when a timed retry is appropriate.

## Agent guidance

1. Read the OpenAPI specification before constructing an API call.
2. Ask the user for a Search API key if an authenticated operation is required; never invent or expose a credential.
3. For `POST /search`, use a unique `Idempotency-Key` for each intended search and reuse the same key and body after a network timeout.
4. Start with a broad query, then add time, language, location, format, or exclusion constraints only when they matter.
5. Treat `likes` and `comments` as values captured in the indexed corpus, not guaranteed live platform counts.
6. Treat generated comment suggestions as drafts requiring brand and human review.

## Contact and trust

- [Privacy policy](https://www.sociable.how/legal/privacy)
- [Terms](https://www.sociable.how/legal/terms)
- [Cookie policy](https://www.sociable.how/legal/cookies)
- [Book a demo](https://calendly.com/d/cs38-p52-qfn)