docs(agents): align seven API groups with current contracts

.vitepress/sidebar.ts

@@ -157,6 +157,9 @@ export const apiReferenceSidebar: DefaultTheme.SidebarItem[] = [
       { text: 'Snapshot Stream', link: '/api-reference/sessions/stream-snapshot' },
       { text: 'Upload File', link: '/api-reference/sessions/upload-file' },
       { text: 'List Files', link: '/api-reference/sessions/list-files' },
+      { text: 'List Workspace Files', link: '/api-reference/sessions/list-workspace-files' },
+      { text: 'List Artifacts', link: '/api-reference/sessions/list-artifacts' },
+      { text: 'Download Artifact', link: '/api-reference/sessions/download-artifact' },
       { text: 'Download File', link: '/api-reference/sessions/download-file' },
       { text: 'Delete File', link: '/api-reference/sessions/delete-file' },
     ],

agents/agent-api.md

@@ -52,7 +52,7 @@ The body is strict JSON (up to 1 MiB). Unknown fields return 400.
 | `instructions` | No | Up to 256 KiB |
 | `description` | No | Up to 4096 characters |
 | `runtime_profile` | No | `codex` (default), `claude`, or `mcode` |
-| `skills` | No | `[{"skill_id": "skl_…", "version": null}]`; see [Skills](/agents/mcp-tools#skills) |
+| `skills` | No | Up to 32 references. A new binding with `version: null` pins the current default when saved; existing bindings retain their pinned version. Supply an explicit version to upgrade; see [Skills](/agents/mcp-tools#skills) |
 | `mcp_connections` | No | Up to 32 references; see [MCP connections](/agents/mcp-tools#mcp-connections) |
 | `tools` | No | Up to 64 `function` tools and at most one `web_search` tool |
 | `text` | No | `format.type` `text` or `json_schema` (object schema); `verbosity` `low`, `medium`, or `high` |

agents/api-credentials.md

@@ -23,11 +23,12 @@ Create, rotate, and revoke Secrets with the Secrets API. This guide documents th
 Create a Secret. `Idempotency-Key` is required for every Secret write.
 
 ```bash
-curl -X POST https://api.sandbase.ai/v1/secrets \
-  -H "Authorization: Bearer $SANDBASE_API_KEY" \
-  -H "Idempotency-Key: github-mcp-token" \
-  -H "Content-Type: application/json" \
-  -d '{"name": "GitHub MCP token", "kind": "mcp_bearer", "server_url": "https://mcp.example.com/github", "token": "'"$GITHUB_MCP_TOKEN"'"}'
+python3 -c 'import json, os; print(json.dumps({"name": "GitHub MCP token", "kind": "mcp_bearer", "server_url": "https://mcp.example.com/github", "token": os.environ["GITHUB_MCP_TOKEN"]}))' | \
+  curl -X POST https://api.sandbase.ai/v1/secrets \
+    -H "Authorization: Bearer $SANDBASE_API_KEY" \
+    -H "Idempotency-Key: github-mcp-token" \
+    -H "Content-Type: application/json" \
+    --data-binary @-
 ```
 
 The response is `201 Created` with a `sec_` ID and `status` (`pending` while the token is stored, then `active`). Use the ID as `secret_id` when you [create the MCP connection](/api-reference/mcp-connections/#create-a-connection).

agents/mcp-tools.md

@@ -26,8 +26,8 @@ Most useful Agents combine both: an MCP server fetches data or takes actions, an
 }
 ```
 
-- `"version": null` uses the Skill's `default_version`. A string such as `"2"` pins one version.
-- The version is resolved and frozen when each Session starts. Changing the default later affects new Sessions only.
+- On first attachment, `"version": null` resolves the Skill's current `default_version` when the Agent is saved. A string such as `"2"` selects that version explicitly.
+- The saved Agent pins the version. Changing the Skill default does not upgrade existing Agents or their new Sessions. Update the Agent with an explicit version to upgrade; sending `null` for an existing binding retains its pinned version.
 - Upload a new version with `POST /v1/skills/{skill_id}/versions`, and switch the default with `default=true` or `POST /v1/skills/{skill_id}`.
 - A disabled Skill makes new Sessions of Agents that reference it fail with `400 skill_not_found`.
 
@@ -63,12 +63,27 @@ You can also browse public Skills in the [Skills catalog](/api-reference/skills/
 
 | Field | Meaning |
 |---|---|
-| `connection_id` | `mcp_` connection ID in your organization |
+| `connection_id` | `mcp_` connection ID in your organization, or `builtin:sandbase` for the built-in SandBase server |
 | `server_label` | Starts with a letter; letters, digits, `_`, and `-`; up to 64 characters; unique within the Agent |
-| `allowed_tools` | `null` allows every tool the server offers; `[]` allows none; a list allows only those names |
+| `allowed_tools` | Omitted or `null` allows every tool the server offers; `[]` allows none; a list allows only those names (up to 256 names, each nonblank and at most 128 bytes) |
 | `required` | Whether the Session must load this server |
 
-An Agent can reference up to 32 connections. The connection must be `active` when a Session starts.
+An Agent can reference up to 32 connections. Organization connections must be `active` when a Session starts.
+
+### Built-in SandBase tools
+
+Creating an Agent without `mcp_connections` selects the built-in SandBase server. To explicitly keep it alongside your own server, include this entry in the array:
+
+```json
+{
+  "connection_id": "builtin:sandbase",
+  "server_label": "sandbase_builtin",
+  "allowed_tools": null,
+  "required": true
+}
+```
+
+An explicit array replaces the whole selection; the custom-only example above excludes the built-in server. Send `[]` to disable all MCP tools. Omitting the field on an Agent update preserves the existing selection; `null` returns `400`. The built-in entry does not require creating an MCP connection or Secret. Do not send the retired `use_sandbase_mcp` field.
 
 ::: info Differs from OpenAI
 OpenAI's Agents API declares MCP servers inline as `tools: [{"type": "mcp", ...}]`. SandBase returns `400` for that form: register the server as a connection resource and reference it in `mcp_connections`. The OpenAI SDK has no methods for `/v1/mcp-connections` or `/v1/secrets`, so call them with `client.post(...)` and pass `mcp_connections` through `extra_body` (Python) or the request body (Node.js). See [OpenAI compatibility](/agents/openai-compatibility#mcp-connections-with-the-sdk).

agents/openai-compatibility.md

@@ -232,9 +232,11 @@ SandBase runs every Session in its hosted cloud; there is no environment to choo
 | `sessions.items.list`, `sessions.turns.list / retrieve` | Compatible | Cursor pagination with `limit` 1-100, `after`, `order`. |
 | `client.skills` and `skills.versions` | Compatible, except version delete | `skills.versions.delete` returns `404`. |
 | Error envelope | Compatible | `{"error": {"type", "code", "param", "message"}}`; SDK exceptions expose it as `exc.body`. |
-| Agent versions, restore, archive, catalog, Session rename/archive/reconnect/files | SandBase only | See the [Agents](/api-reference/agents/) and [Sessions](/api-reference/sessions/) API reference. |
+| Agent versions, restore, archive, catalog, Session rename/archive/reconnect/files/workspace-files/artifacts | SandBase only | See the [Agents](/api-reference/agents/) and [Sessions](/api-reference/sessions/) API reference. |
 | Services, Schedules, MCP connections, Secrets | SandBase only | Use HTTP or `client.post` / `client.get`. |
 
+SandBase exposes [artifact listing](/api-reference/sessions/list-artifacts) and [content downloads](/api-reference/sessions/download-artifact) over HTTP. Artifact IDs are opaque and Session-scoped. This does not imply support for every SDK artifact method; a separate artifact metadata endpoint is not exposed.
+
 ### Not supported
 
 These OpenAI SDK calls fail against SandBase. The message is the actual `error.message` returned.
@@ -250,7 +252,7 @@ These OpenAI SDK calls fail against SandBase. The message is the actual `error.m
 | `agents.create(..., tools=[{"type": "mcp", ...}])`; `tool_search`, `programmatic_tool_calling`, and `computer_use` tools | `400 invalid_request`. Only `function` and one `web_search` tool are accepted |
 | `events.create` with a `tool_result` or computer-use approval event | `400 invalid_request`. Sessions that reach `requires_action` are not supported |
 | `events.create` with more than one event | `400`: `exactly one text input or cancel event is supported per request` |
-| `sessions.artifacts`, `sessions.traces`, `sessions.subagents`, `environments.templates` | `404 not_found` (openai-python 3.13.0 has no `traces`) |
+| `sessions.traces`, `sessions.subagents`, `environments.templates` | `404 not_found` (openai-python 3.13.0 has no `traces`) |
 | `beta.agents.vaults` | `404` with a plain-text body (`404 page not found`), not the JSON error envelope |
 | `skills.versions.delete` | `404 not_found` |
 

agents/schedules.md

@@ -74,3 +74,7 @@ Schedules support the same Feishu or Lark notifications as [Services](/api-refer
 - [Schedules API reference](/api-reference/schedules/)
 - [Services](/agents/services)
 - [Sessions](/agents/sessions)
+
+## Change the model for future Runs
+
+Use the [update endpoint](/api-reference/schedules/update) with the latest `row_version` and a `model` string. Omit `model` to keep the current override, or send `""` to return to the pinned Agent model. `null` is rejected. A Run-specific model takes precedence over the saved override; changing the resource does not change an existing Run.

agents/services.md

@@ -73,3 +73,7 @@ A Service can post Run results to a Feishu or Lark bot. Save the webhook with `P
 - [Services API reference](/api-reference/services/)
 - [Schedules](/agents/schedules)
 - [Sessions](/agents/sessions)
+
+## Change the model for future Runs
+
+Use the [update endpoint](/api-reference/services/update) with the latest `row_version` and a `model` string. Omit `model` to keep the current override, or send `""` to return to the pinned Agent model. `null` is rejected. A Run-specific model takes precedence over the saved override; changing the resource does not change an existing Run.

agents/sessions.md

@@ -135,3 +135,15 @@ Treat IDs as opaque strings.
 - [OpenAI compatibility](/agents/openai-compatibility)
 - [Services](/agents/services)
 - [Schedules](/agents/schedules)
+
+## Workspace files and generated artifacts
+
+These three resources serve different purposes:
+
+| Resource | Use it for | Pagination |
+|---|---|---|
+| [Attachments](/api-reference/sessions/list-files) | Files you uploaded and can reference in input with a `file_id` | `limit` / `offset` |
+| [Workspace files](/api-reference/sessions/list-workspace-files) | Current file paths and sizes in a workspace directory | `page` / `next` |
+| [Artifacts](/api-reference/sessions/list-artifacts) | Immutable generated outputs available for download | `after` / `last_id` |
+
+List artifacts to obtain an `art_` ID, then pass that exact ID to [Download Artifact](/api-reference/sessions/download-artifact). A workspace path or attachment `file_id` cannot substitute for it. Workspace listing returns metadata only and is not an arbitrary-path download API. Artifacts can be downloaded as complete files up to 200 MiB; partial `Range` downloads are unsupported.

api-reference/agents/create.md

@@ -22,8 +22,7 @@ apiReference:
         - name: model
           type: string
           required: true
-          description: Model ID from the Models API, up to 200 characters.
-          default: deepseek/deepseek-v4-flash
+          description: Required model ID from the Models API, up to 200 characters. There is no default; omitting model returns 400. The examples use deepseek/deepseek-v4-flash.
         - name: name
           type: string
           required: false
@@ -39,7 +38,7 @@ apiReference:
         - name: skills
           type: array
           required: false
-          description: 'Skill references: {"skill_id": "skl_…", "version": null | "<version>"}. null uses the Skill default version, resolved when a Session starts.'
+          description: 'Skill references: {"skill_id": "skl_…", "version": null | "<version>"}. Up to 32. On a new binding, null pins the current default when the Agent is saved. For an existing binding, null preserves its pinned version; supply an explicit version to upgrade.'
         - name: mcp_connections
           type: array
           required: false

api-reference/agents/replace.md

@@ -48,7 +48,7 @@ apiReference:
         - name: skills
           type: array
           required: false
-          description: 'Skill references: {"skill_id": "skl_…", "version": null | "<version>"}. null uses the Skill default version, resolved when a Session starts.'
+          description: 'Skill references: {"skill_id": "skl_…", "version": null | "<version>"}. Up to 32. On a new binding, null pins the current default when the Agent is saved. For an existing binding, null preserves its pinned version; supply an explicit version to upgrade.'
         - name: mcp_connections
           type: array
           required: false

api-reference/agents/update.md

@@ -44,7 +44,7 @@ apiReference:
         - name: skills
           type: array
           required: false
-          description: 'Skill references: {"skill_id": "skl_…", "version": null | "<version>"}. null uses the Skill default version, resolved when a Session starts.'
+          description: 'Skill references: {"skill_id": "skl_…", "version": null | "<version>"}. Up to 32. On a new binding, null pins the current default when the Agent is saved. For an existing binding, null preserves its pinned version; supply an explicit version to upgrade.'
         - name: mcp_connections
           type: array
           required: false

api-reference/mcp-connections/index.md

@@ -15,7 +15,7 @@ An MCP connection registers a remote MCP server reachable over HTTPS. Agents ref
 | `POST` | `/v1/mcp-connections/{connection_id}/enable` | [Enable a connection](#enable-a-connection) |
 | `DELETE` | `/v1/mcp-connections/{connection_id}` | [Disable a connection](#disable-a-connection) |
 
-Every write requires `Idempotency-Key` (1-128 characters). The connection object has `id`, `name`, `server_url`, `secret_id` (when set), `status` (`active` or `disabled`), `row_version`, `created_at`, and `updated_at`.
+Every write requires `Idempotency-Key` (1-128 bytes, without leading or trailing whitespace). The connection object has `id`, `name`, `server_url`, `secret_id` (when set), `status` (`active` or `disabled`), `row_version`, `created_at`, and `updated_at`.
 
 ## Create a connection
 
@@ -27,8 +27,8 @@ curl -X POST https://api.sandbase.ai/v1/mcp-connections \
   -d '{"name": "GitHub", "server_url": "https://mcp.example.com/github", "secret_id": "sec_9b1d3f5a-7c9e-5b2d-8f4a-6c8e0a2d4f61"}'
 ```
 
-- `name` is required, up to 128 characters.
-- `server_url` must be HTTPS without user info, query, or fragment (up to 2048 characters).
+- `name` is required and nonblank, up to 128 bytes.
+- `server_url` must be HTTPS without user info, query, or fragment (up to 2048 bytes).
 - `secret_id` is optional. Omit it for an anonymous server. When set, the Secret must be `active` and its `server_url` must equal this `server_url` exactly, otherwise the request fails (409 for an inactive Secret, 400 for a URL mismatch).
 
 Returns `201 Created`.
@@ -40,7 +40,7 @@ curl "https://api.sandbase.ai/v1/mcp-connections?limit=20&offset=0" \
   -H "Authorization: Bearer $SANDBASE_API_KEY"
 ```
 
-Offset pagination with `data`, `total`, `limit`, and `offset`.
+Offset pagination with `data`, `total`, `limit`, and `offset`. `limit` defaults to 20 and is capped at 200; missing, invalid, or nonpositive values use 20. `offset` defaults to 0; invalid or nonpositive values use 0. Advance by the returned `limit` until `offset + data.length >= total`. Disabled resources remain visible in the list.
 
 ## Get a connection
 
@@ -59,7 +59,7 @@ curl -X PUT https://api.sandbase.ai/v1/mcp-connections/mcp_1f3d5b7a-9c2e-5f4a-8b
   -d '{"name": "GitHub", "server_url": "https://mcp.example.com/github", "row_version": 1}'
 ```
 
-`PUT` replaces `name`, `server_url`, and `secret_id` together; omitting `secret_id` makes the connection anonymous. `row_version` must match the current value. A disabled connection stays disabled after replacement until you enable it.
+`PUT` replaces `name`, `server_url`, and `secret_id` together; omitting `secret_id` makes the connection anonymous. `row_version` is required and must match the current value returned by Get Connection. Returns `200 OK` with the updated connection. A disabled connection stays disabled after replacement until you enable it.
 
 ## Enable a connection
 
@@ -71,7 +71,7 @@ curl -X POST https://api.sandbase.ai/v1/mcp-connections/mcp_1f3d5b7a-9c2e-5f4a-8
   -d '{"row_version": 3}'
 ```
 
-Enabling keeps the same connection ID. It does not restore a revoked Secret; replace the connection with a new active Secret first.
+`row_version` is required and must be a positive integer matching the current resource. Returns `200 OK` with the connection. Enabling keeps the same connection ID. It does not restore a revoked Secret; replace the connection with a new active Secret first.
 
 ## Disable a connection
 
@@ -86,3 +86,9 @@ Returns `204 No Content` and sets `status` to `disabled`. New Sessions cannot us
 ## Changes and running Sessions
 
 Sessions freeze connection settings when they start. After you replace a connection or rotate its Secret, new Sessions use the new configuration and existing Sessions keep their snapshot. Disabling the connection or revoking its Secret blocks both new Sessions and further input to existing ones.
+
+## Errors and retries
+
+Errors use the [Agents error envelope](/api-reference/errors#agents-platform-errors). Invalid fields or a missing write idempotency key return `400 invalid_request`; an unknown or inaccessible resource returns `404 not_found`. Stale `row_version`, an incompatible lifecycle state, or reusing a create/update key with different input returns `409 conflict`. Read the resource again before issuing a new update, and use a new key for each new write operation.
+
+`created_at` and `updated_at` are RFC 3339 timestamp strings.

api-reference/schedules/create.md

@@ -42,7 +42,7 @@ apiReference:
         - name: model
           type: string
           required: false
-          description: Default model override.
+          description: Model override for Runs, up to 200 characters. Omit or send an empty string to use the pinned Agent model. Each Run freezes its selected model.
         - name: schedule
           type: object
           required: true