ChatGPT ↗
Claude ↗This page documents the canonical HTTP contract for this endpoint.
The server pins its configured model and requires a successful paired MCP tool call; model and require_tool_call request values do not override those safeguards. This HTTP adapter uses a process-local rate limiter, defaulting to 2 requests per user per minute and 10 per organization per minute (environment-configurable), and bills source credits. response_schema is a field-name-to-type map (for example, {"city":"string"}), not a JSON Schema document; its validation applies to parsed_output. Attachments must already be stored PDFs authorized to the caller's organization. The HTTP request runs synchronously; it is not a durable asynchronous job. An optional request invocation_id is used for invocation/capture correlation and does not deduplicate repeated provider calls. The response example abbreviates the server-selected model, allowed-operation list, tool output, usage and raw provider response.
Body parameters
promptrequiredstring
Research instructions; 1–20,000 characters.
row_context· optionalobject
JSON context for the research request.
attachments· optionalarray
Up to 10 previously stored server PDFs. Each item requires id (1–200 chars), filename (1–500 chars), kind=pdf, storageState=server; optional mediaType (max 200 chars) and sizeBytes (nonnegative integer).
seller_identity· optionalobject
Optional companyName and companyDomain context.
run_metadata· optionalobject
response_schema· optionalobject
Non-empty response-schema field map used to validate parsed_output when supplied.
reasoning_effort· optionalstring
low, medium, or high.
max_tool_calls· optionalinteger
1–25; safety ceiling, default 25.
max_output_tokens· optionalinteger
256–32,000; default 32,000.
profile· optionalstring
Deprecated compatibility field, max 80 characters; does not select the server-side profile.
model· optionalstring
Accepted for compatibility but ignored; server chooses the model.
require_tool_call· optionalboolean
Accepted for compatibility but server always requires a successful tool call.
invocation_id· optionalstring
Optional invocation/capture identifier, 1–240 characters; it does not make the provider call idempotent.
| Name | Type | Description |
|---|---|---|
| promptrequired | string | Research instructions; 1–20,000 characters. |
| row_context | object | JSON context for the research request. |
| attachments | array | Up to 10 previously stored server PDFs. Each item requires id (1–200 chars), filename (1–500 chars), kind=pdf, storageState=server; optional mediaType (max 200 chars) and sizeBytes (nonnegative integer). |
| seller_identity | object | Optional companyName and companyDomain context. |
| run_metadata | object | - |
| response_schema | object | Non-empty response-schema field map used to validate parsed_output when supplied. |
| reasoning_effort | string | low, medium, or high. |
| max_tool_calls | integer | 1–25; safety ceiling, default 25. |
| max_output_tokens | integer | 256–32,000; default 32,000. |
| profile | string | Deprecated compatibility field, max 80 characters; does not select the server-side profile. |
| model | string | Accepted for compatibility but ignored; server chooses the model. |
| require_tool_call | boolean | Accepted for compatibility but server always requires a successful tool call. |
| invocation_id | string | Optional invocation/capture identifier, 1–240 characters; it does not make the provider call idempotent. |
Errors
| Status | Meaning |
|---|---|
| 400 | Missing actor context, provider execution failure, unsuccessful research call, missing successful tool call, or invalid response output. |
| 401 | Missing or invalid authentication. |
| 403 | Developer key lacks search:run. |
| 422 | Request fields or limits fail model validation. |
| 429 | Per-user or per-organization rate limit reached. |