Skip to navigation
BeatAPICoreCapabilities

Run a capability, poll a task or fetch a result

Runs an inspected capability with your API key; a start spends balance at the inspected price. Copy next from Inspect and fill the placeholders.

  • operation: start (default): input follows the inspected input_schema; unknown fields inside input are rejected. Synchronous kinds — social and web data, text models, JEV — return the result in the response. Asynchronous kinds — image, video, workflows and data:web.research (30 s to 3 min) — return {data: task, next}; repeat next, an operation: status call with task_id, until succeeded or failed. A finished research task carries its result in data.output; a failed one is not charged.
  • Text models: {"reference":"model:<id>","input":{"input":"<prompt>"}} returns {object:"text.result", model, status, output_text, usage, request_id}. input.input is a string or a messages array; instructions, max_output_tokens and temperature are optional.
  • JEV (model:jev-1.13, model:jev-1.13-free): {"input":{"state":…,"questions":…}} returns {id, model, answers, usage}.
  • Result views: view: preview lifts the result’s main list to items (the first max_items, default 10, each element trimmed inside) with items_path and items_total, shortens long strings and marks the reply truncated with a result_ref; fields keeps only the listed paths, items[].<key> for keys of each list element. REST defaults to full; the BeatAPI MCP server defaults to preview. A status poll takes the same view.
  • operation: result with request_id returns a finished result again, free, for one hour, with any view, fields or max_items.

Send a unique idempotency_key per task as a top-level field (or the Idempotency-Key header) and reuse it only to retry the same start. An unknown reference returns 404 with suggestions.

Authentication

AuthorizationBearer

Send your API key as Authorization: Bearer <BEATAPI_API_KEY>.

Headers

X-Beat-ClientenumOptionalDefaults to http

Dialect of next: http (default) writes a curl command, mcp writes a capabilities tool call. The BeatAPI MCP server sends mcp.

Allowed values:

Request

This endpoint expects an object.
referencestringRequiredformat: "^(model|data|workflow):.+$"
The inspected reference
operationenumOptionalDefaults to start

start: run it. status: poll an async task (needs task_id; takes view, max_items and fields like start). result: fetch a finished result again, free within one hour (needs request_id).

Allowed values:
inputmap from strings to anyOptional

For start: the input, following the inspected input_schema. Text models: {"input": "<prompt or messages>"} with optional instructions, max_output_tokens, temperature. JEV: {"state": …, "questions": …}.

task_idstringOptional

For status: the task id an async start returned.

request_idstringOptional

For result: the request_id a sync start returned.

viewenumOptional

full (REST default): the whole result. preview: the result’s main list lifted to items (the first max_items elements, each trimmed inside) with items_path and items_total, long strings shortened, truncated and result_ref reported.

Allowed values:
max_itemsintegerOptional1-50

With preview: elements kept in items (default 10).

fieldslist of stringsOptional

Keep only these paths. Paths starting items[] are read from each element of the result’s list and returned as items, such as items[].title; other paths are dotted from the root, [] walks an array.

idempotency_keystringOptional<=255 characters

Unique per task, a top-level field next to reference and input (or the Idempotency-Key header); reuse only to retry the same start.

Response

Synchronous result, stored result or task status
objectstringOptional
idstringOptional
Task id for async kinds.
statusstringOptional

Task status: poll until succeeded or failed.

request_idstringOptional

Pass to operation: result to fetch the stored result.

output_textstringOptional
Text models only.
answersmap from strings to anyOptional
JEV only.
itemslist of anyOptional

With preview or items[] fields: the elements of the result’s main list.

items_pathstringOptional

Where the list sits in the full result, such as data.data.items or results.

items_totalintegerOptional
Elements in the full list.
items_shownintegerOptional

Elements in items.

truncatedbooleanOptional
True when a preview cut the result.
result_refobjectOptional
The stored full result, when a view left anything out.
usagemap from strings to anyOptional
dataanyOptional
The result payload or the wrapped object.

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error