Skip to main content
/v1/responses is an OpenAI-compatible alternative to chat completions, aimed at reasoning models and hosted tools the provider runs on your behalf. Use it when you need controllable reasoning effort, provider-hosted capabilities like web search or code execution, or long-running work that outlives a single HTTP connection. For ordinary chat, /v1/chat/completions remains the right endpoint.

​
Reasoning effort

Reasoning models can be told how much thinking to spend:
Higher effort produces more reasoning tokens — better results on hard problems, at higher cost and latency. Reasoning tokens are billed.
Chat completions accepts the same nested reasoning object (effort, or a max_tokens thinking budget). It also still accepts the older flat reasoning_effort field; when both are sent, the reasoning object wins.

​
Hosted tools

Unlike function calling, where you execute the function, hosted tools run on the provider’s side and return their results directly. Hosted tools need a model with native Responses API support; sending one to any other model returns 400 model_capability_not_supported. Function tools work on every model.
web_search_preview forces the request into background mode. Web search is slow enough that a dropped HTTP connection would lose the billing record, so MeshAPI upgrades these requests to background: true automatically.The practical consequence: you get back a queued job, not a completed answer, even though you didn’t ask for one. Code that expects a synchronous result will break. Poll GET /v1/responses/{id} for the outcome. Models that only run as background jobs are upgraded the same way.

​
Background jobs

Set background: true for work that shouldn’t be tied to a live connection:
You receive a response id immediately, then poll:
GET /v1/responses lists your jobs. Background mode needs a model with native Responses API support (otherwise 400), and cannot be combined with service_tier: "flex".
You can have at most 10 active background jobs at once; jobs in a terminal state don’t count, and an 11th returns 429 job_limit_exceeded. Credit is reserved when a job is queued and settled when it finishes, so a queued job reduces your spendable balance before it produces anything. A balance too low to reserve returns 402 insufficient_balance.

​
Provider-specific fields

Several fields are honoured only on particular upstreams — thinking, caching, store, expire_at, and context_management among them.
An unsupported field is silently ignored, not rejected. Sending store: true to a provider that doesn’t implement it returns a perfectly normal response in which nothing was stored. Verify behaviour on the specific model you are targeting rather than assuming a field took effect.
Other supported controls include previous_response_id for continuing a conversation, max_tool_calls (1–10) to bound hosted tool usage, include for requesting extra output, and text.format for structured output.