# Six verbs, one contract

Core inputs, response envelopes, pagination and the Remote MCP contract.

Canonical: https://socialtoai.com/docs/verbs/

## Choose an action

search: query public content or users. Select platform, or an explicit list of up to five platforms. count is 1–20. A multi-platform call cannot take a cursor.

trending: choose a platform and an optional supported category. Some platforms return content items; others return leaderboards.

detail and comments: pass platform and url_or_id. Comments can take cursor and reply_of.

user_profile and user_posts: pass platform and user. Creator posts can take a cursor. Accepted account identifiers differ by platform.

[Download OpenAPI 3.1 →](https://socialtoai.com/openapi.json)

## Read the envelope

Every response includes request_id, schema_version and fetched_at. A single-platform result contains platform, status, items, applied_params and warnings. A multi-platform search groups results under fanout and itemizes billing.detail.

MCP structuredContent and the JSON text payload carry the same envelope. not_supported is a domain result, not a transport error. Inspect each fanout cell even when the outer status is ok.

```
{
  "request_id": "example_only_not_a_live_call",
  "schema_version": "v1",
  "fetched_at": "2026-09-05T00:00:00Z",
  "status": "ok",
  "applied_params": {},
  "warnings": [],
  "items": [
    {
      "kind": "item",
      "id": "EXAMPLE_ITEM_ID",
      "author": {
        "name": "example_author"
      },
      "published_at": "2026-09-01T08:30:00Z",
      "metrics": {
        "likes": 412,
        "comments": 96
      },
      "title": "Illustrative post title",
      "text": "Illustrative excerpt, not real content."
    }
  ],
  "platform": "reddit",
  "billing": {
    "cost": 0.2,
    "balance": 1.8,
    "unit": "credits",
    "pricing": "standard"
  }
}
```

[Download the complete envelope schema →](https://socialtoai.com/envelope.schema.json)

## Keep continuation opaque

Cursors bind the workspace, platform, verb and normalized query, and expire after 30 minutes. Do not parse, edit or move a cursor to another request. A cursor is only valid for a single platform.

Stop when has_more is false or your page or credit budget is exhausted. Missing native filter support must remain visible in your explanation. See the platform-specific limits before opening reply branches.

## Discover only what your Key can use

The default Connector exposes six core verbs and capabilities. The account and ping tools are not included in that restricted scope set; use the console to check your balance before the first paid call. Additional scopes and capability packs are not granted by adding a URL parameter. Raw and domain-pack availability must be explicitly documented before use.

GET and POST share core paths under /v1/. Product Keys use X-API-Key, Bearer or key query authentication. Console routes use the signed-in user Session instead.