> 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.

# Inspect one capability contract

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

Returns the complete contract for one reference: `input_schema` (required fields,
types, limits), `pricing`, `execution.mode` (`sync` answers in the response,
`async` returns a task), `readiness` and `next`, a Run call pre-filled with the
reference and a `<placeholder>` for each required input. Free and keyless.

`readiness`: `ready` — input, output and price are published; `runnable` — it runs
through Run, but the output shape is not published, so read what you need from the
result; `listed` — it cannot run through Run (`next.note` says why); search for an
alternative.

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

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

## 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 an object.

- `reference` (string, required) — A reference copied exactly from Search results or `suggestions`, such as `data:xiaohongshu.app_v2.search_notes` or `model:jev-1.13-free`.

## Response

### 200

Capability contract with the next call

- `data` (V1CapabilitiesInspectPostResponsesContentApplicationJsonSchemaData, 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.

### 404 Not Found Error

Unknown capability reference. `suggestions` lists the closest published references and `next` inspects the best of them.

- `error` (V1CapabilitiesInspectPostResponsesContentApplicationJsonSchemaError, required)

## Types

### V1CapabilitiesInspectPostResponsesContentApplicationJsonSchemaData

- `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` (V1CapabilitiesInspectPostResponsesContentApplicationJsonSchemaDataExecution, required)
- `versions` (V1CapabilitiesInspectPostResponsesContentApplicationJsonSchemaDataVersions, required)
- `validation` (V1CapabilitiesInspectPostResponsesContentApplicationJsonSchemaDataValidation, 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` (V1CapabilitiesInspectPostResponsesContentApplicationJsonSchemaDataDocumentation, optional) — First-party usage guidance. Detailed Run examples appear here for selected data capabilities and are omitted from Search responses.
- `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>`.

### 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.

### V1CapabilitiesInspectPostResponsesContentApplicationJsonSchemaError

- `code` (enum, required)
  - Allowed values: `not_found`
- `message` (string, required)
- `retryable` (boolean, required)
- `request_id` (string, required)
- `suggestions` (list of string, optional)
- `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>`.

### V1CapabilitiesInspectPostResponsesContentApplicationJsonSchemaDataExecution

- `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)

### V1CapabilitiesInspectPostResponsesContentApplicationJsonSchemaDataVersions

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

### V1CapabilitiesInspectPostResponsesContentApplicationJsonSchemaDataValidation

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

### V1CapabilitiesInspectPostResponsesContentApplicationJsonSchemaDataDocumentation

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)

### 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)

### CapabilityNextCall

### CapabilityNextCall1

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

## Examples

**Request**

```json
{
  "reference": "data:xiaohongshu.app_v2.search_notes"
}
```

**Response**

```json
{
  "data": {
    "reference": "string",
    "kind": "model",
    "id": "string",
    "version": "string",
    "status": "string",
    "title": "string",
    "description": "string",
    "execution": {
      "mode": "sync",
      "status_supported": true,
      "result_location": "string"
    },
    "versions": {
      "catalog_version": "string",
      "contract_version": "string",
      "price_version": "string"
    },
    "validation": {
      "state": "verified",
      "verified_at": "string",
      "evidence": [
        "string"
      ]
    },
    "readiness": "ready",
    "categories": [
      "string"
    ],
    "platforms": [
      "string"
    ],
    "entities": [
      "string"
    ],
    "operations": [
      "string"
    ],
    "tags": [
      "string"
    ],
    "input_schema": {},
    "output_schema": {},
    "schema_hash": "3f9c2a7d1b0e4a65",
    "pricing": {},
    "pagination": {},
    "limits": {},
    "errors": {},
    "documentation": {
      "url": "string",
      "run_example": {},
      "notes": [
        "string"
      ]
    },
    "next": {
      "action": "search",
      "call": "string",
      "note": "string"
    }
  }
}
```

**SDK Code**

```python Capabilities_inspectCapability_example
import requests

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

payload = { "reference": "data:xiaohongshu.app_v2.search_notes" }
headers = {"Content-Type": "application/json"}

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

print(response.json())
```

```javascript Capabilities_inspectCapability_example
const url = 'https://api.beatapi.io/v1/capabilities/inspect';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"reference":"data:xiaohongshu.app_v2.search_notes"}'
};

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

```go Capabilities_inspectCapability_example
package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"reference\": \"data:xiaohongshu.app_v2.search_notes\"\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_inspectCapability_example
require 'uri'
require 'net/http'

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

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  \"reference\": \"data:xiaohongshu.app_v2.search_notes\"\n}"

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

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

HttpResponse<String> response = Unirest.post("https://api.beatapi.io/v1/capabilities/inspect")
  .header("Content-Type", "application/json")
  .body("{\n  \"reference\": \"data:xiaohongshu.app_v2.search_notes\"\n}")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.beatapi.io/v1/capabilities/inspect', [
  'body' => '{
  "reference": "data:xiaohongshu.app_v2.search_notes"
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

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

```csharp Capabilities_inspectCapability_example
using RestSharp;

var client = new RestClient("https://api.beatapi.io/v1/capabilities/inspect");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"reference\": \"data:xiaohongshu.app_v2.search_notes\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Capabilities_inspectCapability_example
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = ["reference": "data:xiaohongshu.app_v2.search_notes"] as [String : Any]

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

let request = NSMutableURLRequest(url: NSURL(string: "https://api.beatapi.io/v1/capabilities/inspect")! 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()
```