# Supported API compatibility

ARBI uses `/v1/responses` as its canonical execution API. The TypeScript SDK adds familiar
Responses conveniences while preserving ARBI authentication, workspace authorization and
execution controls. This is a supported subset, not a drop-in replacement for every OpenAI,
Vercel or Claude SDK feature.

This table describes the current TypeScript SDK and backend contract. A deployment running an
older backend may not have a recently introduced capability. See its `/v1/docs` schema for the exact deployed fields.

| Surface | Supported behavior | Boundary |
| --- | --- | --- |
| `responses.create({ input })` | Synchronous response envelope with `output_text` | SDK input is text. Backend normalization of input arrays is not full typed input-item, image/audio or tool-result compatibility. |
| `model` | Saved `cfg-` selection and existing deployment configuration resolution | A configuration is not an `agt-` identity or an arbitrary upstream-provider override. |
| `previous_response_id` | Continue from an existing assistant `msg-` response | A conversation is `con-`; a new run/conversation ID is not introduced by the SDK handle. |
| Response envelope | Preserve `output`, `metadata`, `usage`, status and errors; add `output_text` | A failed JSON response remains failed. Inspect its status. `_request_id` is available on create when the server supplies it. |
| `stream: true` | Async iterable with `event.type`, Responses lifecycle/text/output-item events | `arbi.*` events remain ARBI extensions. Connection loss throws; a failed terminal response remains an event. |
| `background: true` | Queued response ID, then `retrieve(id)` or ARBI `attach(id)` | The SDK rejects `stream: true` plus `background: true`. The backend returns queued JSON for that combination, not a live stream. |
| `responses.retrieve(id)` | Retrieve the existing response's status and output | Existing authentication, ownership and workspace checks apply. |
| `responses.parse({ text: { format } })` | One synchronous request, validated `output_parsed`, original envelope retained | JSON Schema draft 2020-12, local references only; no Zod helper, coercion, repair or automatic resubmission. Format annotations are not assertions. Client validation compiles schemas; a CSP that forbids compilation produces `STRUCTURED_OUTPUT_VALIDATOR_UNAVAILABLE` before a request. Raw server-validated Responses remain available. |
| Structured streaming/background | Server validates final output; standalone parser can validate a completed response | Live fragments are provisional. Native-agent and slash/delegation paths reject unsupported structured requests explicitly. `json_object` and text verbosity are outside this subset. |
| Tools | ARBI document/search/tool map and existing MCP capabilities | Standard OpenAI function-tool arrays and arbitrary local JavaScript function execution are not implemented. |
| Lifecycle controls | Cancel, attach, snapshots and outcomes through the existing response handle | Breaking iteration detaches the reader. ARBI controls need not have the same URL or method shape as another provider's controls. |
| Authentication | ARBI login/session and workspace-key flow; existing key and host integrations | Changing `base_url` and supplying an unrelated provider API key is insufficient. A deployment key is not a private-workspace credential. |
| Workspace context | Current workspace by default; explicit application switching and existing resource/permission checks | Examples do not add per-call workspace headers, grant access, or enable cross-workspace search. Advanced wire fields retain their existing server checks. |
| `agt-` execution | Existing authorized agent identity and task/grant lifecycle | Choosing an agent does not mint a session or create temporary/standing access. Deferred authorization is not a model failure. |
| React UI | Shared `ArbiChat`, connected views and React Query hooks | Does not implement Vercel `useChat`'s transport protocol or replace the host's session/cache. |
| Node | ESM/CommonJS, memory key storage by default, optional explicit persistence | A browser IndexedDB polyfill is not required. Node filesystem helpers remain separate from browser imports. |
| Retries | Bounded connection retries for generated GET/HEAD; existing explicit session/state recovery | Do not automatically repeat response creation after an ambiguous network failure. Check the existing `msg-` first. |
| Legacy assistant-query route | Logged temporary compatibility alias | New SDK/generated clients use Responses. Removal is a separate change after call-log review, planned for 2026-11-01. |

## Migrating an existing integration

1. Establish the ARBI session and explicitly select a permitted workspace.
2. Start with `responses.create({ input })`, then streaming if needed. Keep the raw envelope.
3. Map provider-specific tools to supported ARBI capabilities; do not cast an incompatible tool array.
4. Keep ARBI-specific controls and permissions above the basic request/response surface.
5. Verify refusal, incomplete, cancellation, disconnect and deferred-access outcomes in your app.

A direct OpenAI client can call the documented backend subset after ARBI authentication and
workspace setup. Vercel and Claude SDKs manage different runtime/tool/UI protocols; familiarity
of concepts does not make them interchangeable imports. Use the
[quickstart](getting-started.md) for a small native ARBI integration.

## Verify a release

Maintainers with repository access check local package tarballs in normal CI and
**published npm artifacts** after releases. From the repository root with Node 22.22+:

```sh
node scripts/sdk-node-smoke.mjs --published=0.5.62
node scripts/sdk-examples-smoke.mjs --published=0.5.62
```

Substitute the exact release you are adopting. Omit `=VERSION` to use the version in the checked-out
SDK manifest; omit `--published` entirely to check locally built tarballs. The Node check covers
ESM/CommonJS/browser/testing imports, session recovery and response/stream/structured contracts
against a fake transport. The React check installs npm dependencies and builds the minimal app.
Developers do not need repository access to use the installed examples or guides.
These checks do not claim live authentication, model quality, or hosted SSO works on every deployment.
The release workflow repeats these fresh-consumer checks after publication.