> ## Documentation Index
> Fetch the complete documentation index at: https://openagentcore-codex-e2b-unified-pause.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents API coverage ledger

Core targets the complete OpenAI Agents API as pinned below ([public API rule](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/AGENTS.md#public-api)). This ledger records how much of each resource Core implements and which contract holds its details, then every known difference from the OpenAI service and every open gap. [API namespaces and credentials](../../docs/api/index.md) says who calls which API; the [Agents API guide](../../docs/api/public-agent-api.md) shows how to use it.

## Pinned baseline

| File | Contents |
| - | - |
| [upstream.json](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/contracts/agents-api/upstream.json) | The pin: [openai-python](https://github.com/openai/openai-python/tree/d7c41efee1b0802b79f3f88a678ef2052b06e9ce/src/openai/resources/beta/agents) 3.13.0 at commit `d7c41ef`, resources under `beta/agents`, Beta header `agents=v1` |
| [upstream-routes.json](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/contracts/agents-api/upstream-routes.json), [upstream-fields.json](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/contracts/agents-api/upstream-fields.json) | The 58 method and path pairs and their official fields: 42 operations under `beta/agents`, 5 Files and 11 Skills operations. `scripts/extract-agents-api-upstream.py` extracts them from the pinned SDK; run it with that SDK installed |
| [openapi.yaml](./openapi.yaml) | Core's public schema, generated by `make openapi` from the route annotations in `services/core/internal/api/` and the wire types in [`v1/`](https://github.com/MiniMax-AI/OpenAgentCore/tree/main/contracts/agents-api/v1) |

Contract tests hold Core to the pin: the router and `openapi.yaml` serve exactly the pinned routes (`services/core/internal/api/routing_test.go`, `v1/upstream_contract_test.go`), every query parameter and field is official, and Core-only fields sit only inside `x_agents_core` on Agents and Sessions. Swagger 2.0 cannot express string-or-array unions, so `openapi.yaml` leaves Session `input` and function-result `output` unconstrained; the pinned types and Core's validation define them. Operations and fields newer than the pin wait for a protocol upgrade.

Evidence for a status comes from the pinned official SDK and raw HTTP against the running service, as [CONTRIBUTING](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/CONTRIBUTING.md#compatibility-evidence) requires.

## Coverage by resource

**Implemented** means every operation serves the pinned shapes; limits that remain are listed under [known gaps](#known-gaps). **Partial** names what is missing.

| Resource | Operations | Status | Contract |
| - | - | - | - |
| Agents | create, retrieve, update, list, delete | Implemented. Every pinned setting is saved; Session admission runs a subset | [Agents](./wire-semantics.md#agents) |
| Sessions | create (JSON or stream), retrieve, update, list, delete | Implemented. Update takes `metadata` only; deletion requires an idle or failed Session | [Sessions](./wire-semantics.md#sessions), [creation streaming](./sessions-events.md#creation-streaming) |
| Session events | create, stream | Partial: messages with text and inline images, cancellation, function results; the stream is live only | [Sessions, events and history](./sessions-events.md), [message content](./message-content.md) |
| Turns | retrieve, list | Implemented; Session Turn routes hold root Turns only | [Turns and Items](./sessions-events.md#turns-and-items) |
| Items | list | Partial: messages, commands, MCP calls, functions, web search, reasoning and Subagent coordination Items; other native variants are not projected | [Turns and Items](./sessions-events.md#turns-and-items) |
| Artifacts | retrieve, list, delete, content | Implemented | [Environment files and Artifacts](./environment-files.md) |
| Subagents | retrieve, list; Items; Turns retrieve and list; Turn Items | Partial: read-only child work; no live child progress or optional native operations | [Subagents](./subagents.md) |
| Environments | retrieve | Implemented | [Environments](./environments.md) |
| Environment files | create, list | Implemented; the list is not recursive | [Environment files and Artifacts](./environment-files.md) |
| Environment Templates | create, retrieve, update, list, delete | Implemented; execution limits are listed under [known gaps](#known-gaps) | [Environment Templates](./environments.md#templates) |
| Vaults | create, retrieve, list, delete | Implemented; no archive operation | [Vaults and Credentials](./vaults.md) |
| Vault Credentials | create, retrieve, update, list, delete | Implemented for `static_bearer` and `mcp_oauth` | [Vaults and Credentials](./vaults.md) |
| Files | create, retrieve, list, delete, content | Implemented for `purpose=user_data`; content download is rejected | [Files and Skills](./source-files.md) |
| Skills and Skill versions | create, retrieve, update, list, delete, content | Implemented | [Files and Skills](./source-files.md) |

Which operation each Harness supports on each placement is in the [Harness capabilities](./harness-capabilities.md). [Core wire behavior](./wire-semantics.md) holds the rules that apply across resources: requests, errors and lists.

Core's own fields sit inside `x_agents_core` ([Core extensions](../../docs/api/public-agent-api.md#core-extensions-x_agents_core)). The Core administration API (`/core/v1`) and the machine API (`/api/v1`) are not part of the Agents API.

## Differences from OpenAI

Each item is Core's deliberate or native behavior where the official service behaves otherwise. The linked rule states the exact behavior.

**Requests and errors** ([Core wire behavior](./wire-semantics.md))

* Core sends no `OpenAI-Organization` or `OpenAI-Project` response headers.
* `HEAD` on the event stream, on content downloads and on the Environment files list returns 405.
* A JSON array body is rejected; the official service reads `[]` as `{}`.
* U+0000 in a stored string returns 400; the official service stores it.
* Not-found messages never name the resource; Core quotes a full metadata key where the official message abbreviates it.
* UUID identifiers also resolve in other spellings, such as uppercase or braces.
* The Files routes keep a local `unsupported_parameter` code for a repeated query key.

**Lists** ([lists](./wire-semantics.md#lists))

* A deleted Agent or Session used as a cursor returns 404; the official service still pages from it.
* A Turn cursor from another Session, a Credential cursor equal to its Vault ID, and a Skills cursor that is not a Skill ID return 404.
* Vault and Credential lists clamp a negative `limit`, as the pinned SDK describes; the official service returns 400.

**Agents and Sessions** ([Agents](./wire-semantics.md#agents), [Sessions](./wire-semantics.md#sessions))

* A repeated Session creation with the same `Idempotency-Key` returns the original Session; the official service creates a new one.
* Omitted programmatic tool calling keeps the harness's native behavior; the official default is on.
* An omitted reasoning effort stays null instead of taking the model's default.
* A Session's `agent.tools` omits `tool_search` declarations.
* Deleting a Session right after an events 202 returns 409, because Core admits the Turn in the same transaction; the official service returned 200.

**Input, events and history** ([Sessions, events and history](./sessions-events.md), [message content](./message-content.md))

* Input to a `none` Session is admitted synchronously; Core does not emulate the official asynchronous admission window.
* A function result that resumes a waiting Turn emits `turn.in_progress`, and cancelling a Turn that waits on a function result emits an interim `agent.session.in_progress`.
* Attaching to the stream mid-Turn sends no catch-up Item snapshots.
* The Items list includes in-progress and incomplete output Items, and keeps a failed function result's submitted `output`.
* Error messages omit the call and executor IDs that official messages include.
* An empty text part beside other text is accepted and stored.
* Empty input returns 400 `invalid_request` with a generic message and a null param; the official response is `invalid_request_error` with param `input`.
* Session usage is available as soon as every root Turn has settled; official reads lag by seconds.

**Files, Skills, Environment files and Artifacts** ([Files and Skills](./source-files.md), [Environment files and Artifacts](./environment-files.md))

* File uploads hold up to 512 MiB; the official limit is 512 MB. The Files list returns up to 10,000 Files by default, and a `purpose` filter other than `user_data` returns an empty page.
* Skill version numbers are never reused, and uploads and deletions of one Skill run one at a time.
* Environment files work on `self_hosted` Environments, which the official service refuses.
* Creating an Environment file over an existing regular file returns the "must not traverse symlinks or overwrite existing files" message. A parent symbolic link that stays inside the workspace is followed, and a parent that escapes the workspace or is a regular file gets a generic 400; the official service rejects symbolic-link parents.
* Artifact IDs are UUIDs.

**Vaults and Credentials** ([Vaults and Credentials](./vaults.md))

* Vault and Credential status is stored privately and defaults to `active`; with no archive operation, lists without a filter include both statuses.
* An unknown or foreign Vault in `vault_ids` returns 404 "Resource not found."; the official message names the ID.
* An explicit `null` for OAuth `access_token`, `refresh` or `token_endpoint_auth` in an update keeps the stored value.
* A static token must be an RFC 6750 `b64token` to run; other stored tokens fail at dispatch.
* Vault metadata has a 64 KiB bound and no pair or length limits; names are 1–256 bytes after trimming.

## Known gaps

**Configuration and tools**

* Explicit reasoning effort or summary, service tiers other than `auto`, enabled `web_search` and enabled programmatic tool calling are saved but rejected at Session admission.
* Harness support for tools, structured output, deferred discovery, subagents and MCP differs by Harness and placement; see the [Harness capabilities](./harness-capabilities.md). MiniMax Code has no public functions, no service-origin MCP and no image input.
* Model-derived reasoning defaults are not resolved.

**Execution and history**

* The stream does not emit reasoning-summary events, Environment `pending` or `ready` events, or every pinned interim tool-output variant.
* Native Item variants beyond those listed under [Turns and Items](./sessions-events.md#turns-and-items) are not projected, and Items cannot be modified.
* A function result that cancellation prevents from being applied never appears as an Item.
* Pinned Codex can lose command output emitted before its stream subscription.
* Claude Code and MiniMax Code report no public usage.
* Core gives no crash-safe or exactly-once guarantee for native side effects; claimed work fails on restart without replay.
* Images must be inline PNG or JPEG data URIs; remote URLs, `file_id` and `detail` are rejected.

**Environments and Templates**

* Runtimes do not enforce `disabled` or `restricted` networks, so Sessions that need them are rejected ([restricted network policy](./environments.md#restricted-network)).
* `packages.system` is rejected; system packages must be preinstalled.

**Files and Environment files**

* Files accept only `purpose=user_data`; other purposes, `expires_after` and the Uploads API are not supported.
* An Environment file write whose outcome is uncertain is never retried or recovered automatically; it blocks further writes and messages to the Session.

**Vaults and Credentials**

* There is no archive lifecycle, storage-key rotation or re-encryption.
* OAuth refresh happens only at dispatch: there is no refresh on a provider 401, no mid-Turn replacement and no withdrawal of a token already sent to a Runtime.
* Input sent to a Session whose selected Credential was deleted is admitted and then fails at dispatch.
* Credential creation takes no `Idempotency-Key`.

**Sessions**

* Session deletion does not purge the stored history physically.
* Stream lifetimes for `self_hosted`, hosted and no-input creation, and the creation-stream retry, are Core's own choices.

### Unverified against the official service

* The order of errors when one request has several faults, and error, default and payload-limit parity in general.
* Whether Subagent child Turns and pending Environment file writes block Session deletion.
* The official order between the pending-input error and an unknown result target.
* Failure reasons for npm, initial-file and Skill installation have no official sample.
* Codex behavior for an empty text part beside text, and for images in failed function results or as remote references; Claude behavior for a whitespace-only or empty text block inside a mixed message.
* Official `HEAD` behavior on the routes where Core returns 405.
* Environment Template hostname forms beyond exact hosts, and `disabled` combined with domains.
* Files purpose filtering and pagination while Files change; official Skill upload limits and error timing.
* Environment file list defaults (limit 20, the workspace root as the default path, no recursion, page-token invalidation), the 50 MiB `file_id` copy limit and the check order on create.
* Artifact capture of hard links, special files and a linked `outputs` directory, republication after changed bytes, and content headers and ranges.
* Vault and Credential error and retry semantics, pagination under concurrent writes, visibility after deletion, exact-URL matching against the official normalization, OAuth refresh timing and errors, and restricted-key scopes.