> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# Search capabilities (start here)

POST https://api.beatapi.io/v1/capabilities/search
Content-Type: application/json

The entry point to every BeatAPI capability: social media data (小红书 Xiaohongshu,
抖音 Douyin, TikTok, B站 Bilibili, 微博 Weibo, X, Instagram, YouTube and more),
text, image, video and decision (JEV) models, web search and media workflows.
Free, needs no key and never executes anything.

Write `query` the way the user would say it, platform + action, in Chinese or
English: `小红书 搜索笔记`, `抖音 用户作品`, `tiktok user profile`, `video model`.
A whole sentence works; words that match nothing are ignored and listed in
`understood.ignored`. A query that names only a platform (or `group_by: function`)
returns an overview in `groups`; an empty query returns the catalogue map.
Zero matches return `hints` on how to rephrase.

Results are compact cards by default (`view: full` returns complete contracts).
Every reply carries `next`, the exact call to make next — usually Inspect on the
best match. Copy references exactly; never build one.


Reference: https://docs.beatapi.io/api-reference/core/capabilities/search-capabilities

## Request

### Headers

- `X-Beat-Client` (enum, optional, default: http) — Dialect of `next`: `http` (default) writes a curl command, `mcp` writes a capabilities tool call. The BeatAPI MCP server sends `mcp`.
  - Allowed values: `http`, `mcp`

### Body (application/json)

This endpoint expects a CapabilitySearchRequest.

- `query` (string, optional) — What the user wants, as platform + action in their own words, Chinese or English: `小红书 搜索笔记`, `B站 视频评论`, `image model`. Only a platform name returns an overview; empty returns the catalogue map.
- `kind` (enum, optional) — Optional filter. `model`: text, image, video and decision models. `data`: social media and web data. `workflow`: multi-step media jobs.
  - Allowed values: `model`, `data`, `workflow`
- `platform` (string, optional) — Optional platform filter, slug or name: `xiaohongshu` or `小红书`, `douyin` or `抖音`, `tiktok`, `bilibili`, `weibo`, `x`, `instagram`, `youtube`.
- `limit` (integer, optional, default: 5) — Results per page.
- `cursor` (string, optional) — `next_cursor` from the previous page.
- `view` (enum, optional, default: compact) — `compact`: one card per result. `full`: complete contracts; usually Inspect one reference instead.
  - Allowed values: `compact`, `full`
- `group_by` (enum, optional) — `function`: group matches by what they do (search, content, comments, users, trends, feeds, commerce, live).
  - Allowed values: `function`

## Response

### 200

Capability search page

- `data` (CapabilitySearchPage, required)

## Errors

### 400 Bad Request Error

Malformed JSON or a field, value or combination this endpoint does not accept (`bad_request`; the message names the field), or input refused by moderation (`content_policy_violation`). Not retryable unchanged.

- `error` (ErrorError, required) — Structured BeatAPI error. Use `code` (or `retryable`) for program logic and retain `request_id` for support.

## Types

### CapabilitySearchPage

- `object` (enum, required)
  - Allowed values: `capability.list`
- `data` (list of CapabilitySearchPageDataItems, required) — Compact cards by default; complete contracts with `view` full.
- `next_cursor` (string, required) — Empty on the last page.
- `total` (integer, optional)
- `understood` (CapabilitySearchPageUnderstood, optional) — How the query was read. `terms` counted; `ignored` matched nothing.
- `recommended` (CapabilitySearchPageRecommended, optional) — Present on the first page of a specific query (not on an overview or an empty query) — the pick, so a caller can go straight to Run when the inputs are obvious.
- `groups` (list of CapabilityGroup, optional) — Present in overview mode.
- `hints` (list of string, optional) — How to rephrase when nothing matched.
- `next` (CapabilityNext, optional) — The call to make next, in the caller's dialect: an MCP tool call `{tool, arguments}` when the request sent `X-Beat-Client: mcp`, otherwise a complete curl command. Copy it and replace the `<placeholders>`.
- `catalog_features` (list of string, optional)

### ErrorError

Structured BeatAPI error. Use `code` (or `retryable`) for program logic and retain `request_id` for support.

- `code` (enum, required) — Stable machine-readable error code. `unauthorized` is the deprecated name for a 401; since 2026-09-29 a 401 is `missing_api_key` or `invalid_api_key`. Treat a legacy `unauthorized` like `invalid_api_key`.
  - Allowed values: `bad_request`, `missing_api_key`, `invalid_api_key`, `unauthorized`, `forbidden`, `not_found`, `insufficient_credits`, `idempotency_conflict`, `user_concurrency_exceeded`, `rate_limit_exceeded`, `content_policy_violation`, `processing_unavailable`, `processing_failed`, `processing_timeout`, `result_transfer_failed`, `invalid_signature`, `realtime_disabled`, `realtime_capacity_unavailable`, `realtime_session_expired`, `origin_not_allowed`, `invalid_client_secret`, `transport_not_allowed`, `internal_error`
- `message` (string, required) — English sentence that states the cause; for `bad_request` it names the field. Written for people and logs, not for parsing.
- `retryable` (boolean, required) — Whether making the same call again could succeed. Present on every error; branch on it instead of the status code. True for 429, 500 and 503 (rate_limit_exceeded, user_concurrency_exceeded, internal_error, processing_unavailable, processing_timeout, processing_failed, result_transfer_failed, realtime_capacity_unavailable). False for a request, key or balance that must change first (bad_request, content_policy_violation, missing_api_key, invalid_api_key, insufficient_credits, forbidden, not_found, idempotency_conflict, realtime_disabled and the other realtime credential codes).
- `request_id` (string, required) — Correlation ID to retain for BeatAPI support.
- `retry_after_seconds` (integer, optional) — Seconds to wait before retrying. Present on every 429, and on a 503 when the wait is known; the same value is sent in the `Retry-After` header.
- `docs` (string, optional) — The public Skill page that says what to do about an error. Present on errors answered by the capability endpoints (`/v1/capabilities/search`, `/v1/capabilities/inspect`, `/v1/capabilities/run`); absent on every other endpoint.

### CapabilitySearchPageDataItems

### CapabilitySearchPageUnderstood

How the query was read. `terms` counted; `ignored` matched nothing.

- `platforms` (list of string, optional)
- `terms` (list of string, optional)
- `ignored` (list of string, optional)

### CapabilitySearchPageRecommended

Present on the first page of a specific query (not on an overview or an empty query) — the pick, so a caller can go straight to Run when the inputs are obvious.

- `reference` (string, required) — The top result, copied exactly.
- `title` (string, required)
- `readiness` (enum, required)
  - Allowed values: `ready`, `runnable`, `listed`
- `why_match` (CapabilitySearchPageRecommendedWhyMatch, required) — What the ranker understood — the platform it resolved and the terms that counted.
- `missing_inputs` (list of string, required) — The contract's required inputs, in name order; empty when nothing is required.
- `price` (string, optional) — The card's price text, such as `$0.0300` or `from $0.15`.

### CapabilityGroup

- `key` (string, required) — search, content, comments, users, trends, feeds, commerce, live or other; kinds and categories in the catalogue map.
- `label` (string, required)
- `count` (integer, required)
- `examples` (list of CapabilityGroupExamplesItems, required)
- `search` (map from string to any, optional) — Search arguments that list the whole group.

### CapabilityNext

The call to make next, in the caller's dialect: an MCP tool call `{tool, arguments}` when the request sent `X-Beat-Client: mcp`, otherwise a complete curl command. Copy it and replace the `<placeholders>`.

- `action` (enum, required)
  - Allowed values: `search`, `inspect`, `run`, `status`, `result`, `none`
- `call` (CapabilityNextCall, optional)
- `note` (string, optional)

### CapabilityCard

- `reference` (string, required) — Copy exactly into Inspect.
- `kind` (enum, required)
  - Allowed values: `model`, `data`, `workflow`
- `title` (string, required)
- `summary` (string, required)
- `execution` (enum, required)
  - Allowed values: `sync`, `async`
- `readiness` (enum, required)
  - Allowed values: `ready`, `runnable`, `listed`
- `platform` (string, optional)
- `price` (string, optional) — Human-readable price, such as `$0.03 per request`.
- `signature` (string, optional) — One-line input summary, such as `keyword: string (required), page: integer, +3 more`.

### CapabilityContract

- `reference` (string, required) — Stable reference, `kind:id`. Copy it exactly into Inspect and Run.
- `kind` (enum, required)
  - Allowed values: `model`, `data`, `workflow`
- `id` (string, required)
- `version` (string, required)
- `status` (string, required)
- `title` (string, required)
- `description` (string, required)
- `execution` (CapabilityContractExecution, required)
- `versions` (CapabilityContractVersions, required)
- `validation` (CapabilityContractValidation, required)
- `readiness` (enum, optional) — `ready`: runnable, output schema and price published. `runnable`: runs through Run and the input is documented, but the output shape is not published. `listed`: not runnable through Run, or the input is undocumented.
  - Allowed values: `ready`, `runnable`, `listed`
- `categories` (list of string, optional)
- `platforms` (list of string, optional)
- `entities` (list of string, optional)
- `operations` (list of string, optional)
- `tags` (list of string, optional) — Words callers use for this capability; searchable.
- `input_schema` (map from string to any, optional) — JSON Schema of Run `input`.
- `output_schema` (map from string to any, optional) — JSON Schema of the result
- `schema_hash` (string, optional) — Sixteen hex characters fingerprinting `input_schema` and `output_schema` together. Cache a contract by it and re-inspect only when a later reply shows a different hash.
- `pricing` (map from string to any, optional) — Current retail price of one run.
- `pagination` (map from string to any, optional)
- `limits` (map from string to any, optional)
- `errors` (map from string to any, optional)
- `documentation` (CapabilityContractDocumentation, optional) — First-party usage guidance. Detailed Run examples appear here for selected data capabilities and are omitted from Search responses.

### CapabilitySearchPageRecommendedWhyMatch

What the ranker understood — the platform it resolved and the terms that counted.

- `platforms` (list of string, optional)
- `terms` (list of string, optional)

### CapabilityGroupExamplesItems

- `reference` (string, required)
- `summary` (string, required)
- `price` (string, optional)

### CapabilityNextCall

### CapabilityContractExecution

- `mode` (enum, required) — `sync` returns the result from Run; `async` returns a task to poll with operation status.
  - Allowed values: `sync`, `async`
- `status_supported` (boolean, required)
- `result_location` (string, optional)

### CapabilityContractVersions

- `catalog_version` (string, required)
- `contract_version` (string, required)
- `price_version` (string, optional)

### CapabilityContractValidation

- `state` (enum, required)
  - Allowed values: `verified`, `partial`, `unknown`
- `verified_at` (string, optional)
- `evidence` (list of string, optional)

### CapabilityContractDocumentation

First-party usage guidance. Detailed Run examples appear here for selected data capabilities and are omitted from Search responses.

- `url` (string, required)
- `run_example` (map from string to any, optional)
- `notes` (list of string, optional)

### CapabilityNextCall1

- `tool` (enum, required)
  - Allowed values: `capabilities_search`, `capabilities_inspect`, `capabilities_run`
- `arguments` (map from string to any, required)

## Examples

**Request**

```json
{
  "query": "小红书 搜索笔记"
}
```

**Response**

```json
{
  "data": {
    "object": "capability.list",
    "data": [
      {
        "execution": "sync",
        "kind": "model",
        "platform": "string",
        "price": "string",
        "readiness": "ready",
        "reference": "string",
        "signature": "string",
        "summary": "string",
        "title": "string"
      }
    ],
    "next_cursor": "string",
    "total": 1,
    "understood": {
      "platforms": [
        "string"
      ],
      "terms": [
        "string"
      ],
      "ignored": [
        "string"
      ]
    },
    "recommended": {
      "reference": "string",
      "title": "string",
      "readiness": "ready",
      "why_match": {
        "platforms": [
          "string"
        ],
        "terms": [
          "string"
        ]
      },
      "missing_inputs": [
        "string"
      ],
      "price": "string"
    },
    "groups": [
      {
        "key": "string",
        "label": "string",
        "count": 1,
        "examples": [
          {
            "reference": "string",
            "summary": "string",
            "price": "string"
          }
        ],
        "search": {}
      }
    ],
    "hints": [
      "string"
    ],
    "next": {
      "action": "search",
      "call": "string",
      "note": "string"
    },
    "catalog_features": [
      "string"
    ]
  }
}
```

**SDK Code**

```python Capabilities_searchCapabilities_example
import requests

url = "https://api.beatapi.io/v1/capabilities/search"

payload = { "query": "小红书 搜索笔记" }
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Capabilities_searchCapabilities_example
const url = 'https://api.beatapi.io/v1/capabilities/search';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"query":"小红书 搜索笔记"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Capabilities_searchCapabilities_example
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.beatapi.io/v1/capabilities/search"

	payload := strings.NewReader("{\n  \"query\": \"小红书 搜索笔记\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Capabilities_searchCapabilities_example
require 'uri'
require 'net/http'

url = URI("https://api.beatapi.io/v1/capabilities/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"query\": \"小红书 搜索笔记\"\n}"

response = http.request(request)
puts response.read_body
```

```java Capabilities_searchCapabilities_example
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.beatapi.io/v1/capabilities/search")
  .header("Content-Type", "application/json")
  .body("{\n  \"query\": \"小红书 搜索笔记\"\n}")
  .asString();
```

```php Capabilities_searchCapabilities_example
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.beatapi.io/v1/capabilities/search', [
  'body' => '{
  "query": "小红书 搜索笔记"
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp Capabilities_searchCapabilities_example
using RestSharp;

var client = new RestClient("https://api.beatapi.io/v1/capabilities/search");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"query\": \"小红书 搜索笔记\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Capabilities_searchCapabilities_example
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = ["query": "小红书 搜索笔记"] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.beatapi.io/v1/capabilities/search")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```