AppDirect Responses API v2 API

OpenAI Responses-compatible API (v2). Supports streaming (SSE) and non-streaming runs, threaded and stateless execution, and lifecycle control (cancel / pause / resume).The shape mirrors the [official OpenAI Responses API](https://platform.openai.com/docs/api-reference/responses) for inputs, outputs, tools, and streaming events. Items below labelled **[devs.ai extension]** have no equivalent in OpenAI's spec; everything else is intended to be 1:1 compatible.### Vendor extensions used to flag devs.ai additionsEvery devs.ai-specific element in this spec is also tagged with a machine-readable [OpenAPI specification extension](https://swagger.io/docs/specification/openapi-extensions/) so tooling can detect them programmatically without parsing description text:- **`x-devs-ai-extension: true`** — applied to schemas, schema properties, parameters, response headers, and operations that have no OpenAI counterpart.- **`x-devs-ai-extension-values: [string, ...]`** — applied to enum schemas/properties whose enum is OpenAI-aligned but where devs.ai accepts/emits additional values. Lists only the extra values (e.g. `["cancelled"]` on `ResponseStatus`).- **`x-devs-ai-extension-behavior: ""`** — applied where the field name itself is OpenAI-standard but devs.ai's handling differs (e.g. `optional-on-request` on `MessageInputItem.type` because devs.ai accepts the field being omitted while OpenAI requires it).### devs.ai ExtensionsA single reference list of every devs.ai-specific addition exposed by this API. Each entry below is also marked `**[devs.ai extension]**` at its source and carries one of the `x-devs-ai-extension*` vendor extensions described above.**Request fields (`CreateResponseRequest`)**- `chat_mode` — `execute` / `chat` / `plan` execution mode.- `user_secrets` — short-lived per-request API keys / secrets for tools.- `thread_mode` — concurrent-request handling on an existing thread (`collect` / `steer` / `interrupt` / `force`).- `options` — internal devs.ai chat options (provider routing, tracing, etc.).- `reasoning.effort` extra values `none` and `xhigh` (in addition to OpenAI's `minimal` / `low` / `medium` / `high`).**Input content-part flags**- `input_text.invisible` / `input_image.invisible` / `input_file.invisible` — content sent to the model but hidden from end-user transcripts.- `input_text.metadata` — arbitrary metadata attached to a content part (not forwarded to the model).- `output_text.logprobs` (when `output_text` appears inside an `OutputMessageInputItem`).**Input item enum**- `FunctionCallOutputInputItem.status` uses `["success", "error", "cancelled"]` instead of OpenAI's `["in_progress", "completed", "incomplete"]` (incompatible enum).**Tools (`ToolDefinition`)** — only `function` and `web_search` mirror OpenAI; everything below is devs.ai-specific.- `python` — emits `server_tool_call` items (not OpenAI's `code_interpreter_call`).- `image_generation` — shares the type name with OpenAI but uses devs.ai's input shape and emits `server_tool_call` items.- `mcp_server` — references a configured devs.ai MCP integration; does not emit OpenAI's `mcp_list_tools` discovery events or `mcp_approval_request` / `mcp_approval_response` items.- `spreadsheet`, `memory`, `sandbox`, `deep_research` — no OpenAI counterpart.- `web_search.includeXSearch` — extra X (Twitter) search inclusion flag.**Output items (`OutputItem`)**- `server_tool_call` and `server_tool_call_output` — emitted instead of OpenAI's `code_interpreter_call` / `image_generation_call` items for devs.ai's server-side tools.**Response fields (`Response`)**- `selection_metadata` — model routing / selection metadata (chosen provider, fallback chain, latency hints).- `status` extra value `cancelled` (in addition to OpenAI's `in_progress` / `completed` / `failed` / `incomplete`).- `incomplete_details.reason` extra value `paused` (in addition to OpenAI's `max_output_tokens` / `content_filter`).**Streaming events** (full list and payloads in the `x-streaming-events` reference under `components`)- `response.server_tool_call.in_progress` / `.completed` / `.failed`.- `response.server_tool_call_arguments.delta` / `.done`.- `response.subagent.started` / `.progress` / `.completed`.- `response.output_item.added.status_hints` (optional field on `response.output_item.added`).- Every event payload includes a monotonically increasing `sequence_number` field.- Terminal sentinel `event: done` / `data: [DONE]` after the last lifecycle event.**Endpoints / headers**- `POST /api/v2/responses/{responseId}/pause` — pause an active threaded response run.- `POST /api/v2/responses/{responseId}/resume` — resume a paused threaded response run, optionally supplying tool outputs.- `GET /api/v2/responses/{responseId}/stream` — reconnect to an in-flight SSE stream after a network drop, resuming from `lastSequence`.- `POST /api/v2/responses/{responseId}/deep-research/resume` — approve / deny / clarify a paused deep research subagent.- `x-stream-chat-id` response header on streaming `POST /api/v2/responses` and on the `/stream` reconnect endpoint.