{ "components": { "schemas": { "AnthropicCountTokensRequest": { "description": "`POST /v1/messages/count_tokens`. Free and unmetered.", "properties": { "messages": { "description": "The conversation to count, in Messages shape.", "items": { "additionalProperties": true, "type": "object" }, "title": "Messages", "type": "array" }, "model": { "description": "A catalog alias or a real Claude model name. A concrete Claude name gives that model's exact count; anything else is counted with the platform's current Claude counting model.", "title": "Model", "type": "string" }, "system": { "anyOf": [ { "type": "string" }, { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "System prompt, counted too.", "title": "System" }, "tools": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Tool definitions, counted too.", "title": "Tools" } }, "required": [ "model", "messages" ], "title": "AnthropicCountTokensRequest", "type": "object" }, "AnthropicError": { "properties": { "deny_detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The specific cause behind a 403: `model_restricted` when an administrator in your organization restricted the model. Same value as `X-MindsHub-Deny-Detail`. Absent otherwise.", "title": "Deny Detail" }, "message": { "description": "Human-readable explanation of what went wrong.", "title": "Message", "type": "string" }, "type": { "description": "Anthropic's error class for the HTTP status: `invalid_request_error` (400, and 402), `authentication_error` (401), `permission_error` (403), `not_found_error` (404), `request_too_large` (413), `rate_limit_error` (429), `api_error` (500, 503), `overloaded_error` (529).", "title": "Type", "type": "string" } }, "required": [ "type", "message" ], "title": "AnthropicError", "type": "object" }, "AnthropicErrorEnvelope": { "description": "The error body on `/v1/messages` and `/v1/messages/count_tokens`. No `code` field; read the HTTP status.", "properties": { "error": { "$ref": "#/components/schemas/AnthropicError" }, "reset_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO-8601 instant the limit resets, on an allowance or free-serving 429. Same value as `X-MindsHub-Reset-At`. Absent otherwise, and absent on an allowance 429 when the organization has no included allowance.", "title": "Reset At" }, "type": { "default": "error", "description": "Always `error`.", "title": "Type", "type": "string" } }, "required": [ "error" ], "title": "AnthropicErrorEnvelope", "type": "object" }, "AnthropicMessage": { "description": "A Messages API response, as Anthropic shapes it.", "properties": { "content": { "description": "Content blocks: `text`, `tool_use`, and on thinking models a leading `thinking` block with a `signature`. Don't assume the first block is text.", "items": { "additionalProperties": true, "type": "object" }, "title": "Content", "type": "array" }, "id": { "description": "`msg_…`.", "title": "Id", "type": "string" }, "model": { "description": "The model that served. `mindshub_air` and `mindshub_blaze` echo the string you sent.", "title": "Model", "type": "string" }, "role": { "default": "assistant", "title": "Role", "type": "string" }, "stop_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`end_turn`, `tool_use`, `max_tokens`, `stop_sequence`, or `refusal`.", "title": "Stop Reason" }, "stop_sequence": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The matched stop sequence, on Claude-family targets.", "title": "Stop Sequence" }, "type": { "default": "message", "title": "Type", "type": "string" }, "usage": { "$ref": "#/components/schemas/AnthropicUsage" } }, "required": [ "id", "model", "content", "usage" ], "title": "AnthropicMessage", "type": "object" }, "AnthropicMessagesRequest": { "additionalProperties": true, "description": "An Anthropic ``POST /v1/messages`` request body.\n\nDeliberately permissive (``extra=\"allow\"``, loose block typing): Anthropic\nadds request fields and content-block types over time, and an unknown\nfield must degrade to \"ignored\", never a 422 — Claude Code treats\nvalidation failures as hard errors. Field semantics are enforced by the\ntranslation layer (``minds.requests.anthropic_compat``), not the schema.\n\nField-by-field support — what is forwarded, adapted, or ignored — is\ndocumented in one place, ``minds.requests.anthropic_compat.PARAM_SUPPORT``,\nrather than restated here where it would drift.", "properties": { "cache_control": { "description": "**Accepted and ignored.** The top-level auto-caching form is not read. Block-level cache_control on system blocks, text/tool_result blocks and tool definitions IS honoured on Claude-family targets, and cache usage is reported in the response's usage." }, "container": { "description": "**Accepted and ignored.** The code-execution tool is not offered here." }, "inference_geo": { "description": "**Accepted and ignored.** Inference geography is a property of the upstream account, not of a request." }, "max_tokens": { "description": "**Per model.** Clamped to the resolved model's real output ceiling, and up to its floor where the backend enforces one; either adjustment is named in X-MindsHub-Clamped-Params.", "title": "Max Tokens", "type": "integer" }, "mcp_servers": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "**Adapted.** Remote MCP servers, Anthropic's shape (type url, url, name, authorization_token). Each must be referenced by exactly one mcp_toolset in tools, as on Anthropic; otherwise 400. Runs on the target's native connector (Claude, GPT); the authorization token is forwarded upstream and never stored or traced. This dialect has no approval concept, so tools run as the model calls them on every target.", "title": "Mcp Servers" }, "messages": { "description": "**Per model.** Text, image, tool_use, tool_result and thinking blocks all round-trip to a Claude-family target, where is_error and block-level cache_control survive too. Against another provider each block is rebuilt into that transport's own vocabulary, and anything it has no field for — an Anthropic-only block type, a cache_control or citations marker — is dropped and named in X-MindsHub-Dropped-Content rather than forwarded into a 400.", "items": { "additionalProperties": true, "type": "object" }, "title": "Messages", "type": "array" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "**Accepted and ignored.** Accepted and not read.", "title": "Metadata" }, "model": { "description": "**Adapted.** A real Claude model id is family-mapped to the catalog alias serving that family (claude-sonnet-5 -> sonnet); a bare alias resolves as-is. The response names the model that ran; `mindshub_air` and `mindshub_blaze` echo the id the caller sent.", "title": "Model", "type": "string" }, "output_config": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "**Adapted.** Both halves are honoured and travel separately: 'effort' is clamped onto the resolved model's published ladder, and 'format' becomes a schema constraint each provider renders in its own shape. A model that cannot constrain its output at all is a 400, not prose.", "title": "Output Config" }, "service_tier": { "description": "**Accepted and ignored.** One serving tier; nothing to select." }, "stop_sequences": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "**Per model.** Forwarded where the transport has a field for them (the OpenAI Responses transport does not). A sequence that fires is reported as stop_reason 'stop_sequence' with the matched string, on Anthropic-wire targets.", "title": "Stop Sequences" }, "stream": { "default": false, "description": "**Forwarded.** Produces the standard Anthropic event sequence. See the module docstring for the two documented divergences (ping is sent once, and input tokens are 0 on message_start for non-Claude targets).", "title": "Stream", "type": "boolean" }, "system": { "anyOf": [ { "type": "string" }, { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "**Per model.** String or content blocks. Blocks pass through verbatim so cache_control markers reach a Claude-family target; against another provider they are reconciled like any other content, and what that transport cannot carry is named in X-MindsHub-Dropped-Content.", "title": "System" }, "temperature": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "**Per model.** Dropped on models that reject sampling params — which is every current Claude 5 model — and named in X-MindsHub-Dropped-Params.", "title": "Temperature" }, "thinking": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "**Per model.** Forwarded to models that accept a thinking config, budget_tokens included. Reasoning bills as output tokens. Thinking blocks come back on both streamed and non-streamed turns, so a client can replay them.", "title": "Thinking" }, "tool_choice": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "**Adapted.** auto/any/none/tool all map. disable_parallel_tool_use is honoured, including on transports that spell it as a positive parallel_tool_calls. A forced choice a model cannot honour is downgraded to auto rather than refused (ENG-1095).", "title": "Tool Choice" }, "tools": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "**Adapted.** Client tools (input_schema) translate to every provider, strict included. Anthropic's hosted web_search*/web_fetch* map onto the platform's own web search where the target supports it. An mcp_toolset (with its mcp_servers entry) maps onto the target's own remote-MCP connector where it has one and is dropped, named in X-MindsHub-Dropped-Params, where it does not; enabled/default_config.enabled are honoured, defer_loading is dropped. Other server tools (computer_*, bash_*, text_editor_*, code_execution, memory) have no cross-provider meaning and are dropped. A tool schema is rewritten where the target accepts only a subset of JSON Schema; both kinds of change are named in X-MindsHub-Dropped-Content.", "title": "Tools" }, "top_k": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "**Per model.** As temperature.", "title": "Top K" }, "top_p": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "**Per model.** As temperature. On a Claude model that still takes sampling params, sending it with temperature drops top_p (Anthropic rejects the pair) and names it in X-MindsHub-Dropped-Params; top_p alone is forwarded.", "title": "Top P" } }, "required": [ "model", "messages", "max_tokens" ], "title": "AnthropicMessagesRequest", "type": "object" }, "AnthropicUsage": { "properties": { "cache_creation_input_tokens": { "description": "Prompt tokens written to the provider's cache.", "title": "Cache Creation Input Tokens", "type": "integer" }, "cache_read_input_tokens": { "description": "Prompt tokens read from the provider's cache.", "title": "Cache Read Input Tokens", "type": "integer" }, "input_tokens": { "description": "Uncached prompt tokens. The three input fields partition the prompt.", "title": "Input Tokens", "type": "integer" }, "output_tokens": { "description": "Generated tokens, thinking included.", "title": "Output Tokens", "type": "integer" } }, "required": [ "input_tokens", "output_tokens", "cache_creation_input_tokens", "cache_read_input_tokens" ], "title": "AnthropicUsage", "type": "object" }, "BaseModel": { "properties": {}, "title": "BaseModel", "type": "object" }, "ChatCompletion": { "properties": { "choices": { "description": "Exactly one choice.", "items": { "$ref": "#/components/schemas/Choice" }, "title": "Choices", "type": "array" }, "created": { "title": "Created", "type": "integer" }, "id": { "title": "Id", "type": "string" }, "model": { "description": "The model that served, which can be sent back as-is. `mindshub_air` and `mindshub_blaze` return their own alias instead.", "title": "Model", "type": "string" }, "object": { "default": "chat.completion", "title": "Object", "type": "string" }, "system_fingerprint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Provider fingerprint where one is reported.", "title": "System Fingerprint" }, "usage": { "anyOf": [ { "$ref": "#/components/schemas/Usage" }, { "type": "null" } ], "description": "Token usage; see the Usage schema." } }, "required": [ "model", "choices" ], "title": "ChatCompletion", "type": "object" }, "ChatCompletionChunk": { "properties": { "choices": { "description": "Empty on the final usage-bearing chunk when stream_options.include_usage is set.", "items": { "$ref": "#/components/schemas/StreamChoice" }, "title": "Choices", "type": "array" }, "created": { "title": "Created", "type": "integer" }, "id": { "title": "Id", "type": "string" }, "model": { "description": "The model that served, which can be sent back as-is. `mindshub_air` and `mindshub_blaze` return their own alias instead.", "title": "Model", "type": "string" }, "object": { "default": "chat.completion.chunk", "title": "Object", "type": "string" }, "system_fingerprint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Provider fingerprint where one is reported.", "title": "System Fingerprint" } }, "required": [ "model", "choices" ], "title": "ChatCompletionChunk", "type": "object" }, "ChatCompletionRequestMetadata": { "properties": { "enable_charting": { "default": false, "description": "Whether to enable charting for the request", "title": "Enable Charting", "type": "boolean" }, "mdb_completions_session_id": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "null" } ], "description": "Session ID for the request", "title": "Mdb Completions Session Id" } }, "title": "ChatCompletionRequestMetadata", "type": "object" }, "ChatCompletionsRequest": { "additionalProperties": true, "description": "The inbound `/v1/chat/completions` body.\n\n``extra=\"allow\"``, matching both sibling lanes\n(:class:`~minds.requests.anthropic_messages_request.AnthropicMessagesRequest`,\n:class:`~minds.requests.openai_responses_request.OpenAIResponsesRequest`).\nThis lane used pydantic's ``ignore`` default until ENG-2112, which is a\nquieter failure than it looks: an undeclared field is discarded before any\ncode runs, so it is not merely unsupported but *unobservable* — nothing can\nlog it, report it, or notice it arrived. Every param OpenAI defines today is\ndeclared below; ``allow`` is for the one it adds tomorrow.", "properties": { "audio": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "**Accepted and ignored.** As modalities.", "title": "Audio" }, "frequency_penalty": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "**Per model.** As seed.", "title": "Frequency Penalty" }, "function_call": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "**Adapted.** Translated into `tool_choice`; an unrecognized string is dropped rather than forwarded into a provider 400. Sending `tools` alongside either legacy field is read as a modern request, and answered in the modern shape.", "title": "Function Call" }, "functions": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "description": "**Adapted.** OpenAI's pre-`tools` spelling, deprecated by OpenAI and still served by them. Honoured in all four places they switch: the request becomes `tools`, a replayed assistant.function_call and 'function' role become tool_calls and a 'tool' message, and the answer comes back as message.function_call with finish_reason 'function_call' on both the JSON and SSE paths. Only the first call of a multi-call turn is representable. See minds/requests/legacy_functions.py.", "title": "Functions" }, "logit_bias": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "**Accepted and ignored.** As logprobs. Reported as a drop.", "title": "Logit Bias" }, "logprobs": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "**Accepted and ignored.** No transport here returns log probabilities: they are Chat Completions fields, and the shape serving the GPT and Grok families is the Responses API. Reported as a drop unless explicitly false.", "title": "Logprobs" }, "max_completion_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "**Adapted.** OpenAI's newer spelling of max_tokens and wins over it when both are set to positive values. A value of 0 is falsy here and falls through to max_tokens.", "title": "Max Completion Tokens" }, "max_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "**Per model.** Clamped down to the resolved model's output ceiling and up to the transport's floor; either is named in X-MindsHub-Clamped-Params. Above the 131,072 admission ceiling the request is refused with `max_tokens_exceeded` before a provider is touched.", "title": "Max Tokens" }, "messages": { "description": "**Adapted.** system/user/assistant/tool all round-trip, and `developer` is read as `system`. Text and image_url content parts translate to every provider; `file` and `input_audio` parts do not (Milestone 4). `name` survives only to Moonshot, and as the tool-name fallback on Gemini. `hosted_tool_calls` is an internal carrier for the other two lanes' replayed remote-MCP records and is ignored here.", "items": { "$ref": "#/components/schemas/Message-Input" }, "title": "Messages", "type": "array" }, "metadata": { "anyOf": [ { "$ref": "#/components/schemas/ChatCompletionRequestMetadata" }, { "type": "null" } ], "description": "**Accepted and ignored.** Accepted and not read. Must be an object if present, so a string is a 400." }, "modalities": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "**Accepted and ignored.** Text only; audio is Milestone 4. Reported as a drop.", "title": "Modalities" }, "model": { "description": "**Adapted.** An alias from GET /v1/models resolves to a concrete provider model. The response names the model that served, which can be sent back as-is (it resolves to the alias serving that model, not to a pin); `mindshub_air` and `mindshub_blaze` return their own alias instead. The deprecated `latest:` spelling still resolves.", "title": "Model", "type": "string" }, "n": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "**Accepted and ignored.** There is always exactly one choice. Reported in X-MindsHub-Dropped-Params unless it was 1, which is what we do.", "title": "N" }, "parallel_tool_calls": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "**Per model.** Honoured, including on the Anthropic wire, which spells it inverted inside tool_choice. Gemini cannot express it and declares it unsupported, so the drop is named.", "title": "Parallel Tool Calls" }, "prediction": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "**Accepted and ignored.** Predicted outputs are not offered. Reported as a drop.", "title": "Prediction" }, "presence_penalty": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "**Per model.** As seed.", "title": "Presence Penalty" }, "prompt_cache_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "**Accepted and ignored.** Cache routing is derived from the request's own stable prefix, which is more reliable than a key a caller has to keep consistent themselves.", "title": "Prompt Cache Key" }, "prompt_cache_retention": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "**Accepted and ignored.** Retention is the upstream provider's.", "title": "Prompt Cache Retention" }, "reasoning_effort": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "**Per model.** Clamped onto the resolved model's published ladder rather than dropped — with no level on the request the provider applies its own, which sits near the top. An unrecognized level fits no rung, so it falls back to the model's published `default_reasoning_effort` clamped onto that ladder, and is reported as a clamp naming the category `other` rather than the value sent; it is dropped only where the model publishes no default. A model that publishes a default and an empty ladder is pinned: every request runs at that level and a level sent is replaced by it (`mindshub_air`). Kimi reasons internally with no adjustable level, so the transport declares it unsupported.", "title": "Reasoning Effort" }, "response_format": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "**Per model.** json_schema and json_object both parse; each transport renders the schema in its own shape. The ONE param that raises rather than being dropped when a model cannot honour it (CONTRACT_PARAMS): prose handed to a caller who will json.loads() it is a different kind of answer, not a differently-flavored one. json_object is a 400 on the Anthropic wire, which has no schema-less JSON mode.", "title": "Response Format" }, "safety_identifier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "**Accepted and ignored.** As user.", "title": "Safety Identifier" }, "seed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "**Per model.** Reaches Gemini and Moonshot, the only two transports with a field for it. Never a reproducibility guarantee even there.", "title": "Seed" }, "service_tier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "**Accepted and ignored.** One serving tier; nothing to select. The response echoes `default`.", "title": "Service Tier" }, "stop": { "anyOf": [ { "type": "string" }, { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "**Per model.** Forwarded where the transport has a stop-sequence field; the OpenAI Responses shape, which serves the GPT and Grok families here, does not. Reported under the internal name `stop_sequences`, not `stop`.", "title": "Stop" }, "store": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "**Accepted and ignored.** Chat completions are not stored and there is no retrieval endpoint for them. `/v1/responses` does store, and defaults to it.", "title": "Store" }, "stream": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": false, "description": "**Forwarded.** SSE `chat.completion.chunk` frames terminated by `[DONE]`. Null-valued keys are omitted rather than sent as null, so non-terminal chunks carry no `finish_reason` key.", "title": "Stream" }, "stream_options": { "anyOf": [ { "$ref": "#/components/schemas/StreamOptions" }, { "type": "null" } ], "description": "**Adapted.** `include_usage` is honoured; other keys are ignored. Never reaches a provider — it shapes our own response — so no model can fail to support it. Kimi streams end with a usage chunk whether or not it was asked for." }, "temperature": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "**Per model.** Dropped on models that reject sampling params — every current Claude 5 model, Gemini 3.x, and the GPT 5.6/5.3-codex line — and named in X-MindsHub-Dropped-Params.", "title": "Temperature" }, "tool_choice": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "**Adapted.** auto/required/none/named all map. A forced choice a model cannot honour is downgraded to `auto` rather than refused (ENG-1095), and `none` is honoured by dropping the tools on transports with no word for it — both reported in X-MindsHub-Clamped-Params.", "title": "Tool Choice" }, "tools": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "description": "**Adapted.** Function tools translate to every provider, `strict` included. The platform's own `web_search`/`fetch` entries map onto each provider's hosted search, or our external loop, and are dropped where the target has neither. An OpenAI-shaped `mcp` entry (MindsHub extension: Chat Completions itself has none) runs on the target's own remote-MCP connector; this lane cannot hand back an approval request, so only tools with `require_approval: \"never\"` run and the rest are named in X-MindsHub-Dropped-Params. The answer reflects the tool output; the body has no slot for the calls.", "title": "Tools" }, "top_k": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "**Per model.** A MindsHub extension, not an OpenAI parameter. Forwarded where the transport has it; the OpenAI Responses shape does not, so it is always dropped on the GPT and Grok families and named in X-MindsHub-Dropped-Params.", "title": "Top K" }, "top_logprobs": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "**Accepted and ignored.** As logprobs.", "title": "Top Logprobs" }, "top_p": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "**Per model.** As temperature. On a Claude model that still takes sampling params, sending it with temperature drops top_p (Anthropic rejects the pair) and names it in X-MindsHub-Dropped-Params; top_p alone is forwarded.", "title": "Top P" }, "user": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "**Accepted and ignored.** Requests are attributed by API key and the headers the edge supplies. Not reported as a drop: nothing about the answer changes.", "title": "User" }, "verbosity": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "**Per model.** Rides `text.verbosity` on the OpenAI Responses transport, the only one that has it; dropped and named everywhere else.", "title": "Verbosity" }, "web_search_options": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "**Adapted.** Read as the platform's own `{'type': 'web_search'}` tool entry, so it enables hosted search on models that have it. `search_context_size` and `user_location` are dropped: one body here routes to seven backends whose search tools take different options.", "title": "Web Search Options" } }, "required": [ "model", "messages" ], "title": "ChatCompletionsRequest", "type": "object" }, "Choice": { "properties": { "finish_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "stop, length, tool_calls, content_filter, or null on an abnormal end.", "title": "Finish Reason" }, "index": { "description": "Always 0; there is exactly one choice.", "title": "Index", "type": "integer" }, "message": { "$ref": "#/components/schemas/Message-Output", "description": "The assistant turn." } }, "required": [ "index", "message" ], "title": "Choice", "type": "object" }, "ChoiceAnswer": { "properties": { "choice": { "description": "Selected option name from the question's criteria.", "title": "Choice", "type": "string" }, "confidence": { "description": "Certainty from 0 to 1 derived from the distribution; not necessarily the winning probability.", "title": "Confidence", "type": "number" }, "probabilities": { "additionalProperties": { "type": "number" }, "description": "Probability for each named option.", "title": "Probabilities", "type": "object" }, "type": { "const": "choice", "description": "Answer to a choice question.", "title": "Type", "type": "string" } }, "required": [ "type", "choice", "confidence", "probabilities" ], "title": "ChoiceAnswer", "type": "object" }, "ChoiceQuestion": { "additionalProperties": true, "properties": { "criteria": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "type": "object" }, { "items": { "$ref": "#/components/schemas/JsonValue" }, "type": "array" }, { "type": "null" } ] }, "description": "Option names mapped to descriptions. Include a fallback when the categories may not fit.", "title": "Criteria", "type": "object" }, "instructions": { "anyOf": [ { "type": "string" }, { "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "type": "object" }, { "items": { "$ref": "#/components/schemas/JsonValue" }, "type": "array" }, { "type": "null" } ], "description": "Judgment to make about state. Write the question here; its name is only an identifier.", "title": "Instructions" }, "type": { "const": "choice", "description": "Select one named option from criteria.", "title": "Type", "type": "string" } }, "required": [ "type", "criteria" ], "title": "ChoiceQuestion", "type": "object" }, "CompletionTokensDetails": { "description": "How the completion count breaks down.\n\n``reasoning_tokens`` is a **subset** of ``completion_tokens``, not an\naddition to it — the same meaning OpenAI's field has, and the opposite\nconvention from :class:`PromptTokensDetails`, whose buckets never overlap.", "properties": { "reasoning_tokens": { "default": 0, "description": "Subset of completion_tokens spent reasoning; 0 where the provider does not break it out.", "title": "Reasoning Tokens", "type": "integer" } }, "title": "CompletionTokensDetails", "type": "object" }, "CountTokensResponse": { "properties": { "input_tokens": { "description": "Prompt tokens the request would consume. An estimate off the Claude family.", "title": "Input Tokens", "type": "integer" } }, "required": [ "input_tokens" ], "title": "CountTokensResponse", "type": "object" }, "DecisionUsage": { "properties": { "input_tokens": { "description": "Provider-reported input tokens for the whole request.", "minimum": 0.0, "title": "Input Tokens", "type": "integer" }, "output_tokens": { "description": "Provider-reported output tokens, including during free pricing.", "minimum": 0.0, "title": "Output Tokens", "type": "integer" } }, "required": [ "input_tokens", "output_tokens" ], "title": "DecisionUsage", "type": "object" }, "DecisionsRequest": { "additionalProperties": true, "examples": [ { "model": "jev", "questions": { "replacement": { "instructions": "Does the report explicitly ask for a replacement item?", "type": "noul" } }, "state": { "report": "The outer box arrived torn. The item inside is undamaged and works normally." } } ], "properties": { "model": { "description": "MindsHub decision alias: jev, its synonym jev-latest, or the pinned jev-1.13.0.", "examples": [ "jev" ], "title": "Model", "type": "string" }, "questions": { "additionalProperties": { "discriminator": { "mapping": { "choice": "#/components/schemas/ChoiceQuestion", "noul": "#/components/schemas/NoulQuestion", "score": "#/components/schemas/ScoreQuestion" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/NoulQuestion" }, { "$ref": "#/components/schemas/ChoiceQuestion" }, { "$ref": "#/components/schemas/ScoreQuestion" } ] }, "description": "Named questions evaluated independently against the same state. Answers use the same names.", "minProperties": 1, "title": "Questions", "type": "object" }, "state": { "anyOf": [ { "type": "string" }, { "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "type": "object" }, { "items": { "$ref": "#/components/schemas/JsonValue" }, "type": "array" } ], "description": "Shared text or JSON to evaluate. Each request is independent; no media input.", "examples": [ { "report": "The outer box arrived torn. The item inside is undamaged and works normally." } ], "title": "State" } }, "required": [ "model", "state", "questions" ], "title": "DecisionsRequest", "type": "object" }, "DecisionsResponse": { "examples": [ { "answers": { "replacement": { "noul": 0.02, "type": "noul" } }, "model": "jev-1.13.0", "usage": { "input_tokens": 120, "output_tokens": 8 } } ], "properties": { "answers": { "additionalProperties": { "discriminator": { "mapping": { "choice": "#/components/schemas/ChoiceAnswer", "noul": "#/components/schemas/NoulAnswer", "score": "#/components/schemas/ScoreAnswer" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/NoulAnswer" }, { "$ref": "#/components/schemas/ChoiceAnswer" }, { "$ref": "#/components/schemas/ScoreAnswer" } ] }, "description": "One typed answer per question, keyed by its original name.", "minProperties": 1, "title": "Answers", "type": "object" }, "model": { "description": "Actual model version served by TypeSafe; does not echo the requested MindsHub alias.", "title": "Model", "type": "string" }, "usage": { "$ref": "#/components/schemas/DecisionUsage", "description": "Token usage across all questions in this evaluation." } }, "required": [ "model", "answers", "usage" ], "title": "DecisionsResponse", "type": "object" }, "DetailError": { "description": "FastAPI's default error body, used by `/v1/traces`: `{\"detail\": \"...\"}`.", "properties": { "detail": { "title": "Detail", "type": "string" } }, "required": [ "detail" ], "title": "DetailError", "type": "object" }, "EmbeddingObject": { "properties": { "embedding": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "string" } ], "description": "The vector, or a base64 string when `encoding_format` is `base64`.", "title": "Embedding" }, "index": { "title": "Index", "type": "integer" }, "object": { "default": "embedding", "title": "Object", "type": "string" } }, "required": [ "index", "embedding" ], "title": "EmbeddingObject", "type": "object" }, "EmbeddingsRequest": { "description": "OpenAI-compatible embeddings request.\n\n``model`` is a bare passthrough alias (e.g. ``embed-small``) resolved by the\nauth gate. The remaining fields mirror the OpenAI embeddings API and are\nforwarded verbatim to the upstream provider.", "properties": { "dimensions": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Number of dimensions the resulting output embeddings should have", "title": "Dimensions" }, "encoding_format": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Format to return the embeddings in (`float` or `base64`)", "title": "Encoding Format" }, "input": { "anyOf": [ { "type": "string" }, { "items": { "type": "string" }, "type": "array" }, { "items": { "type": "integer" }, "type": "array" }, { "items": { "items": { "type": "integer" }, "type": "array" }, "type": "array" } ], "description": "Input text(s) or pre-tokenized input(s) to embed", "title": "Input" }, "model": { "description": "Embeddings alias (e.g. `embed-small`)", "title": "Model", "type": "string" }, "user": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Stable identifier for the end-user, forwarded to the provider", "title": "User" } }, "required": [ "model", "input" ], "title": "EmbeddingsRequest", "type": "object" }, "EmbeddingsResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/EmbeddingObject" }, "title": "Data", "type": "array" }, "model": { "description": "The model that served (for example `text-embedding-3-small`).", "title": "Model", "type": "string" }, "object": { "default": "list", "title": "Object", "type": "string" }, "usage": { "$ref": "#/components/schemas/EmbeddingsUsage" } }, "required": [ "data", "model", "usage" ], "title": "EmbeddingsResponse", "type": "object" }, "EmbeddingsUsage": { "properties": { "prompt_tokens": { "title": "Prompt Tokens", "type": "integer" }, "total_tokens": { "title": "Total Tokens", "type": "integer" } }, "required": [ "prompt_tokens", "total_tokens" ], "title": "EmbeddingsUsage", "type": "object" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "title": "Detail", "type": "array" } }, "title": "HTTPValidationError", "type": "object" }, "JsonValue": {}, "Message": { "properties": { "cache_control": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Cache Control" }, "content": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "$ref": "#/components/schemas/BaseModel" }, { "type": "string" }, { "items": {}, "type": "array" }, { "type": "null" } ], "default": null, "description": "Text, a list of content parts, or null when the model only called tools.", "title": "Content" }, "hosted_tool_calls": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Hosted Tool Calls" }, "is_error": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Is Error" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional participant name.", "title": "Name" }, "role": { "$ref": "#/components/schemas/Role", "description": "system, user, assistant, or tool. developer is accepted and read as system." }, "thinking_blocks": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Thinking Blocks" }, "tool_call_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "On a tool message: the id of the call this result answers.", "title": "Tool Call Id" }, "tool_calls": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Tool calls the assistant made; echo them back verbatim on the next turn.", "title": "Tool Calls" } }, "required": [ "role" ], "title": "Message", "type": "object" }, "Message-Input": { "properties": { "cache_control": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Cache Control" }, "content": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "$ref": "#/components/schemas/BaseModel" }, { "type": "string" }, { "items": {}, "type": "array" }, { "type": "null" } ], "description": "Text, a list of content parts, or null when the model only called tools.", "title": "Content" }, "hosted_tool_calls": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Hosted Tool Calls" }, "is_error": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Error" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional participant name.", "title": "Name" }, "role": { "$ref": "#/components/schemas/Role", "description": "system, user, assistant, or tool. developer is accepted and read as system." }, "thinking_blocks": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Thinking Blocks" }, "tool_call_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "On a tool message: the id of the call this result answers.", "title": "Tool Call Id" }, "tool_calls": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "description": "Tool calls the assistant made; echo them back verbatim on the next turn.", "title": "Tool Calls" } }, "required": [ "role" ], "title": "Message", "type": "object" }, "Message-Output": { "additionalProperties": true, "type": "object" }, "ModelList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ModelRow" }, "title": "Data", "type": "array" }, "has_more": { "default": false, "description": "Always `false`; the listing is never paginated.", "title": "Has More", "type": "boolean" }, "object": { "default": "list", "title": "Object", "type": "string" } }, "required": [ "data" ], "title": "ModelList", "type": "object" }, "ModelRow": { "properties": { "created": { "default": 0, "description": "Always `0`; not a real timestamp.", "title": "Created", "type": "integer" }, "created_at": { "description": "Always `1970-01-01T00:00:00Z`; the catalog tracks availability, not release.", "title": "Created At", "type": "string" }, "default_for": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Agent roles this alias is the default for (`planning`, `coding`, `router`). Omitted when the gate cannot say.", "title": "Default For" }, "default_reasoning_effort": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The effort used when you send none.", "title": "Default Reasoning Effort" }, "disabled_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Why `enabled` is false: `model_restricted` (an administrator in your organization restricted the model; credit does not help), `wallet_empty`, or `included_allowance_exhausted`. Omitted on an enabled row.", "title": "Disabled Reason" }, "display_name": { "description": "Anthropic's spelling of `label`.", "title": "Display Name", "type": "string" }, "embedding": { "description": "`true` for embedding models; use them with `/v1/embeddings`.", "title": "Embedding", "type": "boolean" }, "enabled": { "description": "Whether your organization can call this model right now. Disabled models are still listed.", "title": "Enabled", "type": "boolean" }, "family": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The moving alias this pin belongs to; `family == id` means this alias tracks the newest version. Omitted when unclassified.", "title": "Family" }, "id": { "description": "The alias. Put this in a request's `model` field.", "title": "Id", "type": "string" }, "label": { "description": "Human-readable display name.", "title": "Label", "type": "string" }, "object": { "default": "model", "title": "Object", "type": "string" }, "provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Who serves the model: `anthropic`, `openai`, `gemini`, `fireworks`, `moonshot`, `meta`, `xai`. Omitted when unclassified.", "title": "Provider" }, "reasoning_efforts": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Effort levels the model accepts, or `null` when the level isn't adjustable (the model may still reason).", "title": "Reasoning Efforts" }, "supported_params": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Reserved; not published yet.", "title": "Supported Params" }, "type": { "default": "model", "description": "Anthropic's spelling of `object`.", "title": "Type", "type": "string" } }, "required": [ "id", "label", "display_name", "created_at", "enabled", "reasoning_efforts", "default_reasoning_effort", "embedding" ], "title": "ModelRow", "type": "object" }, "NoulAnswer": { "properties": { "noul": { "description": "Probability of yes/true, from 0 to 1. Not a Boolean; no separate confidence field.", "title": "Noul", "type": "number" }, "type": { "const": "noul", "description": "Answer to a noul question.", "title": "Type", "type": "string" } }, "required": [ "type", "noul" ], "title": "NoulAnswer", "type": "object" }, "NoulCriteria": { "additionalProperties": true, "properties": { "false": { "anyOf": [ { "type": "string" }, { "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "type": "object" }, { "items": { "$ref": "#/components/schemas/JsonValue" }, "type": "array" }, { "type": "null" } ], "description": "Describe the no/false outcome; noul values near 0 support it.", "title": "False" }, "true": { "anyOf": [ { "type": "string" }, { "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "type": "object" }, { "items": { "$ref": "#/components/schemas/JsonValue" }, "type": "array" }, { "type": "null" } ], "description": "Describe the yes/true outcome; noul values near 1 support it.", "title": "True" } }, "title": "NoulCriteria", "type": "object" }, "NoulQuestion": { "additionalProperties": true, "properties": { "criteria": { "anyOf": [ { "$ref": "#/components/schemas/NoulCriteria" }, { "type": "null" } ], "description": "Optional descriptions clarifying yes and no." }, "instructions": { "anyOf": [ { "type": "string" }, { "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "type": "object" }, { "items": { "$ref": "#/components/schemas/JsonValue" }, "type": "array" }, { "type": "null" } ], "description": "Judgment to make about state. Write the question here; its name is only an identifier.", "title": "Instructions" }, "type": { "const": "noul", "description": "Ask one yes/no proposition and receive its probability of being true.", "title": "Type", "type": "string" } }, "required": [ "type" ], "title": "NoulQuestion", "type": "object" }, "OpenAIError": { "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Stable machine-readable code: `model_not_found`, `param_not_supported`, `invalid_param`, `max_tokens_exceeded`, `unsupported_parameter`, `previous_response_not_found`, `rate_limited`, `included_allowance_exhausted`, `free_air_daily_spend_fuse_exceeded`, `wallet_empty`, `invalid_credentials`, `permission_denied`, `policy_unavailable`.", "title": "Code" }, "deny_detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The specific cause behind a `permission_denied`: `model_restricted` when an administrator in your organization restricted the model. Same value as `X-MindsHub-Deny-Detail`. Absent otherwise.", "title": "Deny Detail" }, "message": { "description": "Human-readable explanation of what went wrong.", "title": "Message", "type": "string" }, "param": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The request field at fault, when the error is about one.", "title": "Param" }, "type": { "description": "Error class: `invalid_request_error`, `authentication_error`, `permission_error`, `rate_limit_error`, or `server_error`.", "title": "Type", "type": "string" } }, "required": [ "message", "type" ], "title": "OpenAIError", "type": "object" }, "OpenAIErrorEnvelope": { "description": "The error body on every OpenAI-shaped endpoint (`/chat/completions`, `/responses`, `/embeddings`, `/models`),\nand on the gate's denials on `/decisions`.", "properties": { "error": { "$ref": "#/components/schemas/OpenAIError" }, "reset_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO-8601 instant the limit resets, on `included_allowance_exhausted` and `free_air_daily_spend_fuse_exceeded`. Same value as `X-MindsHub-Reset-At`. Absent otherwise, and absent on `included_allowance_exhausted` when the organization has no included allowance.", "title": "Reset At" } }, "required": [ "error" ], "title": "OpenAIErrorEnvelope", "type": "object" }, "OpenAIResponsesRequest": { "additionalProperties": true, "description": "An OpenAI ``POST /v1/responses`` request body.\n\nDeliberately permissive (``extra=\"allow\"``, loose item typing): OpenAI adds\nrequest fields and input-item types over time, and an unknown field must\ndegrade to \"ignored\", never a 422 — the OpenAI SDK treats a validation\nfailure as a hard error, so strictness here reads to a caller as an outage.\nField *semantics* live in the translation layer, not in this schema.", "properties": { "background": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "**Accepted and ignored.** Accepted and echoed, but every request is served synchronously: a client's poll of retrieve() finds the response already completed rather than queued. `response.queued` is therefore never emitted, and cancel() has nothing in flight to stop.", "title": "Background" }, "context_management": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "**Rejected with 400.** A 400. It asks us to manage the context window on the caller's behalf, and a client that believes we are doing so stops managing it itself — the same failure as `conversation`.", "title": "Context Management" }, "conversation": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "**Rejected with 400.** A 400. OpenAI documents `conversation` and `previous_response_id` as mutually exclusive, so the alternative is a one-line change for the caller. Refusing beats ignoring here: a client that believes we are holding its thread stops sending history, and every turn silently loses its context (ENG-1224). No third-party Responses implementation offers a Conversations API today.", "title": "Conversation" }, "include": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "**Per model.** Of the eight values OpenAI defines, only `reasoning.encrypted_content` is honoured — it gates the reasoning round-trip. Note that `web_search_call` items and `output_text` annotations are returned whether or not they are asked for, so the two `include` values naming them change nothing. `message.output_text.logprobs` needs logprobs we do not produce; the file_search, code_interpreter and computer_use values belong to hosted tools we do not run; `message.input_image.image_url` is Milestone 4.", "title": "Include" }, "input": { "anyOf": [ { "type": "string" }, { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "**Adapted.** A string or an item list. `message`, `function_call`, `function_call_output`, `custom_tool_call`, `custom_tool_call_output` and `reasoning` items round-trip; `input_text`/`output_text`/`input_image` content parts translate, including inside a `function_call_output`, so a tool that returns an image shows the model an image; a model that cannot take one sees a short text note in its place. Supplied `refusal` explanations replay as text. `input_file` and `input_audio` parts are dropped (Milestone 4). An `item_reference` item has no local counterpart and is skipped. Every skipped item type (`item_reference`, `local_shell_call`, …) is named in X-MindsHub-Dropped-Params as `input.`.", "title": "Input" }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "**Adapted.** Becomes a leading system message. Deliberately per-turn: OpenAI does not carry it across `previous_response_id`, so a chained turn replays history without it.", "title": "Instructions" }, "max_output_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "**Per model.** Clamped down to the resolved model's output ceiling and up to the transport's floor; either is named in X-MindsHub-Clamped-Params. A turn cut short by it reports `status: incomplete` with `incomplete_details.reason: max_output_tokens`.", "title": "Max Output Tokens" }, "max_tool_calls": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "**Accepted and ignored.** No transport we speak has a per-turn tool-call ceiling, and enforcing one ourselves would mean truncating a turn mid-flight. Named in X-MindsHub-Dropped-Params.", "title": "Max Tool Calls" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "**Accepted and ignored.** Accepted and echoed back on the Response. Describes the caller's bookkeeping rather than the generation, so it reaches no provider and is not reported as a drop.", "title": "Metadata" }, "model": { "description": "**Adapted.** An alias from GET /v1/models resolves to a concrete provider model, so any catalog model can serve a Responses request. The response names the model that served, as every lane does; `mindshub_air` and `mindshub_blaze` return their own alias instead.", "title": "Model", "type": "string" }, "parallel_tool_calls": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "**Per model.** Honoured, including on the Anthropic wire, which spells it inverted inside tool_choice. Gemini cannot express it and declares it unsupported, so the drop is named in X-MindsHub-Dropped-Params.", "title": "Parallel Tool Calls" }, "previous_response_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "**Adapted.** Reconstructs history from the stored chain. Items the client also re-sent are deduped, because a duplicated tool_use is a hard 400 on the Anthropic wire. An unknown id is a 404 naming the recovery. A chain truncated to fit is reported in a response header.", "title": "Previous Response Id" }, "prompt": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "**Rejected with 400.** A 400. Stored prompt templates live in OpenAI's dashboard and we cannot resolve an id that only exists there; serving the request would answer with the template silently missing.", "title": "Prompt" }, "prompt_cache_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "**Accepted and ignored.** Accepted and echoed. We derive an equivalent key ourselves from the instructions and tool set, so honouring the caller's spelling would change nothing they can observe.", "title": "Prompt Cache Key" }, "prompt_cache_retention": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "**Accepted and ignored.** Accepted and echoed. Cache lifetime is the upstream provider's to set and differs per provider; there is no field to forward it to on any transport we speak.", "title": "Prompt Cache Retention" }, "reasoning": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "**Per model.** `effort` maps onto each model's own ladder, clamped rather than dropped so a request to be cheap is not answered by the provider's near-the-top default. `summary` is surfaced on the returned `reasoning` item where the provider gives one. Kimi reasons internally with no adjustable level and declares `effort` unsupported.", "title": "Reasoning" }, "safety_identifier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "**Accepted and ignored.** Accepted and echoed. Describes the caller, not the generation. Abuse attribution here runs off the authenticated identity, which a request cannot choose.", "title": "Safety Identifier" }, "service_tier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "**Accepted and ignored.** Accepted and echoed as `default`. One serving tier here, so the field is a constant rather than a measurement — sent because OpenAI always sends it and a client reading it should get a string rather than a missing key.", "title": "Service Tier" }, "store": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "**Adapted.** Defaults to true as OpenAI's server does. A stored turn is readable by GET, DELETE and /input_items, and chainable by previous_response_id, for 30 days. `store: false` persists nothing — a chain can still be read from, but not extended.", "title": "Store" }, "stream": { "default": false, "description": "**Forwarded.** SSE Responses events terminated by `response.completed`/`.incomplete`, never a `[DONE]` sentinel. Items are strictly sequential — one closes before the next opens.", "title": "Stream", "type": "boolean" }, "stream_options": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "**Accepted and ignored.** The Responses API's only member is `include_obfuscation`, which we do not implement; usage rides the terminal event unconditionally, so there is nothing here to honour. `include_usage` is read as a MindsHub extension for callers migrating from the chat lane, and changes nothing a Responses client can observe.", "title": "Stream Options" }, "temperature": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "**Per model.** Dropped on models that reject sampling params and named in X-MindsHub-Dropped-Params. One body routes to seven providers, so a param the chosen model cannot read is not a reason to refuse the request.", "title": "Temperature" }, "text": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "**Per model.** `text.format` is structured output and is honoured on every transport that can express a JSON schema; a model that cannot is a 400 naming it, not a silent drop, because prose handed to a caller about to json.loads() it is a different kind of answer. Schema-less `json_object` is unavailable on the Anthropic family, which has no equivalent. `text.verbosity` reaches only the OpenAI Responses transport, whose native field it is.", "title": "Text" }, "tool_choice": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "**Adapted.** auto/required/none and `{type: function, name}` all map. A forced choice a model cannot honour is downgraded to `auto` rather than refused (ENG-1095). A hosted-tool choice cannot be forced generically and is dropped.", "title": "Tool Choice" }, "tools": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "**Adapted.** Responses function tools are flat where the internal shape nests them; both translate. Hosted `web_search` maps onto each provider's own search or our external loop, and the searches it runs are reported as `web_search_call` output items on a non-streamed turn (a stream does not narrate them yet). `mcp` runs on the target's own remote-MCP connector (GPT: OpenAI's, `require_approval` passed through, approvals included; Claude: Anthropic's, which has no gate, so only tools resolving to `never` run and the rest are named in X-MindsHub-Dropped-Params) and is reported as `mcp_list_tools` / `mcp_call` output items on a non-streamed turn. A freeform `custom` tool (Codex's `apply_patch`) goes upstream as a function taking one string, its grammar in the description, and the call comes back as a `custom_tool_call`. Every other hosted tool (file_search, code_interpreter, computer_use, local_shell, tool_search, …) has no cross-provider meaning, so it is dropped and named in X-MindsHub-Dropped-Params as `tools.`.", "title": "Tools" }, "top_logprobs": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "**Accepted and ignored.** Our OpenAI and xAI providers speak the Responses API, which has no logprobs, and the Anthropic wire has none either — so there is no response-side plumbing to build on for the two backends that could express it. Named in X-MindsHub-Dropped-Params, and `logprobs: []` is sent on every text frame because the SDK requires the key.", "title": "Top Logprobs" }, "top_p": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "**Per model.** As temperature. On a Claude model that still takes sampling params, sending it with temperature drops top_p (Anthropic rejects the pair) and names it in X-MindsHub-Dropped-Params; top_p alone is forwarded.", "title": "Top P" }, "truncation": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "**Accepted and ignored.** `disabled` IS our behavior and is honoured by doing nothing. `auto` asks us to drop history to fit the context window; we have no per-model context table, so it is named in X-MindsHub-Dropped-Params rather than silently not happening.", "title": "Truncation" }, "user": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "**Accepted and ignored.** As safety_identifier — OpenAI's deprecated spelling of it.", "title": "User" }, "verbosity": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "**Per model.** Not in the SDK's request-params object. `responses.parse()` takes it as a top-level keyword and passes it through verbatim, so it arrives beside `text` rather than inside it; `responses.create()` does not model it at all, so `parse()` is the only SDK route to this parameter. Normalized into `text.verbosity` on arrival, so the echo and the applied value agree, and honoured from there.", "title": "Verbosity" } }, "required": [ "model" ], "title": "OpenAIResponsesRequest", "type": "object" }, "PromptTokensDetails": { "description": "How the prompt count breaks down across the provider's cache buckets.\n\nSame field OpenAI publishes it under, so a client already reading their\nresponses reads ours without a change.", "properties": { "cache_write_tokens": { "default": 0, "description": "Prompt tokens written to the cache (a MindsHub extension).", "title": "Cache Write Tokens", "type": "integer" }, "cached_tokens": { "default": 0, "description": "Prompt tokens read from the provider's cache.", "title": "Cached Tokens", "type": "integer" } }, "title": "PromptTokensDetails", "type": "object" }, "ResponseDeleted": { "properties": { "deleted": { "default": true, "title": "Deleted", "type": "boolean" }, "id": { "title": "Id", "type": "string" }, "object": { "default": "response", "title": "Object", "type": "string" } }, "required": [ "id" ], "title": "ResponseDeleted", "type": "object" }, "ResponseInputItemList": { "description": "One page of a stored response's own input items (not the inherited history).", "properties": { "data": { "items": { "additionalProperties": true, "type": "object" }, "title": "Data", "type": "array" }, "first_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Id" }, "has_more": { "title": "Has More", "type": "boolean" }, "last_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Id" }, "object": { "default": "list", "title": "Object", "type": "string" } }, "required": [ "data", "has_more" ], "title": "ResponseInputItemList", "type": "object" }, "ResponseObject": { "description": "A Responses API response, as OpenAI shapes it. Stored for 30 days unless `store: false`.", "properties": { "background": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Background" }, "completed_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Completed At" }, "created_at": { "description": "Unix seconds.", "title": "Created At", "type": "integer" }, "error": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "On `failed`: `{\"code\": …, \"message\": …}`. Codes include `rate_limit_exceeded`, `context_length_exceeded`, `insufficient_quota`, `invalid_prompt`, `server_error`.", "title": "Error" }, "id": { "description": "`resp_…`. Chain the next turn onto it with `previous_response_id`.", "title": "Id", "type": "string" }, "incomplete_details": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "On `incomplete`: `{\"reason\": \"max_output_tokens\" | \"content_filter\"}`.", "title": "Incomplete Details" }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instructions" }, "max_output_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Max Output Tokens" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "model": { "description": "The model that served, which can be sent back as-is. `mindshub_air` and `mindshub_blaze` return their own alias instead.", "title": "Model", "type": "string" }, "object": { "default": "response", "title": "Object", "type": "string" }, "output": { "description": "Output items: `message` (with `output_text` parts), `function_call`, `web_search_call`, `reasoning`.", "items": { "additionalProperties": true, "type": "object" }, "title": "Output", "type": "array" }, "output_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The assistant text flattened, as the SDK exposes it.", "title": "Output Text" }, "parallel_tool_calls": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Parallel Tool Calls" }, "previous_response_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Previous Response Id" }, "reasoning": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Reasoning" }, "service_tier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Always `default`.", "title": "Service Tier" }, "status": { "description": "`completed`, `incomplete` (see `incomplete_details`), or `failed` (see `error`).", "title": "Status", "type": "string" }, "store": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Store" }, "temperature": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Temperature" }, "text": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Echo of the `text` request field, `format` included.", "title": "Text" }, "tool_choice": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Tool Choice" }, "tools": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Tools" }, "top_p": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Top P" }, "usage": { "anyOf": [ { "$ref": "#/components/schemas/ResponseUsage" }, { "type": "null" } ] } }, "required": [ "id", "created_at", "status", "model", "output" ], "title": "ResponseObject", "type": "object" }, "ResponseUsage": { "properties": { "input_tokens": { "description": "Prompt tokens, cached tokens included.", "title": "Input Tokens", "type": "integer" }, "input_tokens_details": { "additionalProperties": { "type": "integer" }, "description": "`{\"cached_tokens\": n}`: prompt tokens served from the provider's cache.", "title": "Input Tokens Details", "type": "object" }, "output_tokens": { "description": "Generated tokens, reasoning included.", "title": "Output Tokens", "type": "integer" }, "output_tokens_details": { "additionalProperties": { "type": "integer" }, "description": "`{\"reasoning_tokens\": n}`: the subset of `output_tokens` spent reasoning, where the provider reports it.", "title": "Output Tokens Details", "type": "object" }, "total_tokens": { "title": "Total Tokens", "type": "integer" } }, "required": [ "input_tokens", "input_tokens_details", "output_tokens", "output_tokens_details", "total_tokens" ], "title": "ResponseUsage", "type": "object" }, "Role": { "enum": [ "system", "user", "assistant", "function", "tool" ], "title": "Role", "type": "string" }, "ScoreAnswer": { "properties": { "confidence": { "description": "Certainty statistic from 0 to 1 derived from the level distribution.", "title": "Confidence", "type": "number" }, "legend": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "type": "object" }, { "items": { "$ref": "#/components/schemas/JsonValue" }, "type": "array" } ] }, "description": "String level indices mapped to the original criterion descriptions.", "title": "Legend", "type": "object" }, "probabilities": { "additionalProperties": { "type": "number" }, "description": "Probability for each level, keyed by its index as a string.", "title": "Probabilities", "type": "object" }, "score": { "description": "Probability-weighted mean of zero-based level indices; may be fractional.", "title": "Score", "type": "number" }, "type": { "const": "score", "description": "Answer to a score question.", "title": "Type", "type": "string" } }, "required": [ "type", "score", "confidence", "legend", "probabilities" ], "title": "ScoreAnswer", "type": "object" }, "ScoreQuestion": { "additionalProperties": true, "properties": { "criteria": { "description": "Ordered level descriptions. Positions assign scores from 0; the result may be fractional.", "items": { "anyOf": [ { "type": "string" }, { "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "type": "object" }, { "items": { "$ref": "#/components/schemas/JsonValue" }, "type": "array" } ] }, "minItems": 1, "title": "Criteria", "type": "array" }, "instructions": { "anyOf": [ { "type": "string" }, { "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "type": "object" }, { "items": { "$ref": "#/components/schemas/JsonValue" }, "type": "array" }, { "type": "null" } ], "description": "Judgment to make about state. Write the question here; its name is only an identifier.", "title": "Instructions" }, "type": { "const": "score", "description": "Rate one dimension along an ordered rubric.", "title": "Type", "type": "string" } }, "required": [ "type", "criteria" ], "title": "ScoreQuestion", "type": "object" }, "StreamChoice": { "properties": { "delta": { "$ref": "#/components/schemas/Message", "description": "The incremental message fragment." }, "finish_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Only on the terminal chunk: stop, length, tool_calls, content_filter, or function_call.", "title": "Finish Reason" }, "index": { "description": "Always 0.", "title": "Index", "type": "integer" } }, "required": [ "index", "delta" ], "title": "StreamChoice", "type": "object" }, "StreamOptions": { "description": "OpenAI ``stream_options``: opt-in for the final streaming usage chunk.\n\nWas silently dropped by pydantic as an unknown extra until ENG-1158 — so a\nclient asking for streamed usage got nothing, with no error. Only\n``include_usage`` is honored; other keys are ignored as before.", "properties": { "include_usage": { "default": false, "description": "Emit a final chunk with empty choices and the usage totals before [DONE]", "title": "Include Usage", "type": "boolean" } }, "title": "StreamOptions", "type": "object" }, "TraceDetail": { "description": "Full trace: list fields plus content payloads and the span waterfall.", "properties": { "cached_input_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Prompt tokens served from the provider prompt cache (billed at a discount)", "title": "Cached Input Tokens" }, "error_class": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Error category when the request failed", "title": "Error Class" }, "http_status": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "HTTP status the handler returned; None if unrecorded", "title": "Http Status" }, "id": { "description": "Trace id (also the langfuse_trace_id join key)", "title": "Id", "type": "string" }, "input": { "anyOf": [ {}, { "type": "null" } ], "description": "Trace-level input payload", "title": "Input" }, "input_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Full-rate (uncached) input/prompt tokens", "title": "Input Tokens" }, "kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Source-stamped request classification: 'probe' for a background call a MindsHub client made on the caller's key, such as a connectivity health check; None for ordinary traffic. The list hides probes by default.", "title": "Kind" }, "latency_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "End-to-end latency in milliseconds", "title": "Latency Ms" }, "level": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Highest observation level, best-effort (DEFAULT | ERROR)", "title": "Level" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Trace-level metadata", "title": "Metadata" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Requested model alias (from the request payload), best-effort", "title": "Model" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Trace name, e.g. 'cowork:turn-3' or 'chat.completion'", "title": "Name" }, "output": { "anyOf": [ {}, { "type": "null" } ], "description": "Trace-level output payload", "title": "Output" }, "output_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Output (completion) tokens", "title": "Output Tokens" }, "preview": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Short preview of the request (the last user message) — the row's identity", "title": "Preview" }, "provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Upstream model provider (e.g. openai, anthropic); None if unrecorded", "title": "Provider" }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Session id grouping multi-turn requests", "title": "Session Id" }, "span_count": { "default": 0, "description": "Number of observations (spans) on the trace", "title": "Span Count", "type": "integer" }, "spans": { "description": "Observations, ordered by start time", "items": { "$ref": "#/components/schemas/TraceSpan" }, "title": "Spans", "type": "array" }, "stream": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether served as a stream; disambiguates latency_ms (drain vs request time). None if unrecorded.", "title": "Stream" }, "tags": { "description": "Trace tags (env, harness, identity)", "items": { "type": "string" }, "title": "Tags", "type": "array" }, "timestamp": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the request started", "title": "Timestamp" }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Owning user id", "title": "User Id" } }, "required": [ "id" ], "title": "TraceDetail", "type": "object" }, "TraceListItem": { "description": "A single request in the trace list. Content payloads are omitted here;\nthey are only returned on the detail endpoint.", "properties": { "cached_input_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Prompt tokens served from the provider prompt cache (billed at a discount)", "title": "Cached Input Tokens" }, "error_class": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Error category when the request failed", "title": "Error Class" }, "http_status": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "HTTP status the handler returned; None if unrecorded", "title": "Http Status" }, "id": { "description": "Trace id (also the langfuse_trace_id join key)", "title": "Id", "type": "string" }, "input_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Full-rate (uncached) input/prompt tokens", "title": "Input Tokens" }, "kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Source-stamped request classification: 'probe' for a background call a MindsHub client made on the caller's key, such as a connectivity health check; None for ordinary traffic. The list hides probes by default.", "title": "Kind" }, "latency_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "End-to-end latency in milliseconds", "title": "Latency Ms" }, "level": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Highest observation level, best-effort (DEFAULT | ERROR)", "title": "Level" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Requested model alias (from the request payload), best-effort", "title": "Model" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Trace name, e.g. 'cowork:turn-3' or 'chat.completion'", "title": "Name" }, "output_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Output (completion) tokens", "title": "Output Tokens" }, "preview": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Short preview of the request (the last user message) — the row's identity", "title": "Preview" }, "provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Upstream model provider (e.g. openai, anthropic); None if unrecorded", "title": "Provider" }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Session id grouping multi-turn requests", "title": "Session Id" }, "span_count": { "default": 0, "description": "Number of observations (spans) on the trace", "title": "Span Count", "type": "integer" }, "stream": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether served as a stream; disambiguates latency_ms (drain vs request time). None if unrecorded.", "title": "Stream" }, "tags": { "description": "Trace tags (env, harness, identity)", "items": { "type": "string" }, "title": "Tags", "type": "array" }, "timestamp": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the request started", "title": "Timestamp" }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Owning user id", "title": "User Id" } }, "required": [ "id" ], "title": "TraceListItem", "type": "object" }, "TraceListResponse": { "description": "Wrapped list response (the client always expects a wrapped object).", "properties": { "has_more": { "default": false, "description": "Whether another page is available", "title": "Has More", "type": "boolean" }, "langfuse_available": { "default": true, "description": "False when the Langfuse backend is not configured. The list is served from Postgres regardless, and a live stored Responses turn's detail falls back to its Postgres payload (no spans).", "title": "Langfuse Available", "type": "boolean" }, "limit": { "default": 25, "description": "Page size", "title": "Limit", "type": "integer" }, "page": { "default": 1, "description": "1-based page number", "title": "Page", "type": "integer" }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Exact total matching traces, when known. `null` when the bounded count exceeds its cap or the scan isn't index-served: any filter on an unindexed column (session/model/provider/level/stream) or a `user_id` pin skips the count for cost. Use `has_more` for pagination.", "title": "Total" }, "total_capped": { "default": false, "description": "True when the bounded count crossed its cap. `total` remains null to preserve its exact-or-unknown contract.", "title": "Total Capped", "type": "boolean" }, "traces": { "description": "Traces for this org/role, newest first", "items": { "$ref": "#/components/schemas/TraceListItem" }, "title": "Traces", "type": "array" } }, "title": "TraceListResponse", "type": "object" }, "TraceSpan": { "description": "One observation within a trace (a generation, tool call, or search).", "properties": { "duration_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Span duration in milliseconds (end - start)", "title": "Duration Ms" }, "end_time": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Span end", "title": "End Time" }, "id": { "description": "Observation id", "title": "Id", "type": "string" }, "input": { "anyOf": [ {}, { "type": "null" } ], "description": "Span input payload (prompt / tool args / query)", "title": "Input" }, "level": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Langfuse level: DEBUG | DEFAULT | WARNING | ERROR", "title": "Level" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Span metadata (alias, provider, call_id, …)", "title": "Metadata" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Model for generation spans", "title": "Model" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Observation name, e.g. 'generation · sonnet' or 'tool:search'", "title": "Name" }, "output": { "anyOf": [ {}, { "type": "null" } ], "description": "Span output payload (completion / results)", "title": "Output" }, "parent_observation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Parent observation id (nesting)", "title": "Parent Observation Id" }, "start_time": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Span start", "title": "Start Time" }, "status_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Error/status message when the span failed", "title": "Status Message" }, "type": { "default": "span", "description": "Observation type: generation | span | event", "title": "Type", "type": "string" }, "usage": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Token usage details for generation spans", "title": "Usage" } }, "required": [ "id" ], "title": "TraceSpan", "type": "object" }, "Usage": { "description": "The usage object on a chat-completion response.\n\n``prompt_tokens`` is the WHOLE prompt — uncached, cache reads, and cache\nwrites — because that is what the field means in an OpenAI-shaped response\nand what every cost tracker reading one assumes. Our internal\n``TokenUsage.input_tokens`` is the full-rate remainder instead, so putting\nit here understated the prompt on exactly the requests where caching was\nworking. Build this through :meth:`from_token_usage` rather than by hand so\nthe two can never drift apart again.", "properties": { "completion_tokens": { "description": "Generated tokens, reasoning included.", "title": "Completion Tokens", "type": "integer" }, "completion_tokens_details": { "$ref": "#/components/schemas/CompletionTokensDetails" }, "prompt_tokens": { "description": "The whole prompt, cached tokens included.", "title": "Prompt Tokens", "type": "integer" }, "prompt_tokens_details": { "anyOf": [ { "$ref": "#/components/schemas/PromptTokensDetails" }, { "type": "null" } ], "description": "Present only when the request touched the provider's cache." }, "total_tokens": { "description": "prompt_tokens + completion_tokens.", "title": "Total Tokens", "type": "integer" } }, "required": [ "prompt_tokens", "completion_tokens", "total_tokens" ], "title": "Usage", "type": "object" }, "ValidationError": { "properties": { "ctx": { "title": "Context", "type": "object" }, "input": { "title": "Input" }, "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "title": "Location", "type": "array" }, "msg": { "title": "Message", "type": "string" }, "type": { "title": "Error Type", "type": "string" } }, "required": [ "loc", "msg", "type" ], "title": "ValidationError", "type": "object" } }, "securitySchemes": { "BearerAuth": { "description": "`Authorization: Bearer mdb_…`", "scheme": "bearer", "type": "http" } } }, "info": { "description": "Every major model through the three request formats you already use: OpenAI Chat Completions, OpenAI Responses, and Anthropic Messages, on one key and one bill. Any model in the catalog can serve any of the three when its kind is chat. Jev uses the native state/questions shape on POST /v1/decisions.\n\nAuthenticate with `Authorization: Bearer mdb_…`. OpenAI SDKs take the base URL `https://api.mindshub.ai/v1`; Anthropic SDKs take `https://api.mindshub.ai` and authenticate with `auth_token`, not `api_key`.\n\nOn the three chat APIs, parameters the target model cannot take are dropped and named in `X-MindsHub-Dropped-Params`; values outside its range are clamped and named in `X-MindsHub-Clamped-Params`. Parts of the request itself the target cannot carry — a content block, a per-block key, a tool schema keyword — are likewise dropped and named in `X-MindsHub-Dropped-Content`, so a model that does not support something you sent serves the request instead of refusing it. Structured output is the one parameter refused (400) rather than dropped. Guides: https://docs.mindshub.ai/inference/", "title": "MindsHub Inference API", "version": "v1" }, "openapi": "3.1.0", "paths": { "/v1/chat/completions": { "post": { "description": "OpenAI Chat Completions, on any model in the catalog. Send `model` (an alias) and `messages`; set `stream: true` for `text/event-stream` chunks terminated by `data: [DONE]`. Parameters the target model cannot take are dropped and named in `X-MindsHub-Dropped-Params`, and parts of the request the target cannot carry in `X-MindsHub-Dropped-Content` (a stream whose 200 went out early carries neither); `response_format` is the one thing refused with a 400 instead. The response's `model` names the model that served (`mindshub_air` and `mindshub_blaze` return their own alias), and it can be sent back as-is.", "operationId": "createChatCompletion", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionsRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletion" } }, "text/event-stream": { "description": "When `stream` is true: server-sent events, one frame per `data:` line.", "schema": { "$ref": "#/components/schemas/ChatCompletionChunk" } } }, "description": "The completion. Exactly one choice.", "headers": { "X-MindsHub-Attempts": { "description": "Upstream attempts the request took, requested model and fallbacks together. `1` means the first try answered. Never sent on a stream whose 200 went out early because its response took more than 90 seconds to start, so there its absence says nothing.", "schema": { "type": "integer" } }, "X-MindsHub-Clamped-Params": { "description": "Parameters adjusted to the model's range, as `name=requested>applied`. Absent when nothing was clamped. Never sent on a stream whose 200 went out early because its response took more than 90 seconds to start, so there its absence says nothing.", "schema": { "type": "string" } }, "X-MindsHub-Dropped-Content": { "description": "Comma-separated categories of request *structure* the target model could not take: content blocks and per-block keys, message fields, tool keys, and tool schemas rewritten into the target's dialect (e.g. `block_field.cache_control,content_block.thinking,tool_schema.gemini_openapi`). Category labels, not an inventory, and capped at 16 with a trailing `more.N`. Absent when nothing was dropped. Never sent on a stream whose 200 went out early because its response took more than 90 seconds to start, so there its absence says nothing.", "schema": { "type": "string" } }, "X-MindsHub-Dropped-Params": { "description": "Comma-separated parameters the target model could not take and that were dropped. Absent when nothing was dropped. Never sent on a stream whose 200 went out early because its response took more than 90 seconds to start, so there its absence says nothing.", "schema": { "type": "string" } }, "X-MindsHub-Failover": { "description": "`true` when a fallback model produced the response, `false` when the requested model did. Present, on errors too, once the request reached a model. Never sent on a stream whose 200 went out early because its response took more than 90 seconds to start, so there its absence says nothing. On such a stream, read the `mindshub` field of its last event instead (`message_delta` on Messages). A Chat Completions or Messages stream that fails after its early 200 carries no failover signal at all.", "schema": { "enum": [ "true", "false" ], "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorEnvelope" } } }, "description": "Malformed body, or a parameter the target model cannot honor and that is refused rather than dropped (`param_not_supported`, `invalid_param`, `max_tokens_exceeded`, `model_not_configured`)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorEnvelope" } } }, "description": "Missing or invalid `Authorization: Bearer mdb_…` (`invalid_credentials`)." }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorEnvelope" } } }, "description": "The wallet is empty and this model is not covered by the included allowance (`wallet_empty`).", "headers": { "X-MindsHub-Reason": { "description": "Machine-readable denial reason (`permission_denied`, `rate_limited`, `included_allowance_exhausted`, `free_air_daily_spend_fuse_exceeded`, `wallet_empty`).", "schema": { "type": "string" } }, "X-MindsHub-Recovery-Url": { "description": "Relative console URL where credit can be added.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorEnvelope" } } }, "description": "The key is valid but not permitted here (`permission_denied`). When an administrator in your organization restricted the model, `error.deny_detail` and `X-MindsHub-Deny-Detail` read `model_restricted`: choose another model, since credit does not lift it.", "headers": { "X-MindsHub-Deny-Detail": { "description": "The specific cause behind `permission_denied`. `model_restricted` when an administrator in your organization restricted the model; the body's `error.deny_detail` carries the same value. Absent on every other 403.", "schema": { "type": "string" } }, "X-MindsHub-Reason": { "description": "Machine-readable denial reason (`permission_denied`, `rate_limited`, `included_allowance_exhausted`, `free_air_daily_spend_fuse_exceeded`, `wallet_empty`).", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorEnvelope" } } }, "description": "Unknown model alias (`model_not_found`)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorEnvelope" } } }, "description": "Too fast (`rate_limited`, retry after `Retry-After`), the included allowance is exhausted (`included_allowance_exhausted`), or free serving is paused until the daily budget resets (`free_air_daily_spend_fuse_exceeded`). The last two carry body `reset_at` and `X-MindsHub-Reset-At`, and `x-should-retry: false`; adding credit lifts either immediately. An organization with no included allowance gets `included_allowance_exhausted` with no `reset_at`, because nothing refills; only credit lifts it.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-MindsHub-Reason": { "description": "Machine-readable denial reason (`permission_denied`, `rate_limited`, `included_allowance_exhausted`, `free_air_daily_spend_fuse_exceeded`, `wallet_empty`).", "schema": { "type": "string" } }, "X-MindsHub-Reset-At": { "description": "ISO-8601 instant the allowance refills or free serving resumes. Absent on `included_allowance_exhausted` when the organization has no included allowance.", "schema": { "type": "string" } }, "x-should-retry": { "description": "`false` on `included_allowance_exhausted` and `free_air_daily_spend_fuse_exceeded`, so the OpenAI and Anthropic SDKs return the error on the first attempt instead of retrying it. Absent on `rate_limited`, which is worth retrying.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorEnvelope" } } }, "description": "The authorization gate is unavailable (`policy_unavailable`). Retry." } }, "summary": "Create a chat completion", "tags": [ "chat" ], "x-codeSamples": [ { "label": "Python", "lang": "Python", "source": "import os\n\nfrom openai import OpenAI\n\nclient = OpenAI(base_url=\"https://api.mindshub.ai/v1\", api_key=os.environ[\"MINDSHUB_API_KEY\"])\n\nresponse = client.chat.completions.create(\n model=\"mindshub_air\",\n messages=[{\"role\": \"user\", \"content\": \"What is the capital of Australia?\"}],\n)\nprint(response.choices[0].message.content)" }, { "label": "TypeScript", "lang": "TypeScript", "source": "import OpenAI from \"openai\";\n\nconst client = new OpenAI({ baseURL: \"https://api.mindshub.ai/v1\", apiKey: process.env.MINDSHUB_API_KEY });\n\nconst response = await client.chat.completions.create({\n model: \"mindshub_air\",\n messages: [{ role: \"user\", content: \"What is the capital of Australia?\" }],\n});\nconsole.log(response.choices[0].message.content);" } ] } }, "/v1/decisions": { "post": { "description": "Evaluate named noul, choice, or score questions against shared state.\n\nAuthenticate with a MindsHub key. TypeSafe hosts Jev; no TypeSafe key is\nneeded by callers. Each question sees the same state and returns an answer\nunder its original name. The response model is the actual served version.\n\nReturns one JSON response; streaming, tools, and conversation chaining are\nnot supported. Input and output are priced at $0 during the Jev launch\npromotion. Organizations with wallet credit, or with a card that has\ncompleted a top-up and has no payment error, call Jev without a daily cap.\nOther organizations get a free daily allowance while shared free capacity\nlasts; past it the request is refused with 402 wallet_empty. Rate limits\napply to every organization.\n\nAllowance: https://docs.mindshub.ai/inference/billing#jev-decisions\nGuide: https://docs.mindshub.ai/inference/decision-models\nExamples, limits, and retries: https://docs.mindshub.ai/inference/decisions", "operationId": "createDecisions", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionsRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionsResponse" } } }, "description": "Successful Response" }, "400": { "description": "Wrong model kind, unavailable provider configuration, or provider validation failure." }, "401": { "description": "Missing or invalid MindsHub credentials." }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorEnvelope" } } }, "description": "The organization has neither wallet credit nor a card with a completed top-up and no payment error, and its free daily allowance is used up or shared free capacity has run out (`wallet_empty`). Add credit to lift the cap; `X-MindsHub-Recovery-Url` carries the console path. Allowance: https://docs.mindshub.ai/inference/billing#jev-decisions", "headers": { "X-MindsHub-Reason": { "description": "Machine-readable denial reason (`permission_denied`, `rate_limited`, `included_allowance_exhausted`, `free_air_daily_spend_fuse_exceeded`, `wallet_empty`).", "schema": { "type": "string" } }, "X-MindsHub-Recovery-Url": { "description": "Relative console URL where credit can be added.", "schema": { "type": "string" } } } }, "403": { "description": "The credential does not have permission to run this model." }, "404": { "description": "Model alias unavailable in this environment or to this account." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit. Honor Retry-After when supplied." }, "503": { "description": "MindsHub could not verify the access policy, or the provider failed. `upstream_status: 502` marks a provider connection, credential, or response failure, after which an evaluation may already have run. `upstream_status: 504` marks a provider timeout, and resending may execute a duplicate evaluation." }, "529": { "description": "Provider overload. Honor Retry-After when supplied." } }, "summary": "Evaluate typed decisions", "tags": [ "decisions" ], "x-codeSamples": [ { "label": "Python", "lang": "Python", "source": "import json\nimport os\nfrom urllib.error import HTTPError\nfrom urllib.request import Request, urlopen\n\npayload = {\n \"model\": \"jev\",\n \"state\": {\"report\": \"The outer box arrived torn. The item inside is undamaged and works normally.\"},\n \"questions\": {\n \"team\": {\n \"type\": \"choice\",\n \"instructions\": \"Which team should review this delivery report?\",\n \"criteria\": {\n \"packaging\": \"Damage to the packaging, with the item itself intact.\",\n \"product\": \"Damage to the item itself.\",\n \"other\": \"A different issue, or not enough information to identify one.\",\n },\n },\n \"replacement\": {\n \"type\": \"noul\",\n \"instructions\": \"Does the report explicitly ask for a replacement item?\",\n },\n \"damage\": {\n \"type\": \"score\",\n \"instructions\": \"How much damage does the report describe?\",\n \"criteria\": [\n \"Both packaging and item are undamaged.\",\n \"Packaging is damaged; the item is intact and usable.\",\n \"The item is damaged and cannot be used normally.\",\n ],\n },\n },\n}\n\nrequest = Request(\n \"https://api.mindshub.ai/v1/decisions\",\n headers={\"Authorization\": f\"Bearer {os.environ['MINDSHUB_API_KEY']}\", \"Content-Type\": \"application/json\"},\n data=json.dumps(payload).encode(),\n)\ntry:\n with urlopen(request, timeout=40) as response:\n result = json.load(response)\nexcept HTTPError as error:\n raise SystemExit(f\"HTTP {error.code}: {error.read().decode()}\") from None\n\nprint(json.dumps(result, indent=2))\nprint(\"Team:\", result[\"answers\"][\"team\"][\"choice\"])\nprint(\"Replacement requested (probability):\", result[\"answers\"][\"replacement\"][\"noul\"])\nprint(\"Damage (0–2):\", result[\"answers\"][\"damage\"][\"score\"])" }, { "label": "TypeScript", "lang": "TypeScript", "source": "const apiKey = process.env.MINDSHUB_API_KEY;\nif (!apiKey) throw new Error(\"Set MINDSHUB_API_KEY to your MindsHub API key.\");\n\nconst response = await fetch(\"https://api.mindshub.ai/v1/decisions\", {\n method: \"POST\",\n headers: {\n Authorization: `Bearer ${apiKey}`,\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n model: \"jev\",\n state: { report: \"The outer box arrived torn. The item inside is undamaged and works normally.\" },\n questions: {\n team: {\n type: \"choice\",\n instructions: \"Which team should review this delivery report?\",\n criteria: {\n packaging: \"Damage to the packaging, with the item itself intact.\",\n product: \"Damage to the item itself.\",\n other: \"A different issue, or not enough information to identify one.\",\n },\n },\n replacement: {\n type: \"noul\",\n instructions: \"Does the report explicitly ask for a replacement item?\",\n },\n damage: {\n type: \"score\",\n instructions: \"How much damage does the report describe?\",\n criteria: [\n \"Both packaging and item are undamaged.\",\n \"Packaging is damaged; the item is intact and usable.\",\n \"The item is damaged and cannot be used normally.\",\n ],\n },\n },\n }),\n signal: AbortSignal.timeout(40_000),\n});\nif (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);\nconst result = await response.json();\nconsole.log(JSON.stringify(result, null, 2));\nconsole.log(\"Team:\", result.answers.team.choice);\nconsole.log(\"Replacement requested (probability):\", result.answers.replacement.noul);\nconsole.log(\"Damage (0–2):\", result.answers.damage.score);" } ] } }, "/v1/embeddings": { "post": { "description": "OpenAI embeddings on an embedding alias (`embed-small`). Always bills to the wallet, never to the included allowance. The response's `model` names the model that served.", "operationId": "createEmbedding", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingsRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingsResponse" } } }, "description": "The vectors, one per input." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorEnvelope" } } }, "description": "Malformed body, or a parameter the target model cannot honor and that is refused rather than dropped (`param_not_supported`, `invalid_param`, `max_tokens_exceeded`, `model_not_configured`)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorEnvelope" } } }, "description": "Missing or invalid `Authorization: Bearer mdb_…` (`invalid_credentials`)." }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorEnvelope" } } }, "description": "The wallet is empty and this model is not covered by the included allowance (`wallet_empty`).", "headers": { "X-MindsHub-Reason": { "description": "Machine-readable denial reason (`permission_denied`, `rate_limited`, `included_allowance_exhausted`, `free_air_daily_spend_fuse_exceeded`, `wallet_empty`).", "schema": { "type": "string" } }, "X-MindsHub-Recovery-Url": { "description": "Relative console URL where credit can be added.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorEnvelope" } } }, "description": "The key is valid but not permitted here (`permission_denied`). When an administrator in your organization restricted the model, `error.deny_detail` and `X-MindsHub-Deny-Detail` read `model_restricted`: choose another model, since credit does not lift it.", "headers": { "X-MindsHub-Deny-Detail": { "description": "The specific cause behind `permission_denied`. `model_restricted` when an administrator in your organization restricted the model; the body's `error.deny_detail` carries the same value. Absent on every other 403.", "schema": { "type": "string" } }, "X-MindsHub-Reason": { "description": "Machine-readable denial reason (`permission_denied`, `rate_limited`, `included_allowance_exhausted`, `free_air_daily_spend_fuse_exceeded`, `wallet_empty`).", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorEnvelope" } } }, "description": "Unknown model alias (`model_not_found`)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorEnvelope" } } }, "description": "Too fast (`rate_limited`, retry after `Retry-After`), the included allowance is exhausted (`included_allowance_exhausted`), or free serving is paused until the daily budget resets (`free_air_daily_spend_fuse_exceeded`). The last two carry body `reset_at` and `X-MindsHub-Reset-At`, and `x-should-retry: false`; adding credit lifts either immediately. An organization with no included allowance gets `included_allowance_exhausted` with no `reset_at`, because nothing refills; only credit lifts it.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-MindsHub-Reason": { "description": "Machine-readable denial reason (`permission_denied`, `rate_limited`, `included_allowance_exhausted`, `free_air_daily_spend_fuse_exceeded`, `wallet_empty`).", "schema": { "type": "string" } }, "X-MindsHub-Reset-At": { "description": "ISO-8601 instant the allowance refills or free serving resumes. Absent on `included_allowance_exhausted` when the organization has no included allowance.", "schema": { "type": "string" } }, "x-should-retry": { "description": "`false` on `included_allowance_exhausted` and `free_air_daily_spend_fuse_exceeded`, so the OpenAI and Anthropic SDKs return the error on the first attempt instead of retrying it. Absent on `rate_limited`, which is worth retrying.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorEnvelope" } } }, "description": "The authorization gate is unavailable (`policy_unavailable`). Retry." } }, "summary": "Create embeddings", "tags": [ "embeddings" ], "x-codeSamples": [ { "label": "Python", "lang": "Python", "source": "import os\n\nfrom openai import OpenAI\n\nclient = OpenAI(base_url=\"https://api.mindshub.ai/v1\", api_key=os.environ[\"MINDSHUB_API_KEY\"])\n\nresponse = client.embeddings.create(model=\"embed-small\", input=[\"first text\", \"second text\"])\nvectors = [item.embedding for item in response.data]" }, { "label": "TypeScript", "lang": "TypeScript", "source": "import OpenAI from \"openai\";\n\nconst client = new OpenAI({ baseURL: \"https://api.mindshub.ai/v1\", apiKey: process.env.MINDSHUB_API_KEY });\n\nconst response = await client.embeddings.create({ model: \"embed-small\", input: [\"first text\", \"second text\"] });\nconst vectors = response.data.map((item) => item.embedding);" } ] } }, "/v1/messages": { "post": { "description": "Anthropic Messages, on any model in the catalog. Authenticate with `Authorization: Bearer` (the SDK's `auth_token`), never `x-api-key`. `model` takes a catalog alias or a real Claude model name. Set `stream: true` for the Anthropic event sequence. The response's `model` names the model that served (`mindshub_air` and `mindshub_blaze` echo what you sent).", "operationId": "createMessage", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicMessagesRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicMessage" } }, "text/event-stream": { "description": "When `stream` is true: `message_start` → `content_block_*` → `message_delta` → `message_stop`, with one `ping` after `message_start`.", "schema": { "type": "string" } } }, "description": "The message.", "headers": { "X-MindsHub-Attempts": { "description": "Upstream attempts the request took, requested model and fallbacks together. `1` means the first try answered. Never sent on a stream whose 200 went out early because its response took more than 90 seconds to start, so there its absence says nothing.", "schema": { "type": "integer" } }, "X-MindsHub-Clamped-Params": { "description": "Parameters adjusted to the model's range, as `name=requested>applied`. Absent when nothing was clamped. Never sent on a stream whose 200 went out early because its response took more than 90 seconds to start, so there its absence says nothing.", "schema": { "type": "string" } }, "X-MindsHub-Dropped-Content": { "description": "Comma-separated categories of request *structure* the target model could not take: content blocks and per-block keys, message fields, tool keys, and tool schemas rewritten into the target's dialect (e.g. `block_field.cache_control,content_block.thinking,tool_schema.gemini_openapi`). Category labels, not an inventory, and capped at 16 with a trailing `more.N`. Absent when nothing was dropped. Never sent on a stream whose 200 went out early because its response took more than 90 seconds to start, so there its absence says nothing.", "schema": { "type": "string" } }, "X-MindsHub-Dropped-Params": { "description": "Comma-separated parameters the target model could not take and that were dropped. Absent when nothing was dropped. Never sent on a stream whose 200 went out early because its response took more than 90 seconds to start, so there its absence says nothing.", "schema": { "type": "string" } }, "X-MindsHub-Failover": { "description": "`true` when a fallback model produced the response, `false` when the requested model did. Present, on errors too, once the request reached a model. Never sent on a stream whose 200 went out early because its response took more than 90 seconds to start, so there its absence says nothing. On such a stream, read the `mindshub` field of its last event instead (`message_delta` on Messages). A Chat Completions or Messages stream that fails after its early 200 carries no failover signal at all.", "schema": { "enum": [ "true", "false" ], "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicErrorEnvelope" } } }, "description": "Malformed body, or a parameter the target model cannot honor and that is refused rather than dropped (`param_not_supported`, `invalid_param`, `max_tokens_exceeded`, `model_not_configured`)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicErrorEnvelope" } } }, "description": "Missing or invalid `Authorization: Bearer mdb_…` (`invalid_credentials`)." }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicErrorEnvelope" } } }, "description": "The wallet is empty and this model is not covered by the included allowance (`wallet_empty`). Typed `invalid_request_error` on this lane; read the HTTP status.", "headers": { "X-MindsHub-Reason": { "description": "Machine-readable denial reason (`permission_denied`, `rate_limited`, `included_allowance_exhausted`, `free_air_daily_spend_fuse_exceeded`, `wallet_empty`).", "schema": { "type": "string" } }, "X-MindsHub-Recovery-Url": { "description": "Relative console URL where credit can be added.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicErrorEnvelope" } } }, "description": "The key is valid but not permitted here (`permission_denied`). When an administrator in your organization restricted the model, `error.deny_detail` and `X-MindsHub-Deny-Detail` read `model_restricted`: choose another model, since credit does not lift it.", "headers": { "X-MindsHub-Deny-Detail": { "description": "The specific cause behind `permission_denied`. `model_restricted` when an administrator in your organization restricted the model; the body's `error.deny_detail` carries the same value. Absent on every other 403.", "schema": { "type": "string" } }, "X-MindsHub-Reason": { "description": "Machine-readable denial reason (`permission_denied`, `rate_limited`, `included_allowance_exhausted`, `free_air_daily_spend_fuse_exceeded`, `wallet_empty`).", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicErrorEnvelope" } } }, "description": "Unknown model alias, or a `claude…` name with no recognizable family (`not_found_error`)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicErrorEnvelope" } } }, "description": "Too fast (`rate_limited`, retry after `Retry-After`), the included allowance is exhausted (`included_allowance_exhausted`), or free serving is paused until the daily budget resets (`free_air_daily_spend_fuse_exceeded`). The last two carry body `reset_at` and `X-MindsHub-Reset-At`, and `x-should-retry: false`; adding credit lifts either immediately. An organization with no included allowance gets `included_allowance_exhausted` with no `reset_at`, because nothing refills; only credit lifts it.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-MindsHub-Reason": { "description": "Machine-readable denial reason (`permission_denied`, `rate_limited`, `included_allowance_exhausted`, `free_air_daily_spend_fuse_exceeded`, `wallet_empty`).", "schema": { "type": "string" } }, "X-MindsHub-Reset-At": { "description": "ISO-8601 instant the allowance refills or free serving resumes. Absent on `included_allowance_exhausted` when the organization has no included allowance.", "schema": { "type": "string" } }, "x-should-retry": { "description": "`false` on `included_allowance_exhausted` and `free_air_daily_spend_fuse_exceeded`, so the OpenAI and Anthropic SDKs return the error on the first attempt instead of retrying it. Absent on `rate_limited`, which is worth retrying.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicErrorEnvelope" } } }, "description": "The authorization gate is unavailable (`policy_unavailable`). Retry. Typed `api_error` on this lane." } }, "summary": "Create a message", "tags": [ "messages" ], "x-codeSamples": [ { "label": "Python", "lang": "Python", "source": "import os\n\nimport anthropic\n\nclient = anthropic.Anthropic(base_url=\"https://api.mindshub.ai\", auth_token=os.environ[\"MINDSHUB_API_KEY\"])\n\nmessage = client.messages.create(\n model=\"mindshub_air\",\n max_tokens=1024,\n messages=[{\"role\": \"user\", \"content\": \"What is the capital of Australia?\"}],\n)\nprint(message.content[0].text)" }, { "label": "TypeScript", "lang": "TypeScript", "source": "import Anthropic from \"@anthropic-ai/sdk\";\n\nconst client = new Anthropic({ baseURL: \"https://api.mindshub.ai\", authToken: process.env.MINDSHUB_API_KEY });\n\nconst message = await client.messages.create({\n model: \"mindshub_air\",\n max_tokens: 1024,\n messages: [{ role: \"user\", content: \"What is the capital of Australia?\" }],\n});\nconsole.log(message.content[0]);" } ] } }, "/v1/messages/count_tokens": { "post": { "description": "Prompt tokens a Messages request would consume. Exact for a concrete Claude model name; an estimate from the platform's Claude counting model for any other alias. Free and unmetered.", "operationId": "countMessageTokens", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicCountTokensRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountTokensResponse" } } }, "description": "The count." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicErrorEnvelope" } } }, "description": "Malformed body, or a parameter the target model cannot honor and that is refused rather than dropped (`param_not_supported`, `invalid_param`, `max_tokens_exceeded`, `model_not_configured`)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicErrorEnvelope" } } }, "description": "Missing or invalid `Authorization: Bearer mdb_…` (`invalid_credentials`)." } }, "summary": "Count tokens", "tags": [ "messages" ], "x-codeSamples": [ { "label": "Python", "lang": "Python", "source": "import os\n\nimport anthropic\n\nclient = anthropic.Anthropic(base_url=\"https://api.mindshub.ai\", auth_token=os.environ[\"MINDSHUB_API_KEY\"])\n\ncount = client.messages.count_tokens(\n model=\"sonnet\",\n messages=[{\"role\": \"user\", \"content\": \"What is the capital of Australia?\"}],\n)\nprint(count.input_tokens)" }, { "label": "TypeScript", "lang": "TypeScript", "source": "import Anthropic from \"@anthropic-ai/sdk\";\n\nconst client = new Anthropic({ baseURL: \"https://api.mindshub.ai\", authToken: process.env.MINDSHUB_API_KEY });\n\nconst count = await client.messages.countTokens({\n model: \"sonnet\",\n messages: [{ role: \"user\", content: \"What is the capital of Australia?\" }],\n});\nconsole.log(count.input_tokens);" } ] } }, "/v1/models": { "get": { "description": "Every alias in the catalog with the metadata a model picker needs, including whether your organization can call it right now. Free to call, never paginated. Both the OpenAI and Anthropic SDKs' `models.list()` parse it. Claude Code and Codex receive client-specific shapes, detected from their headers.", "operationId": "listModels", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelList" } } }, "description": "The catalog." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorEnvelope" } } }, "description": "Missing or invalid `Authorization: Bearer mdb_…` (`invalid_credentials`)." } }, "summary": "List models", "tags": [ "models" ], "x-codeSamples": [ { "label": "Python", "lang": "Python", "source": "import os\n\nfrom openai import OpenAI\n\nclient = OpenAI(base_url=\"https://api.mindshub.ai/v1\", api_key=os.environ[\"MINDSHUB_API_KEY\"])\n\nfor model in client.models.list():\n print(model.id)" }, { "label": "TypeScript", "lang": "TypeScript", "source": "import OpenAI from \"openai\";\n\nconst client = new OpenAI({ baseURL: \"https://api.mindshub.ai/v1\", apiKey: process.env.MINDSHUB_API_KEY });\n\nfor await (const model of client.models.list()) {\n console.log(model.id);\n}" } ] } }, "/v1/responses": { "post": { "description": "OpenAI Responses, on any model in the catalog. Send `model` and `input`; set `stream: true` for the typed `response.*` event stream. Turns are stored for 30 days unless `store: false` and chain by `previous_response_id`. `conversation`, `prompt` and `context_management` are refused with a 400. The response's `model` names the model that served (`mindshub_air` and `mindshub_blaze` return their own alias).", "operationId": "createResponse", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIResponsesRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseObject" } } }, "description": "The response object; `status` is `completed`, `incomplete`, or `failed`.", "headers": { "X-MindsHub-Attempts": { "description": "Upstream attempts the request took, requested model and fallbacks together. `1` means the first try answered. Never sent on a stream whose 200 went out early because its response took more than 90 seconds to start, so there its absence says nothing.", "schema": { "type": "integer" } }, "X-MindsHub-Chain-Truncated": { "description": "Present when a `previous_response_id` chain was cut short (expired, deleted, or past the 25-turn walk). Never sent on a stream whose 200 went out early because its response took more than 90 seconds to start, so there its absence says nothing.", "schema": { "type": "string" } }, "X-MindsHub-Clamped-Params": { "description": "Parameters adjusted to the model's range, as `name=requested>applied`. Absent when nothing was clamped. Never sent on a stream whose 200 went out early because its response took more than 90 seconds to start, so there its absence says nothing.", "schema": { "type": "string" } }, "X-MindsHub-Dropped-Content": { "description": "Comma-separated categories of request *structure* the target model could not take: content blocks and per-block keys, message fields, tool keys, and tool schemas rewritten into the target's dialect (e.g. `block_field.cache_control,content_block.thinking,tool_schema.gemini_openapi`). Category labels, not an inventory, and capped at 16 with a trailing `more.N`. Absent when nothing was dropped. Never sent on a stream whose 200 went out early because its response took more than 90 seconds to start, so there its absence says nothing.", "schema": { "type": "string" } }, "X-MindsHub-Dropped-Params": { "description": "Comma-separated parameters the target model could not take and that were dropped. Absent when nothing was dropped. Never sent on a stream whose 200 went out early because its response took more than 90 seconds to start, so there its absence says nothing.", "schema": { "type": "string" } }, "X-MindsHub-Failover": { "description": "`true` when a fallback model produced the response, `false` when the requested model did. Present, on errors too, once the request reached a model. Never sent on a stream whose 200 went out early because its response took more than 90 seconds to start, so there its absence says nothing. On such a stream, read the `mindshub` field of its last event instead (`message_delta` on Messages). A Chat Completions or Messages stream that fails after its early 200 carries no failover signal at all.", "schema": { "enum": [ "true", "false" ], "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorEnvelope" } } }, "description": "Malformed body, or a parameter the target model cannot honor and that is refused rather than dropped (`param_not_supported`, `invalid_param`, `max_tokens_exceeded`, `model_not_configured`). Also `unsupported_parameter` for `conversation`, `prompt`, or `context_management`." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorEnvelope" } } }, "description": "Missing or invalid `Authorization: Bearer mdb_…` (`invalid_credentials`)." }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorEnvelope" } } }, "description": "The wallet is empty and this model is not covered by the included allowance (`wallet_empty`).", "headers": { "X-MindsHub-Reason": { "description": "Machine-readable denial reason (`permission_denied`, `rate_limited`, `included_allowance_exhausted`, `free_air_daily_spend_fuse_exceeded`, `wallet_empty`).", "schema": { "type": "string" } }, "X-MindsHub-Recovery-Url": { "description": "Relative console URL where credit can be added.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorEnvelope" } } }, "description": "The key is valid but not permitted here (`permission_denied`). When an administrator in your organization restricted the model, `error.deny_detail` and `X-MindsHub-Deny-Detail` read `model_restricted`: choose another model, since credit does not lift it.", "headers": { "X-MindsHub-Deny-Detail": { "description": "The specific cause behind `permission_denied`. `model_restricted` when an administrator in your organization restricted the model; the body's `error.deny_detail` carries the same value. Absent on every other 403.", "schema": { "type": "string" } }, "X-MindsHub-Reason": { "description": "Machine-readable denial reason (`permission_denied`, `rate_limited`, `included_allowance_exhausted`, `free_air_daily_spend_fuse_exceeded`, `wallet_empty`).", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorEnvelope" } } }, "description": "Unknown model alias (`model_not_found`) or unknown, expired, or deleted `previous_response_id` (`previous_response_not_found`)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorEnvelope" } } }, "description": "Too fast (`rate_limited`, retry after `Retry-After`), the included allowance is exhausted (`included_allowance_exhausted`), or free serving is paused until the daily budget resets (`free_air_daily_spend_fuse_exceeded`). The last two carry body `reset_at` and `X-MindsHub-Reset-At`, and `x-should-retry: false`; adding credit lifts either immediately. An organization with no included allowance gets `included_allowance_exhausted` with no `reset_at`, because nothing refills; only credit lifts it.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-MindsHub-Reason": { "description": "Machine-readable denial reason (`permission_denied`, `rate_limited`, `included_allowance_exhausted`, `free_air_daily_spend_fuse_exceeded`, `wallet_empty`).", "schema": { "type": "string" } }, "X-MindsHub-Reset-At": { "description": "ISO-8601 instant the allowance refills or free serving resumes. Absent on `included_allowance_exhausted` when the organization has no included allowance.", "schema": { "type": "string" } }, "x-should-retry": { "description": "`false` on `included_allowance_exhausted` and `free_air_daily_spend_fuse_exceeded`, so the OpenAI and Anthropic SDKs return the error on the first attempt instead of retrying it. Absent on `rate_limited`, which is worth retrying.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorEnvelope" } } }, "description": "The authorization gate is unavailable (`policy_unavailable`). Retry." } }, "summary": "Create a response", "tags": [ "responses" ], "x-codeSamples": [ { "label": "Python", "lang": "Python", "source": "import os\n\nfrom openai import OpenAI\n\nclient = OpenAI(base_url=\"https://api.mindshub.ai/v1\", api_key=os.environ[\"MINDSHUB_API_KEY\"])\n\nresponse = client.responses.create(model=\"mindshub_air\", input=\"What is the capital of Australia?\")\nprint(response.output_text)" }, { "label": "TypeScript", "lang": "TypeScript", "source": "import OpenAI from \"openai\";\n\nconst client = new OpenAI({ baseURL: \"https://api.mindshub.ai/v1\", apiKey: process.env.MINDSHUB_API_KEY });\n\nconst response = await client.responses.create({ model: \"mindshub_air\", input: \"What is the capital of Australia?\" });\nconsole.log(response.output_text);" } ] } }, "/v1/responses/{response_id}": { "delete": { "description": "Hard delete: the content is gone, not flagged. Deleting an absent id is a 404, as on OpenAI.", "operationId": "deleteResponse", "parameters": [ { "in": "path", "name": "response_id", "required": true, "schema": { "title": "Response Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseDeleted" } } }, "description": "Deleted." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorEnvelope" } } }, "description": "Missing or invalid `Authorization: Bearer mdb_…` (`invalid_credentials`)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorEnvelope" } } }, "description": "No stored response with this id, or it has expired (`response_not_found`)." } }, "summary": "Delete a stored response", "tags": [ "responses" ], "x-codeSamples": [ { "label": "Python", "lang": "Python", "source": "import os\n\nfrom openai import OpenAI\n\nclient = OpenAI(base_url=\"https://api.mindshub.ai/v1\", api_key=os.environ[\"MINDSHUB_API_KEY\"])\n\ndeleted = client.responses.delete(\"resp_9f2c1ae0b4d8\")\nprint(deleted.deleted)" }, { "label": "TypeScript", "lang": "TypeScript", "source": "import OpenAI from \"openai\";\n\nconst client = new OpenAI({ baseURL: \"https://api.mindshub.ai/v1\", apiKey: process.env.MINDSHUB_API_KEY });\n\nconst deleted = await client.responses.delete(\"resp_9f2c1ae0b4d8\");\nconsole.log(deleted.deleted);" } ] }, "get": { "description": "The response as it was returned, output items included. Stored turns expire after 30 days.", "operationId": "getResponse", "parameters": [ { "in": "path", "name": "response_id", "required": true, "schema": { "title": "Response Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseObject" } } }, "description": "The stored response." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorEnvelope" } } }, "description": "Missing or invalid `Authorization: Bearer mdb_…` (`invalid_credentials`)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorEnvelope" } } }, "description": "No stored response with this id, or it has expired (`response_not_found`)." } }, "summary": "Retrieve a stored response", "tags": [ "responses" ], "x-codeSamples": [ { "label": "Python", "lang": "Python", "source": "import os\n\nfrom openai import OpenAI\n\nclient = OpenAI(base_url=\"https://api.mindshub.ai/v1\", api_key=os.environ[\"MINDSHUB_API_KEY\"])\n\nstored = client.responses.retrieve(\"resp_9f2c1ae0b4d8\")\nprint(stored.status, stored.output_text)" }, { "label": "TypeScript", "lang": "TypeScript", "source": "import OpenAI from \"openai\";\n\nconst client = new OpenAI({ baseURL: \"https://api.mindshub.ai/v1\", apiKey: process.env.MINDSHUB_API_KEY });\n\nconst stored = await client.responses.retrieve(\"resp_9f2c1ae0b4d8\");\nconsole.log(stored.status, stored.output_text);" } ] } }, "/v1/responses/{response_id}/cancel": { "post": { "description": "Only a response created with `background: true` can be cancelled, as on OpenAI. Every request completes synchronously, so a stored background response is already terminal and this returns it unchanged; any other response is a 400.", "operationId": "cancelResponse", "parameters": [ { "in": "path", "name": "response_id", "required": true, "schema": { "title": "Response Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseObject" } } }, "description": "The stored response, already terminal." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorEnvelope" } } }, "description": "The response was not created with `background: true`." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorEnvelope" } } }, "description": "Missing or invalid `Authorization: Bearer mdb_…` (`invalid_credentials`)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorEnvelope" } } }, "description": "No stored response with this id, or it has expired (`response_not_found`)." } }, "summary": "Cancel a background response", "tags": [ "responses" ], "x-codeSamples": [ { "label": "Python", "lang": "Python", "source": "import os\n\nfrom openai import OpenAI\n\nclient = OpenAI(base_url=\"https://api.mindshub.ai/v1\", api_key=os.environ[\"MINDSHUB_API_KEY\"])\n\n# Only a response created with background=True can be cancelled; every request\n# completes synchronously, so this returns the finished object.\nresponse = client.responses.cancel(\"resp_9f2c1ae0b4d8\")\nprint(response.status)" }, { "label": "TypeScript", "lang": "TypeScript", "source": "import OpenAI from \"openai\";\n\nconst client = new OpenAI({ baseURL: \"https://api.mindshub.ai/v1\", apiKey: process.env.MINDSHUB_API_KEY });\n\n// Only a response created with background: true can be cancelled; every request\n// completes synchronously, so this returns the finished object.\nconst response = await client.responses.cancel(\"resp_9f2c1ae0b4d8\");\nconsole.log(response.status);" } ] } }, "/v1/responses/{response_id}/input_items": { "get": { "description": "That turn's own input items, not the inherited history. Paginated with `after`.", "operationId": "listResponseInputItems", "parameters": [ { "in": "path", "name": "response_id", "required": true, "schema": { "title": "Response Id", "type": "string" } }, { "in": "query", "name": "after", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "After" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "order", "required": false, "schema": { "default": "desc", "title": "Order", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseInputItemList" } } }, "description": "One page of input items." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorEnvelope" } } }, "description": "Missing or invalid `Authorization: Bearer mdb_…` (`invalid_credentials`)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorEnvelope" } } }, "description": "No stored response with this id, or it has expired (`response_not_found`)." } }, "summary": "List a stored response's input items", "tags": [ "responses" ], "x-codeSamples": [ { "label": "Python", "lang": "Python", "source": "import os\n\nfrom openai import OpenAI\n\nclient = OpenAI(base_url=\"https://api.mindshub.ai/v1\", api_key=os.environ[\"MINDSHUB_API_KEY\"])\n\npage = client.responses.input_items.list(\"resp_9f2c1ae0b4d8\", limit=20, order=\"desc\")\nfor item in page.data:\n print(item.type)" }, { "label": "TypeScript", "lang": "TypeScript", "source": "import OpenAI from \"openai\";\n\nconst client = new OpenAI({ baseURL: \"https://api.mindshub.ai/v1\", apiKey: process.env.MINDSHUB_API_KEY });\n\nconst page = await client.responses.inputItems.list(\"resp_9f2c1ae0b4d8\", { limit: 20, order: \"desc\" });\nfor (const item of page.data) console.log(item.type);" } ] } }, "/v1/traces": { "get": { "description": "Per-request records for your organization, newest first. Members see their own requests; admins see the organization's. Available where the organization has traces enabled; otherwise a 404.", "operationId": "listTraces", "parameters": [ { "description": "1-based page number", "in": "query", "name": "page", "required": false, "schema": { "default": 1, "description": "1-based page number", "minimum": 1, "title": "Page", "type": "integer" } }, { "description": "Page size", "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "description": "Page size", "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Only traces from the last N hours (legacy; prefer from/to)", "in": "query", "name": "hours", "required": false, "schema": { "anyOf": [ { "maximum": 8760, "minimum": 1, "type": "integer" }, { "type": "null" } ], "description": "Only traces from the last N hours (legacy; prefer from/to)", "title": "Hours" } }, { "description": "Only traces at or after this ISO-8601 instant", "in": "query", "name": "from", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Only traces at or after this ISO-8601 instant", "title": "From" } }, { "description": "Only traces at or before this ISO-8601 instant", "in": "query", "name": "to", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Only traces at or before this ISO-8601 instant", "title": "To" } }, { "description": "Only traces belonging to this session id", "in": "query", "name": "session_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Only traces belonging to this session id", "title": "Session Id" } }, { "description": "Filter to these model aliases (repeatable)", "in": "query", "name": "model", "required": false, "schema": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Filter to these model aliases (repeatable)", "title": "Model" } }, { "description": "Exclude these model aliases (repeatable)", "in": "query", "name": "exclude_model", "required": false, "schema": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Exclude these model aliases (repeatable)", "title": "Exclude Model" } }, { "description": "Filter to these providers (repeatable)", "in": "query", "name": "provider", "required": false, "schema": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Filter to these providers (repeatable)", "title": "Provider" } }, { "description": "Exclude these providers (repeatable)", "in": "query", "name": "exclude_provider", "required": false, "schema": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Exclude these providers (repeatable)", "title": "Exclude Provider" } }, { "description": "Filter to these levels: DEFAULT (ok), ERROR (failed), UNKNOWN (unrecorded). Repeatable, OR-ed.", "in": "query", "name": "level", "required": false, "schema": { "anyOf": [ { "items": { "pattern": "^(DEFAULT|ERROR|UNKNOWN)$", "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Filter to these levels: DEFAULT (ok), ERROR (failed), UNKNOWN (unrecorded). Repeatable, OR-ed.", "title": "Level" } }, { "description": "Exclude these levels (repeatable); the NULL-safe complement of the included set.", "in": "query", "name": "exclude_level", "required": false, "schema": { "anyOf": [ { "items": { "pattern": "^(DEFAULT|ERROR|UNKNOWN)$", "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Exclude these levels (repeatable); the NULL-safe complement of the included set.", "title": "Exclude Level" } }, { "description": "Only streamed (true) or non-streamed (false) traces", "in": "query", "name": "stream", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Only streamed (true) or non-streamed (false) traces", "title": "Stream" } }, { "description": "Include probe traces: background calls a MindsHub client made on the caller's key, such as the provider-validation 'ping'. Hidden by default so the list reflects real activity; set true to show them (they drop from counts while hidden).", "in": "query", "name": "include_probes", "required": false, "schema": { "default": false, "description": "Include probe traces: background calls a MindsHub client made on the caller's key, such as the provider-validation 'ping'. Hidden by default so the list reflects real activity; set true to show them (they drop from counts while hidden).", "title": "Include Probes", "type": "boolean" } }, { "description": "Sort field", "in": "query", "name": "sort", "required": false, "schema": { "default": "timestamp", "description": "Sort field", "pattern": "^(latency_ms|timestamp)$", "title": "Sort", "type": "string" } }, { "description": "Sort direction", "in": "query", "name": "order", "required": false, "schema": { "default": "desc", "description": "Sort direction", "pattern": "^(asc|desc)$", "title": "Order", "type": "string" } }, { "description": "Admin-only: narrow to one user's traces (ignored for members)", "in": "query", "name": "user_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Admin-only: narrow to one user's traces (ignored for members)", "title": "User Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TraceListResponse" } } }, "description": "Successful Response" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetailError" } } }, "description": "Invalid filter or paging parameter." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetailError" } } }, "description": "Missing or invalid `Authorization: Bearer mdb_…`." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetailError" } } }, "description": "Traces are not enabled for this organization, or the trace does not exist or is not visible to this caller. The two are deliberately indistinguishable." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetailError" } } }, "description": "The trace detail backend is unavailable; the listing still works." } }, "summary": "List traces", "tags": [ "traces" ], "x-codeSamples": [ { "label": "Python", "lang": "Python", "source": "import os\n\nimport httpx\n\nheaders = {\"Authorization\": f\"Bearer {os.environ['MINDSHUB_API_KEY']}\"}\npage = httpx.get(\n \"https://api.mindshub.ai/v1/traces\",\n params={\"page\": 1, \"limit\": 25, \"model\": \"sonnet\"},\n headers=headers,\n).json()\nfor trace in page[\"traces\"]:\n print(trace[\"id\"], trace[\"model\"])" }, { "label": "TypeScript", "lang": "TypeScript", "source": "const headers = { Authorization: `Bearer ${process.env.MINDSHUB_API_KEY}` };\nconst params = new URLSearchParams({ page: \"1\", limit: \"25\", model: \"sonnet\" });\nconst page = await fetch(`https://api.mindshub.ai/v1/traces?${params}`, { headers }).then((r) => r.json());\nfor (const trace of page.traces) console.log(trace.id, trace.model);" } ] } }, "/v1/traces/{trace_id}": { "get": { "description": "One trace with its span waterfall and payloads. Content is visible only to the member who made the request. 403 when you can see the organization's traces but this one is another member's; 404 when it does not exist or is not visible to you.", "operationId": "getTrace", "parameters": [ { "in": "path", "name": "trace_id", "required": true, "schema": { "title": "Trace Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TraceDetail" } } }, "description": "Successful Response" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetailError" } } }, "description": "Invalid filter or paging parameter." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetailError" } } }, "description": "Missing or invalid `Authorization: Bearer mdb_…`." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetailError" } } }, "description": "The trace is another member's. Admins see it in the list but cannot open its content." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetailError" } } }, "description": "Traces are not enabled for this organization, or the trace does not exist or is not visible to this caller. The two are deliberately indistinguishable." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetailError" } } }, "description": "The trace detail backend is unavailable; the listing still works." } }, "summary": "Get a trace", "tags": [ "traces" ], "x-codeSamples": [ { "label": "Python", "lang": "Python", "source": "import os\n\nimport httpx\n\nheaders = {\"Authorization\": f\"Bearer {os.environ['MINDSHUB_API_KEY']}\"}\ntrace = httpx.get(\"https://api.mindshub.ai/v1/traces/tr_1a2b3c\", headers=headers).json()\nprint(trace[\"status\"], len(trace[\"spans\"]))" }, { "label": "TypeScript", "lang": "TypeScript", "source": "const headers = { Authorization: `Bearer ${process.env.MINDSHUB_API_KEY}` };\nconst trace = await fetch(\"https://api.mindshub.ai/v1/traces/tr_1a2b3c\", { headers }).then((r) => r.json());\nconsole.log(trace.status, trace.spans.length);" } ] } } }, "security": [ { "BearerAuth": [] } ], "servers": [ { "description": "Production", "url": "https://api.mindshub.ai" } ], "tags": [ { "description": "OpenAI Chat Completions. `POST /v1/chat/completions`.", "name": "chat" }, { "description": "OpenAI Responses, with server-side conversation state.", "name": "responses" }, { "description": "Anthropic Messages, the lane Claude Code speaks.", "name": "messages" }, { "description": "Jev typed decisions served by TypeSafe.", "name": "decisions" }, { "description": "OpenAI embeddings on the embedding aliases.", "name": "embeddings" }, { "description": "The catalog your key can see.", "name": "models" }, { "description": "Per-request records for your organization. Enabled per organization.", "name": "traces" } ] }