Capabilities API

Every BeatAPI capability — social media data (Xiaohongshu, Douyin, TikTok, Bilibili, Weibo, X, Instagram, YouTube and more), text, image, video and decision models, web search and media workflows — is used the same way, in three calls:

1. Search for what the user needs and pick a reference.
2. Inspect that reference to read its input, price and readiness.
3. Run it and get the result, or a task to poll.

Every reply carries next: the exact call to make next. An agent copies it and fills in the <placeholders> instead of reasoning about the contract. Copy references exactly as returned; never build one.

Search and Inspect are free and need no key. Run spends the account balance and needs Authorization: Bearer <BeatAPI API key>; the key works with or without the sk- prefix. The same three operations are the MCP tools capabilities_search, capabilities_inspect and capabilities_run at https://beatapi.io/mcp.

Search

curl -sS -X POST https://api.beatapi.io/v1/capabilities/search \
  -H 'Content-Type: application/json' \
  -d '{"query":"小红书 搜索笔记"}'

The reply’s data holds compact cards — reference, title, summary, price, readiness and a one-line input signature. understood shows which words of the query counted and which were ignored.

• Overview. A query that names only a platform (小红书), or group_by: "function", fills groups: what the platform offers, by function (search, content, comments, users, trends, feeds, commerce, live), each with a count, example references and the search arguments that list the rest. An empty query returns the catalogue map.
• No match. Zero results come with hints on how to rephrase and the platform slugs, instead of an empty page.

Inspect

curl -sS -X POST https://api.beatapi.io/v1/capabilities/inspect \
  -H 'Content-Type: application/json' \
  -d '{"reference":"data:xiaohongshu.app_v2.search_notes"}'

Inspect returns the complete contract: input_schema (required fields, types, limits), pricing, execution.mode (sync answers in the response, async returns a task), readiness and next — a Run call with the reference filled in and a placeholder for every required input.

A guessed or misspelled reference returns 404 not_found with suggestions, the closest published references, and a next that inspects the best of them.

Run

curl -sS -X POST https://api.beatapi.io/v1/capabilities/run \
  -H "Authorization: Bearer $BEATAPI_API_KEY" -H 'Content-Type: application/json' \
  -d '{"reference":"data:xiaohongshu.app_v2.search_notes","input":{"keyword":"AI 视频"},"view":"preview"}'

What a start returns depends on the kind:

Result views. Platform payloads run to tens of kilobytes, and every platform nests its list somewhere else. view: "preview" lifts the result’s main list to a top-level items (the first max_items, each element trimmed inside) and says where it came from in items_path (data.data.items, results, …) with items_total; long strings are shortened, the reply stays under a size budget and is marked truncated with a result_ref. fields keeps only the paths you name, items[].<key> for keys of each element. The full result stays retrievable, free, for one hour with the same key:

{ "reference": "data:xiaohongshu.app_v2.search_notes", "operation": "result", "request_id": "<request_id>", "fields": ["items[].<key>"] }

REST defaults to view: "full"; the MCP server defaults to preview.

next in your dialect

Send X-Beat-Client: mcp or http (default). It changes only how next.call is written:

• http: a complete curl command against https://api.beatapi.io, with Authorization: Bearer $BEATAPI_API_KEY on calls that need a key.
• mcp: {"tool": "capabilities_run", "arguments": {…}}. The BeatAPI MCP server sends this header for you.

next.action is search, inspect, run, status, result or none, and next.note says what the call will return.

Errors

Over MCP, a tool call that reached the gateway is always a tool result: a gateway error comes back with isError: true and the same JSON error envelope as its text, so the agent can read it and correct the call.

For agent platforms that import OpenAPI

https://beatapi.io/agent-openapi.json is a slim OpenAPI document with only these three operations and web search, Bearer authentication and agent-facing descriptions. Import it into a platform that builds tools from OpenAPI. The full contract stays at https://beatapi.io/openapi.json, and the agent guide at https://beatapi.io/skill.md.