[sam2tom]

Changes

The public Agents platform documentation lagged behind the current API: Session workspace/artifact endpoints were missing, model overrides were absent from Service/Schedule updates, and Skill bindings were described as following the default at Session creation.

• Document workspace file listing and artifact listing/downloads with pagination, response fields, examples, and limits.
• Correct the required Agent model field, saved Skill version bindings, and Service/Schedule model override behavior.
• Clarify Skills, MCP Connections, and Secrets pagination, lifecycle, metadata updates, built-in MCP selection, and safely encoded examples.
• Synchronize OpenAPI, navigation, and AI-readable documentation.

Validation

• Complete npm run validate passed.
• Final OpenAPI lint, build, and built-public-surface validation passed (2,581 HTML pages).
• Independently reviewed against backend revision 895e535afb; all reported contract discrepancies resolved.
• 31 Python/Bash examples passed syntax checks; no live API writes were executed.
• git diff --check passed.

Documentation-only: no runtime changes or database migrations. Production publication requested by the user; verify changed public pages and OpenAPI after deployment.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-11T12:06:02.007863Z	323feb0	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 323feb03e3

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Keep the built-in ID out of connection resource paths

MCPConnectionIdPath is used by the persisted connection CRUD and enable endpoints (/v1/mcp-connections/{connection_id} and /enable), but builtin:sandbase is only a sentinel accepted in an Agent's mcp_connections array and has no connection resource to read, replace, disable, or enable. Advertising it in this shared path parameter incorrectly tells OpenAPI consumers that those operations accept the built-in ID, leading to 404 requests; document it only on AgentMCPConnectionRef and keep this parameter limited to mcp_ IDs.

Useful? React with 👍 / 👎.