# AppDirect Responses API v2 API **Canonical:** https://apis.io/apis/appdirect/appdirect-responses-api-v2-api/ **Provider:** AppDirect — https://apis.io/providers/appdirect/ **Base URL:** https://marketplace.appdirect.com/api **Documentation:** https://developer.appdirect.com/references-api AppDirect Responses API v2 API is one of 75 APIs that [AppDirect](https://apis.io/providers/appdirect/) publishes on the [APIs.io](https://apis.io/) network, described by a machine-readable OpenAPI specification. Tagged areas include Responses API v2. The published artifact set on APIs.io includes an OpenAPI specification. 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 additions Every 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 Extensions A 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. ## Machine-readable artifacts (1) - **OpenAPI** — https://raw.githubusercontent.com/api-evangelist/appdirect/refs/heads/main/openapi/appdirect-responses-api-v2-api-openapi.yml ## Other AppDirect APIs (12) - [AppDirect AI Embed API](https://apis.io/apis/appdirect/appdirect-ai-embed-api/) - [AppDirect AI Management API](https://apis.io/apis/appdirect/appdirect-ai-management-api/) - [AppDirect AI Models API](https://apis.io/apis/appdirect/appdirect-ai-models-api/) - [AppDirect AI User Inputs API](https://apis.io/apis/appdirect/appdirect-ai-user-inputs-api/) - [AppDirect Answer API](https://apis.io/apis/appdirect/appdirect-answer-api/) - [AppDirect API Keys API](https://apis.io/apis/appdirect/appdirect-api-keys-api/) - [AppDirect AppResellerAccount API](https://apis.io/apis/appdirect/appdirect-appreselleraccount-api/) - [AppDirect AppResellerAssignment API](https://apis.io/apis/appdirect/appdirect-appresellerassignment-api/) - [AppDirect AppResellerCatalog API](https://apis.io/apis/appdirect/appdirect-appresellercatalog-api/) - [AppDirect AppResellerCompanyAssociation API](https://apis.io/apis/appdirect/appdirect-appresellercompanyassociation-api/) - [AppDirect AppResellerLeads API](https://apis.io/apis/appdirect/appdirect-appresellerleads-api/) - [AppDirect AppResellerOpportunities API](https://apis.io/apis/appdirect/appdirect-appreselleropportunities-api/) ## Tags Responses API v2 --- Profiled by [API Evangelist](https://apievangelist.com) and published on [APIs.io](https://apis.io/apis/appdirect/appdirect-responses-api-v2-api/). The API's provider profile, Kin Score and agent-readiness rating are at https://apis.io/providers/appdirect/.