# Clyck API - **OpenAPI Version:** `3.2.0` - **API Version:** `2026-10-19` ### Introduction #### Build your product on managed agents Clyck runs agents for your application over HTTP. Configure an agent with your model, instructions and tools, start a session, and send it a task. Clyck manages the model and tool loop, conversation history and recovery. Your application receives results through a live event stream, signed webhooks or API reads. Your application stays in charge of the product: it decides when an agent works, which tools it can use and how its results reach your users. Clyck runs the model calls, tool calls, sandboxes and recovery. #### When to use Clyck - **Agents inside your product:** one session per customer, ticket, document or task, driven from your backend. - **Long-running and background work:** submit a task, let your user close the tab, and get a signed webhook when it finishes. - **Any model, your keys:** choose from the providers and models in `GET /models`, including Anthropic, OpenAI and Google. Select a model per agent version or per session. - **Your own tools:** connect MCP servers and HTTP endpoints, and grant each agent exactly the tools it needs. - **Built-in capabilities:** web search, browser automation, a managed sandbox for files and commands, and published file outputs. - **Live product experiences:** stream text, thinking and tool activity to your UI, and steer or follow up while the agent works. #### What Clyck runs, what your application owns | Area | Clyck runs | Your application owns | | ------------------------ | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | | Agent execution | Model calls, tool calls, retries, context summarization and recovery. | Instructions, model choice, when to submit work and what to do with results. | | Conversations | Durable sessions, history, live state streaming and webhooks. | Your product experience and your own records. | | Tools and sandboxes | Calls to your MCP and HTTP tools, sandbox lifecycle, web search and browser. | Your tool endpoints, which tools each agent may use, and sandbox choice. | | Identity and credentials | Tenant isolation, tool grant enforcement and encrypted credential storage. | End-user authentication and authorization, and your provider accounts. | | Outcomes | Recorded results for every submission and tool call. | Budgets, approvals and business-level checks on what the agent did. | #### Core concepts | Concept | What it is | | -------------- | ------------------------------------------------------------------------------------------------------------------------------- | | **Agent** | A named configuration: model, instructions, tool grants and optional sandbox. Every change creates a new immutable version. | | **Session** | One durable conversation started from an agent version. Reuse it for follow-up tasks with its recorded history. | | **Submission** | Input you send to a session, with a status that ends `done`, `cancelled` or `failed`. A `done` input names its answer. | | **Entry** | A committed message in the session's history, such as your input, the agent's answer or a tool result. | | **Credential** | A stored API key for your model, sandbox, web search or browser provider. | | **Connection** | Your MCP server or HTTP endpoint, with its authentication. Agents use its tools through explicit grants. | | **Skill** | A tenant-owned collection of instructions and supporting files, attached by immutable version. Reading skills needs no sandbox. | | **Artifact** | A file the agent published from its sandbox, downloadable through `/files`. | ### Quick start Send a message to an agent and read its answer with a handful of API calls. You need a platform API key, which you create in the [dashboard](/dashboard), and an API key from a model provider. The API base URL is `https://api.useclyck.com/v1`. ```sh export CLYCK_API_URL="https://api.useclyck.com/v1" export CLYCK_API_KEY="your-platform-api-key" ``` **1. Store your model API key.** Save the returned `id` as the credential ID. ```sh curl "$CLYCK_API_URL/credentials" -H "Authorization: Bearer $CLYCK_API_KEY" -H "Content-Type: application/json" \ -d '{"name": "Anthropic", "category": "model", "provider": "anthropic", "api_key": "your-anthropic-api-key"}' ``` **2. Choose a model.** `GET /models` lists the catalog of providers and model IDs; choose a model from your credential's provider. ```sh curl "$CLYCK_API_URL/models" -H "Authorization: Bearer $CLYCK_API_KEY" ``` **3. Create an agent.** Save `latest_version.id` from the response. ```sh curl "$CLYCK_API_URL/agents" -H "Authorization: Bearer $CLYCK_API_KEY" -H "Content-Type: application/json" -d '{ "name": "Assistant", "config": { "model": {"provider": "anthropic", "id": "claude-sonnet-5-5", "credential_id": ""}, "instructions": "Answer clearly and concisely.", "tools": [{"type": "platform", "name": "web_search"}] } }' ``` **4. Start a session.** Save the returned `id` as the session ID. ```sh curl "$CLYCK_API_URL/sessions" -H "Authorization: Bearer $CLYCK_API_KEY" -H "Content-Type: application/json" \ -d '{"agent_version_id": ""}' ``` **5. Submit input.** The `202` response is the saved submission. A `request_id` makes retries of this request safe. ```sh curl "$CLYCK_API_URL/sessions//submissions" -H "Authorization: Bearer $CLYCK_API_KEY" \ -H "Content-Type: application/json" -d '{"content": "What is new in TypeScript this year?", "request_id": "req-1"}' ``` **6. Read the outcome and the answer.** Read the submission until its `status` is `done`, `cancelled` or `failed`, then fetch the answer entry it names. ```sh curl "$CLYCK_API_URL/sessions//submissions/" -H "Authorization: Bearer $CLYCK_API_KEY" curl "$CLYCK_API_URL/sessions//entries?min_entry_id=&max_entry_id=" \ -H "Authorization: Bearer $CLYCK_API_KEY" ``` Your output looks similar to this: ```json {"id": 1, "conversation_id": 1, "request_id": "req-1", "type": "input", "status": "done", "entry": 2, "answer": 5} {"data": [{"id": 5, "conversation_id": 1, "kind": "message", "model": [{"role": "assistant", "content": [{"type": "text", "text": "Here are this year's TypeScript highlights..."}], "stop_reason": "stop"}]}], "next_cursor": null} ``` What happened: 1. Clyck saved your input and placed it in the session's conversation. 2. The model wrote a `codemode` program that called `web_search`, and Clyck ran it and recorded each tool call. 3. The model answered, and Clyck committed the answer as an entry and marked the submission `done`. 4. The session kept its history, so the next submission continues the same conversation. The [runnable Python example](/reference/examples/saas.py) performs these steps with only the standard library: ```sh export MODEL_PROVIDER="anthropic" export MODEL_ID="claude-sonnet-5-5" export MODEL_API_KEY="your-model-api-key" python3 saas.py "Say hello in one sentence." python3 saas.py --session "A follow-up question" ``` Keep platform and provider API keys on your backend. From here, add your own tools, stream progress to your UI and register a webhook, as described in the guides below. ### Operate Clyck from your coding agent Connect an MCP-compatible coding agent to your Clyck MCP server URL to configure Clyck, start sessions, send input and read results. MCP uses an independent endpoint from the HTTP API's `/v1` base path. Local development exposes MCP at `http://localhost:8082/mcp` and the API at `http://localhost:8080/v1`. **Authentication.** Choose either OAuth or a platform API key: - **OAuth:** add the MCP URL to your client, then sign in with your Clyck account through WorkOS and approve access. Clients discover WorkOS through the MCP endpoint's OAuth protected-resource metadata and authentication challenge. Access tokens must be issued for this MCP endpoint and include its required scopes; the client handles obtaining and refreshing tokens. An MCP access token cannot be used directly with the HTTP API; API authorization requires a token issued for that API's resource audience. - **Platform API key:** configure a client that supports custom HTTP headers to send `Authorization: Bearer ` on every request. The key has the same full-tenant access as it does through the HTTP API and stops authenticating new requests when revoked. Both methods act within the authenticated Clyck tenant, and each operation is authorized by Clyck's API. Configure model, sandbox and connection credentials through the Clyck dashboard or HTTP API before using MCP, then reference their stored IDs in tool arguments. MCP tools never accept authentication secrets or return stored secrets. Platform API key management is available through the dashboard and HTTP API. **Tools.** The MCP server exposes the following operations. Names use snake_case; inputs follow the corresponding HTTP operation, with path parameters, query parameters and JSON body properties supplied as tool arguments. | Area | Tools | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Models | `list_models` | | BYO credentials | `list_credentials`, `delete_credential` | | Connections | `list_connections`, `get_connection`, `delete_connection` | | Agents and versions | `list_agents`, `get_agent`, `create_agent`, `list_agent_versions`, `create_agent_version` | | Sessions | `list_sessions`, `get_session`, `get_state`, `list_submissions`, `get_submission`, `list_entries`, `create_session`, `submit_input`, `cancel_submission`, `cancel_session`, `standby_session`, `delete_session` | Tools return the corresponding API JSON result as structured content and as JSON text. Successful operations whose HTTP response has no content return an empty object. API failures are tool errors containing the API's error code and message as JSON text. MCP request bodies are limited to 20 MiB; each operation's own limits also apply. Required inputs, pagination, dependency checks, immutable versions, cancellation and deletion have the behavior documented for the corresponding HTTP operations below. **First session.** Set up a model credential in the dashboard or HTTP API, and a sandbox credential if bringing your own sandbox. Use `list_models` and `list_credentials` to choose a model and find the stored credential IDs. Call `create_agent` with the model, instructions and desired tool grants, then pass its `latest_version.id` to `create_session`. OAuth MCP clients do not need a platform API key to use the MCP server. **Read results.** `submit_input` returns the saved submission immediately. Use its ID with `get_submission` to check for `done`, `cancelled` or `failed`. For a completed input, pass its `answer` entry ID as both `min_entry_id` and `max_entry_id` to `list_entries` to read the answer. `get_state` returns a single current snapshot; `list_entries` returns paginated committed history, including history removed from the current snapshot by summarization. MCP reads do not wait for a submission to finish or open a live event stream. **Revise and clean up.** Editing an agent means calling `create_agent_version` with a replacement configuration. Existing sessions keep their resolved configuration. Manage connection authentication through the dashboard or HTTP API; changing a connection's URL or type requires a new connection. `cancel_submission` withdraws queued input; `cancel_session` cancels active work and queued input while keeping the session available for new input. `standby_session` immediately releases an idle session's runtime resources while retaining the conversation and sandbox files, freeing its active-session slot. New input or context wakes it automatically. Active work must finish or be cancelled before entering standby. `delete_session` stops work, releases owned resources and deletes the session. Archive or delete dependent sessions before deleting credentials or connections. There is no agent-deletion tool. ### Build your integration Your backend maps product records and authenticated users to Clyck sessions. Clyck manages execution, tool grants, encrypted credentials and durable history; your application controls end-user access, budgets, approvals and how results reach your users. Store the session ID with your ticket, document or task, and check user access before forwarding messages or returning session data. #### Connect your own API as tools Agents call your systems through connections. Create a connection for an MCP server (Streamable HTTP) or an HTTP endpoint, then grant tools from it in the agent's `tools`. Connections are reached over public HTTPS. - **MCP:** `POST /connections` with `{type: "mcp", url, credentials}`, then grant `{type: "mcp", connection_id, tools: ["tool_name", ...]}` using the exact names your server advertises. - **HTTP:** `POST /connections` with `{type: "http", url, credentials}`, then grant `{type: "http", connection_id, name, description, parameters}`, where `parameters` is the JSON Schema for the arguments. Each call is a JSON `POST` of the arguments to the connection URL with a 120-second timeout. Give each HTTP tool its own connection URL when your endpoint routes by path. - **Results:** respond with `2xx` and a JSON body (or `204`) for every result the model should read, including business outcomes such as "customer not found". Other statuses fail the call, and the model sees only the status code, so put details the model needs in `2xx` results. - **Per-user access:** to scope tools to one end user or task, create a connection whose credentials are a short-lived token for that user, and start the session with `overrides.tools` listing the complete grants for the session, including the grant for that connection. Rotate credentials in place with `PATCH /connections/{connection_id}` as part of your application's token renewal flow. To build a support assistant, create a connection to your ticket lookup endpoint. Have your endpoint authorize access using the token, then return the ticket and account details as JSON: ```json { "name": "Ticket lookup for this customer", "type": "http", "url": "https://your-app.example.com/agent-tools/read-ticket", "credentials": {"api_key": ""} } ``` Send that body to `POST /connections`, save its `id`, then start a ticket session with `POST /sessions`: ```json { "agent_version_id": "", "overrides": { "tools": [{ "type": "http", "connection_id": "", "name": "read_ticket", "description": "Read an authorized support ticket and its account details.", "parameters": { "type": "object", "required": ["ticket_id"], "properties": {"ticket_id": {"type": "string"}}, "additionalProperties": false } }] } } ``` Submit "Read ticket #42 and suggest the next step" to this session. Clyck sends the tool arguments to your endpoint with `Authorization: Bearer `. The agent uses the result to answer, and your backend can inspect the arguments and response in the session's tool-call history. Each session keeps its resolved grants; include every tool it should use in `overrides.tools`. #### Stream progress to your UI Open `GET /sessions/{session_id}/events` from your backend and relay it to your UI. Each connection starts with a `snapshot` of the complete live state, followed by events for text and thinking deltas, tool activity, usage and submission outcomes. To render a session: 1. Replace your state with each `snapshot`. 2. Apply `message.started`, `message.delta` and `message.replaced` to the in-progress assistant message, and replace it with the committed message on `message.completed`. 3. Show tool activity from `tool.started`, `tool.updated` and `tool.completed`. Nested calls carry `parent_call_id`. 4. Use `submission.updated` to know when input is answered. Whenever a `snapshot` arrives after the first, read the submissions you are tracking, since a snapshot replaces events it supersedes. Streams close when the session enters standby. Opening a stream in standby returns a snapshot and then closes without waking the session. Submit new work, then open or reconnect the stream for its current snapshot. Work continues when a stream disconnects; read `GET entries` and tracked submissions for anything committed meanwhile. #### Get notified when work finishes Register a webhook for `submission.updated` and `artifact.created` to receive background results. Each notification names the session and submission or file; read that resource for its current state. See Webhooks for signing and delivery behavior. #### Bring your own skills Upload a directory containing `SKILL.md` and supporting files through `POST /skills`. Send individual files as multipart `files[]` parts with relative filenames, or send a ZIP as `application/zip`. The root `SKILL.md` uses YAML front matter with a `name` and `description`. A single enclosing directory is accepted and removed from stored relative paths. Keep the same skill name when uploading a new complete version through `POST /skills/{skill_id}/versions`. Each version contains at most 1,000 regular files and 30,000,000 bytes of uncompressed file contents. ZIP uploads contain at most 2,000 entries including directory entries. An upload request is at most 64,000,000 bytes including encoding and multipart overhead. Descriptions cannot contain NUL, must be non-blank and at most 1,024 Unicode characters; XML-like text is allowed. Oversized uploads return `413 skill_too_large`, and invalid bundles return `400 invalid_skill`. A version becomes available only after validation succeeds and all file contents have been stored successfully. There is currently no aggregate skill-storage limit. Skills do not consume the uploaded-file storage allowance. Attach skills in an agent configuration or session overrides: ```json {"skills": [{"skill_id": "10000000-0000-4000-8000-000000000002", "version": "3"}]} ``` The version is required and accepts a positive integer string or `latest`. Creating an agent version resolves `latest` immediately; that agent version and its sessions retain the concrete version. A session's skill override resolves `latest` when the session is created. Omission inherits attachments, a supplied list replaces them, and `[]` clears them. Getters return concrete versions. Publishing another skill version never changes existing attachments. Skill contents remain available after standby and recovery. Attached skills automatically make `read_skill` available inside `codemode`, without a tool grant or sandbox. The model receives each skill's name, validated description, ID and pinned version in its catalog. It reads full instructions and supporting files only when needed: ```javascript text(await tools.read_skill({skill_id: "10000000-0000-4000-8000-000000000002"})); text(await tools.read_skill({skill_id: "10000000-0000-4000-8000-000000000002", path: "references/escalation.md"})); ``` `read_skill` accepts `skill_id`, optional `path` (default `SKILL.md`), optional byte `offset` (default `0`) and optional byte `limit` (default `65536`, between `1` and `262144`). The result identifies `skill_id`, concrete `version`, `path`, `mime_type`, `size` (total file bytes), `offset`, `encoding`, `content`, `next_offset` and `truncated`. `next_offset` is the next byte position to read, or `null` at the end; `truncated` reports whether more bytes remain after this result. Follow `next_offset` to continue a large file. The selected bytes use `utf8` encoding when they are valid UTF-8 and otherwise use `base64`, including a slice that splits a UTF-8 character. Reading `SKILL.md` also returns the version's file manifest. The reader selects only exact uploaded paths from versions attached to this session. It cannot browse other skills, choose another version, access another tenant's files, or interpret paths as URLs, globs, shell expressions or host filesystem locations. Missing and inaccessible skills return the same not-found error. Attachment grants no tools or credentials and never executes uploaded scripts. Skills are not automatically mounted or copied into a sandbox. Relative paths contain at most 4,096 characters, cannot contain empty, `.` or `..` segments, backslashes or NULs, and cannot be absolute. Duplicate paths, symlinks, hard links and special files are rejected. Customer filenames never address the harness host's filesystem. `GET /skills/{skill_id}/versions/{version}` returns metadata and base64 file contents as JSON, or a downloadable ZIP when `Accept: application/zip` is supplied. Both forms identify the concrete version returned. #### Give the agent a sandbox Add `sandbox` to the agent configuration and grant its tools, for example `{type: "sandbox", tools: ["read", "write", "edit", "bash"]}`, to give the agent a filesystem and shell. Clyck creates the sandbox when a tool first needs it and binds it to the session, so every sandbox tool call works in the same environment. Sandboxes Clyck creates are deleted when their session is archived or deleted; an existing sandbox you attach with `sandbox_id` stays yours. | Start with | Configuration | Capabilities | | ----------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | | A Clyck-managed sandbox | `{provider: "clyck-managed"}` | `read`, `write`, `edit`, `bash`, uploaded input files and published output files. | | Your Blaxel workspace | `{provider: "blaxel", credential_id}` | `read`, `write`, `edit` and `bash`; attach an existing sandbox with `sandbox_id`. | | Your Daytona account | `{provider: "daytona", credential_id, snapshot}` | Commands, file operations and `computer_use_*` desktop tools; use `sandbox_id` in place of `snapshot` to attach an existing sandbox. | For Daytona, choose a snapshot available to your credential's account in the selected `target` region, which defaults to `us`. Computer use requires the snapshot or attached sandbox to include Daytona's required desktop software; Clyck starts those desktop services automatically. An attached sandbox must be accessible with the selected credential and running before tools can execute. Start or resume it in Daytona first: Clyck waits for startup already in progress, but does not start stopped sandboxes or resume paused or archived ones. For file workflows, choose the Clyck-managed sandbox. Upload input files with `POST /files` and reference them in a submission; the agent works on copies in its sandbox. When the agent produces a deliverable, it calls `publish_file` to save an immutable copy that you download with `GET /files/{file_id}`. Sandbox files are the agent's working state; published files are your durable output. For example, turn the quickstart agent into a CSV analyst by starting a session with these overrides: ```json { "agent_version_id": "", "overrides": { "instructions": "Analyze the supplied CSV, write a Markdown report, and publish the finished report with publish_file.", "sandbox": {"provider": "clyck-managed"}, "tools": [ {"type": "sandbox", "tools": ["read", "write", "edit", "bash"]}, {"type": "platform", "name": "publish_file"} ] } } ``` Send this body to `POST /sessions` and save the returned session ID. Upload your CSV as raw bytes and save the returned file `id`: ```sh curl "$CLYCK_API_URL/files" -H "Authorization: Bearer $CLYCK_API_KEY" \ -H "X-Filename: sales.csv" -H "Content-Type: text/csv" --data-binary @sales.csv ``` Submit the file and task to the analyst session with `POST /sessions/{session_id}/submissions`: ```json { "content": [ {"type": "file", "file_id": ""}, {"type": "text", "text": "Summarize monthly sales and publish a Markdown report."} ], "request_id": "sales-report-1" } ``` Follow the submission's outcome as in the quickstart. Use `GET /sessions/{session_id}/artifacts` to find published files and `GET /files/{file_id}` to download a report. For background completion, register a webhook before submitting the task. See Files for input sizes, working copies and artifact retention. #### Durable execution - **Accepted input is saved.** A `202` from `POST submissions` means the input is stored. Retrying with the same `request_id` returns the original submission. - **Sessions resume on their own.** History and accepted input persist across restarts and deploys, and active work continues automatically. Check a submission's status before submitting replacement work. - **Outcomes are explicit.** A submission's `status` is the source of truth for whether input was answered: `done`, `cancelled` or `failed` with a `reason`. Stream events report progress along the way. - **Every tool call is recorded.** `GET tool-calls` keeps arguments, results and outcomes for `codemode` and every tool it calls. During recovery, Clyck repeats only operations that are safe to repeat. A call interrupted after it started is recorded with `outcome` `unknown`, so your application can confirm the effect with the system that owns it before trying again. ### API conventions - **Authentication:** send `Authorization: Bearer `. Every resource belongs to the key's tenant; a resource of another tenant returns `404`. - **Account setup:** verify a card in the [dashboard](/dashboard) before creating or changing resources. Unverified writes return `402 card_verification_required`; reads and deletion remain available. Verification does not charge the account or start a paid subscription. Clyck may waive it for existing accounts. - **Errors:** errors return `{error: {code, message}}`. Branch on `code`; `message` is a human-readable explanation. Retry `503` errors after a short wait; the `message` names the unavailable dependency. - **Asynchronous work:** a `2xx` response means the request was accepted. The submission or tool-call record reports the outcome of the work. - **Pagination:** lists return `data` and `next_cursor`. Follow `next_cursor` until it is `null`, keeping the same filters, bounds and order; a page can be shorter than `limit`. Resource lists are newest first; submissions and tool calls default to ascending ID order, entries to descending ID order. A malformed cursor, or one reused with a different order, returns `400 invalid_request`. Lists reflect writes as they happen. Identifiers and cursors are opaque. - **Request bodies:** JSON endpoints accept `application/json` (case-insensitive, with optional parameters); other media types return `415 unsupported_media_type`. Request bodies are up to 16 MiB. String limits count Unicode code points; JSON strings and property names must be well-formed Unicode without `U+0000`, otherwise the request returns `400 invalid_request`. File uploads accept arbitrary bytes. - **Naming:** fields use `snake_case`; enum values and your own JSON keep their documented spelling. ### Guides #### Managed service limits Managed service allowances and session concurrency are shared across the current tenant's agents and sessions. Free includes 2 concurrent resident sessions and 100 MB of file storage. Its monthly allowances are 3,600 managed sandbox seconds, 3,600 managed browser seconds and 100 managed searches. Pro includes 50 concurrent resident sessions and 10 GB of file storage, with monthly allowances of 360,000 managed sandbox seconds, 360,000 managed browser seconds and 5,000 managed searches. Free monthly allowances follow the UTC calendar month. Paid Pro allowances follow the subscription's paid billing period, starting when the subscription begins and renewing on its monthly anniversary. File storage is current capacity, using decimal units (1 MB = 1,000,000 bytes; 1 GB = 1,000,000,000 bytes), and does not reset monthly. Enterprise allowances and customer-specific overrides are configured by Clyck. View current usage and effective limits in the [dashboard](/dashboard/usage). Sandbox time is an estimate: it begins when the managed sandbox is first accessed during an awake period, including input file preparation, and continues through the idle window until the session enters standby. Browser time runs while a managed browser is allocated, through release, expiry or session standby. Each new managed browser counts at least 60 seconds. Reconnecting to the same browser does not add another minimum. If browser creation has an unknown outcome and its resource cannot be released, usage may conservatively include its full configured timeout to account for the browser that may still be running. Standby time is excluded. Concurrent intervals add together. Customer-provided sandbox, browser and search credentials are excluded from managed service usage. Managed searches count when dispatched, including failed attempts. File storage includes uploaded files and published outputs, including reserved pending publications. Deleting a stored file frees storage capacity. Model-provider token usage is reported separately in session state and history. Concurrent sessions include active and idle sessions with a live runtime owner. Standby sessions do not count. Activating another session at the concurrency limit fails with `429 concurrency_limit_exceeded`. Exhausted managed allowances reject resource access with `409 usage_limit_exceeded`. Running sandbox and browser usage is checked approximately every five seconds; a session whose managed runtime allowance is exhausted has its current work stopped and enters standby. State and history remain available. Timed limits may overrun by the checking interval plus cleanup time, multiplied by concurrent resources. Managed runtime and search allowances reset monthly; there are no automatic overage charges. Stopped work is reported through the normal submission cancellation outcome; the dashboard identifies the exhausted allowance. A later input can continue the same session, but exhausted managed tools remain unavailable until the allowance resets or Clyck changes the account's limits. #### How agents use tools: code mode Agents compose tools through short JavaScript programs. The model calls `codemode` and uses the tools you granted as `await tools.(args)`. A program can chain calls, loop over results and select what to return to the model, keeping its context focused. Each tool call is recorded individually for your UI and tool-call history. Inside `codemode`, platform tools keep their names (`web_search`, `browser_client`, `publish_file`), HTTP tools use their grant `name`, sandbox tools are named `sandbox_`, and MCP tools are named `mcp__` with a suffix that is stable for the connection and tool. `ALL_TOOLS` and `searchTools` list the callable names. Programs resume from recorded tool results after interruptions. Each program runs for up to 120 seconds, including its tool calls; a first line of `// @options: {"timeout_ms": 30000}` sets a shorter deadline. For longer work, such as a large build or test suite, the agent starts it in the background in the sandbox and checks its output in later programs. #### Browser automation Grant `{type: "platform", name: "browser"}` to give the agent a remote browser driven through a Playwright-style API. Clyck supplies the browser, or an optional `credential_id` selects your own Browserbase credential. Inside `codemode`, `browser_client` returns the client source and its API documentation. Each `codemode` program starts a fresh JavaScript environment, so bootstrap the client in each program: ```javascript const {browser, helper} = eval((await tools.browser_client()).source); const page = await browser.contexts()[0].newPage(); await page.goto("https://example.com"); text(await page.title()); image(await page.screenshot()); store("examplePage", helper.savePage(page)); ``` In a later program, bootstrap again and pick up the same page: ```javascript const {helper} = eval((await tools.browser_client()).source); const page = await helper.getPage(load("examplePage")); text(await page.title()); ``` **Keeping state between programs.** `store` and `load` keep JSON values after a successful program: up to 262144 characters of serialized JSON per value and 1048576 characters in total. Create client and locator objects in each program, since stored JSON keeps data rather than methods. `helper.savePage(page)` synchronously returns a page reference; store it unchanged and pass it to `helper.getPage(reference)`, which asynchronously reattaches the same live page while its page and browser are open. It fails for a closed page, an expired browser, or a reference from another session or browser. **Browser lifecycle.** The session keeps its browser across submissions and reconnections for up to one hour. Session archival, deletion and `helper.reset()` release it. Standby releases a Clyck-provided browser (a browser grant without `credential_id`), losing its pages, cookies and page references; the next browser use creates a fresh browser. A browser using your `credential_id` is disconnected during standby but remains bound, retaining its provider state while available. Its provider lifetime continues during standby; waking the session reconnects to it if it is still available. `browser.contexts()`, `context.pages()` and `page.url()` synchronously return the most recently observed state, and each awaited browser command updates it; await `helper.refresh()` to pick up changes made outside this client. Await `helper.reset()` to release the browser and invalidate this client and its references, then bootstrap again for a new browser. When the bound browser is unreachable (its creation was interrupted or reconnection failed), `browser_client` still returns the client with `snapshot.status.state` `unavailable` and a stable `code` and safe `message`, so `helper.reset()` is always available; a connected browser has `state` `ready`. A refresh retries the connection to an existing browser. Bootstrap again to replace an expired browser; interrupted creation requires a reset. Old browser and page references never target a replacement browser. When the provider rejects browser creation, for example because of an invalid credential, `browser_client` fails without binding a browser and can be called again once the cause is fixed. Missing credentials, invalid configuration or cancelled work also stop client initialization. **Timing.** `Date.now()` inside `codemode` advances as tool results arrive, so wait with browser methods such as `waitForURL` or `waitForLoadState` rather than a loop. Playwright operations that accept a `timeout` default to 30000 ms and accept 0 to 120000 ms; 0 disables the operation timeout within the program's own deadline of at most 120 seconds. Commands can run concurrently, including `Promise.all` with `waitForURL` and a click that navigates. **API.** The client provides exactly the methods below. Locator and frame builders are synchronous and chainable; browser operations, locator actions and reads, and `locator.all()` are asynchronous unless listed as synchronous above. | Object | Methods | | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Browser | `contexts()` | | Context | `pages()`, `newPage()` | | Page | `close()`, `goto(url, options?)`, `goBack(options?)`, `goForward(options?)`, `reload(options?)`, `url()`, `title()`, `screenshot(options?)`, `setViewportSize(size)`, `waitForURL(urlOrRegExp, options?)`, `waitForLoadState(state?, options?)`, `evaluate(functionOrExpression, argument?)` | | Page, Locator and FrameLocator builders | `getByRole(role, options?)`, `getByText(textOrRegExp, options?)`, `getByLabel(textOrRegExp, options?)`, `getByPlaceholder(textOrRegExp, options?)`, `getByTestId(testIdOrRegExp)`, `locator(selector, options?)`, `frameLocator(selector)` | | Locator composition | `filter(options)`, `first()`, `last()`, `nth(index)`, `and(locator)`, `or(locator)`, `all()` | | Locator actions | `click(options?)`, `dblclick(options?)`, `fill(value, options?)`, `press(key, options?)`, `check(options?)`, `uncheck(options?)`, `selectOption(values, options?)`, `pressSequentially(text, options?)`, `setChecked(checked, options?)` | | Locator reads and waits | `innerText(options?)`, `textContent(options?)`, `allTextContents()`, `getAttribute(name, options?)`, `count()`, `isVisible(options?)`, `isEnabled(options?)`, `ariaSnapshot(options?)`, `waitFor(options?)`, `evaluate(functionOrExpression, argument?, options?)`, `evaluateAll(functionOrExpression, argument?)` | | `page.mouse` | `click(x, y, options?)`, `move(x, y, options?)`, `wheel(deltaX, deltaY)`, `dblclick(x, y, options?)`, `down(options?)`, `up(options?)` | | `page.keyboard` | `press(key, options?)`, `insertText(text)` | Methods follow Playwright argument conventions and work with the browser's existing contexts. Frame locators can be nested. `RegExp` arguments keep their patterns and flags for text and role filters and `waitForURL`. Pass locator objects from the same page, rather than selector strings, to `filter`'s `has`/`hasNot`, `and`/`or`, `locator()` and screenshot `mask` options. Navigation methods return a plain summary `{url, status, statusText, ok, headers}` or `null`. `screenshot()` returns an image block, PNG by default or JPEG on request; show it with `image(await page.screenshot())`. Screenshots take inline `style` strings, which run in the remote browser, rather than `path` or `stylePath`. Evaluation runs JavaScript in the page and can read or change page state; pass values in as an explicit argument, since evaluated functions run in the page rather than the program. Evaluation arguments and results support JSON, `undefined`, `NaN`, `Infinity`, `-Infinity` and `-0`; cycles, `BigInt`, `Date` objects and JavaScript handles are rejected. `evaluate` and `evaluateAll` are the methods that take functions. Browser actions act on real websites. An action interrupted mid-flight may already have taken effect, so inspect the page before repeating it. Browser credentials and provider endpoints stay inside Clyck and are never returned to `codemode`. ## Contents **Operations** - [GET /api-keys](#scalar-operation-get-api-keys) - [POST /api-keys](#scalar-operation-post-api-keys) - [DELETE /api-keys/{key_id}](#scalar-operation-delete-api-keyskey-id) - [GET /models](#scalar-operation-get-models) - [GET /credentials](#scalar-operation-get-credentials) - [POST /credentials](#scalar-operation-post-credentials) - [PATCH /credentials/{credential_id}](#scalar-operation-patch-credentialscredential-id) - [GET /credentials/{credential_id}](#scalar-operation-get-credentialscredential-id) - [DELETE /credentials/{credential_id}](#scalar-operation-delete-credentialscredential-id) - [GET /connections](#scalar-operation-get-connections) - [POST /connections](#scalar-operation-post-connections) - [PATCH /connections/{connection_id}](#scalar-operation-patch-connectionsconnection-id) - [GET /connections/{connection_id}](#scalar-operation-get-connectionsconnection-id) - [DELETE /connections/{connection_id}](#scalar-operation-delete-connectionsconnection-id) - [GET /skills](#scalar-operation-get-skills) - [POST /skills](#scalar-operation-post-skills) - [GET /skills/{skill_id}/versions](#scalar-operation-get-skillsskill-idversions) - [POST /skills/{skill_id}/versions](#scalar-operation-post-skillsskill-idversions) - [GET /skills/{skill_id}/versions/{version}](#scalar-operation-get-skillsskill-idversionsversion) - [GET /agents](#scalar-operation-get-agents) - [POST /agents](#scalar-operation-post-agents) - [GET /agents/{agent_id}](#scalar-operation-get-agentsagent-id) - [GET /agents/{agent_id}/versions](#scalar-operation-get-agentsagent-idversions) - [POST /agents/{agent_id}/versions](#scalar-operation-post-agentsagent-idversions) - [GET /sessions](#scalar-operation-get-sessions) - [POST /sessions](#scalar-operation-post-sessions) - [GET /sessions/{session_id}](#scalar-operation-get-sessionssession-id) - [DELETE /sessions/{session_id}](#scalar-operation-delete-sessionssession-id) - [GET /sessions/{session_id}/submissions](#scalar-operation-get-sessionssession-idsubmissions) - [POST /sessions/{session_id}/submissions](#scalar-operation-post-sessionssession-idsubmissions) - [GET /sessions/{session_id}/submissions/{submission_id}](#scalar-operation-get-sessionssession-idsubmissionssubmission-id) - [POST /sessions/{session_id}/submissions/{submission_id}/cancel](#scalar-operation-post-sessionssession-idsubmissionssubmission-idcancel) - [POST /sessions/{session_id}/cancel](#scalar-operation-post-sessionssession-idcancel) - [GET /sessions/{session_id}/lifecycle](#scalar-operation-get-sessionssession-idlifecycle) - [POST /sessions/{session_id}/archive](#scalar-operation-post-sessionssession-idarchive) - [POST /sessions/{session_id}/standby](#scalar-operation-post-sessionssession-idstandby) - [GET /sessions/{session_id}/entries](#scalar-operation-get-sessionssession-identries) - [GET /sessions/{session_id}/tool-calls](#scalar-operation-get-sessionssession-idtool-calls) - [GET /sessions/{session_id}/tool-calls/{call_id}](#scalar-operation-get-sessionssession-idtool-callscall-id) - [GET /sessions/{session_id}/state](#scalar-operation-get-sessionssession-idstate) - [GET /sessions/{session_id}/events](#scalar-operation-get-sessionssession-idevents) - [GET /sessions/{session_id}/artifacts](#scalar-operation-get-sessionssession-idartifacts) - [GET /webhooks](#scalar-operation-get-webhooks) - [POST /webhooks](#scalar-operation-post-webhooks) - [DELETE /webhooks/{webhook_id}](#scalar-operation-delete-webhookswebhook-id) - [GET /webhooks/{webhook_id}/deliveries](#scalar-operation-get-webhookswebhook-iddeliveries) - [POST /files](#scalar-operation-post-files) - [GET /files/{file_id}](#scalar-operation-get-filesfile-id) - [DELETE /files/{file_id}](#scalar-operation-delete-filesfile-id) **Schemas** - [ApiKeyList](#scalar-schema-apikeylist) - [CredentialList](#scalar-schema-credentiallist) - [ConnectionList](#scalar-schema-connectionlist) - [AgentList](#scalar-schema-agentlist) - [AgentVersionList](#scalar-schema-agentversionlist) - [SessionList](#scalar-schema-sessionlist) - [SubmissionList](#scalar-schema-submissionlist) - [EntryList](#scalar-schema-entrylist) - [ApiKey](#scalar-schema-apikey) - [CreatedApiKey](#scalar-schema-createdapikey) - [ProviderApiKey](#scalar-schema-providerapikey) - [CreateCredential](#scalar-schema-createcredential) - [Credential](#scalar-schema-credential) - [CreateModelCredential](#scalar-schema-createmodelcredential) - [ModelCredential](#scalar-schema-modelcredential) - [CreateSandboxCredential](#scalar-schema-createsandboxcredential) - [SandboxCredential](#scalar-schema-sandboxcredential) - [CreateWebSearchCredential](#scalar-schema-createwebsearchcredential) - [WebSearchCredential](#scalar-schema-websearchcredential) - [CreateBrowserCredential](#scalar-schema-createbrowsercredential) - [BrowserCredential](#scalar-schema-browsercredential) - [ToolEndpointCredentials](#scalar-schema-toolendpointcredentials) - [CreateConnection](#scalar-schema-createconnection) - [Connection](#scalar-schema-connection) - [SkillVersionSelector](#scalar-schema-skillversionselector) - [SkillAttachment](#scalar-schema-skillattachment) - [Skill](#scalar-schema-skill) - [SkillManifestFile](#scalar-schema-skillmanifestfile) - [SkillVersion](#scalar-schema-skillversion) - [SkillVersionContents](#scalar-schema-skillversioncontents) - [SkillList](#scalar-schema-skilllist) - [SkillVersionList](#scalar-schema-skillversionlist) - [AgentConfig](#scalar-schema-agentconfig) - [AgentModel](#scalar-schema-agentmodel) - [Sandbox](#scalar-schema-sandbox) - [ToolGrant](#scalar-schema-toolgrant) - [Agent](#scalar-schema-agent) - [AgentVersion](#scalar-schema-agentversion) - [Session](#scalar-schema-session) - [SessionLifecycle](#scalar-schema-sessionlifecycle) - [SessionOverrides](#scalar-schema-sessionoverrides) - [CreateSubmission](#scalar-schema-createsubmission) - [InputContent](#scalar-schema-inputcontent) - [InputBlock](#scalar-schema-inputblock) - [Submission](#scalar-schema-submission) - [Entry](#scalar-schema-entry) - [ContentBlock](#scalar-schema-contentblock) - [Message](#scalar-schema-message) - [ExecutionError](#scalar-schema-executionerror) - [Usage](#scalar-schema-usage) - [CumulativeUsage](#scalar-schema-cumulativeusage) - [Inbox](#scalar-schema-inbox) - [Retry](#scalar-schema-retry) - [ToolDiagnostic](#scalar-schema-tooldiagnostic) - [ToolProgress](#scalar-schema-toolprogress) - [ToolCallList](#scalar-schema-toolcalllist) - [ToolCall](#scalar-schema-toolcall) - [ToolActivity](#scalar-schema-toolactivity) - [Compaction](#scalar-schema-compaction) - [CompactionFailure](#scalar-schema-compactionfailure) - [State](#scalar-schema-state) - [ExecutionEvent](#scalar-schema-executionevent) - [MessageStarted](#scalar-schema-messagestarted) - [MessageDelta](#scalar-schema-messagedelta) - [MessageReplaced](#scalar-schema-messagereplaced) - [MessageCompleted](#scalar-schema-messagecompleted) - [ToolStarted](#scalar-schema-toolstarted) - [ToolOutputChange](#scalar-schema-tooloutputchange) - [ToolUpdated](#scalar-schema-toolupdated) - [ToolCompleted](#scalar-schema-toolcompleted) - [RetryEnded](#scalar-schema-retryended) - [CompactionStarted](#scalar-schema-compactionstarted) - [CompactionCompleted](#scalar-schema-compactioncompleted) - [InboxUpdated](#scalar-schema-inboxupdated) - [ExecutionFailed](#scalar-schema-executionfailed) - [ModelList](#scalar-schema-modellist) - [File](#scalar-schema-file) - [Artifact](#scalar-schema-artifact) - [ArtifactList](#scalar-schema-artifactlist) - [Webhook](#scalar-schema-webhook) - [CreatedWebhook](#scalar-schema-createdwebhook) - [WebhookList](#scalar-schema-webhooklist) - [WebhookEvent](#scalar-schema-webhookevent) - [WebhookDelivery](#scalar-schema-webhookdelivery) - [WebhookDeliveryList](#scalar-schema-webhookdeliverylist) ## Servers - **URL:** `https://api.useclyck.com/v1` - **Description:** Platform instance ## Authentication - **ApiKey**: HTTP bearer ## Tags ### Skills Upload, inspect and attach tenant-owned, immutable skill versions. Skills provide instructions and supporting files without requiring a sandbox. ### Agents Configure reusable agents. Every configuration change creates an immutable version, and each session starts from a specific version, so you can roll out changes deliberately. ### Model catalog Discover model providers, model IDs and capabilities before selecting a model. ### Sessions A session is one durable conversation started from an agent version. Submit input, stream progress, and read history, submissions and tool calls. Sessions start in `standby`, become `active` when processing new input or context, and become `idle` when that execution finishes. After five minutes idle, the session automatically enters `standby`. New input or context wakes a standby session automatically. Reads, polling and open event streams do not reset the idle timer or prevent standby. Retrying a submission with the same `request_id` does not extend the idle period. Standby preserves the session's configuration, history and sandbox files, and releases any Clyck-provided browser, losing its state. Browsers using your `credential_id` remain bound, subject to their provider lifetime. Daytona VM sandboxes (Linux VM and Windows), including attached sandboxes, are paused on standby, preserving their files and memory. Daytona containers are not explicitly paused. Sandboxes created in your Daytona account use Daytona's default inactivity timers; attached sandboxes keep their existing settings. The next sandbox tool call resumes a paused Daytona sandbox or starts a stopped or archived one before executing. Stop and archive preserve files but lose running processes and memory. Blaxel manages sandbox suspension and resumption automatically; other connections or keep-alive work can keep a Blaxel sandbox running. Sandboxes are not deleted on standby. To release resources immediately, call `POST /sessions/{session_id}/standby`; it returns `409 session_busy` during active work. To remove a session and its owned sandbox, delete the session. To release owned resources permanently while retaining readable history, archive the session. An existing sandbox attached with `sandbox_id` stays yours. ### Files Upload files for the agent to work on, and download the files it publishes. Uploaded files, published outputs and reserved pending publications share the tenant's file storage capacity shown in the [dashboard](/dashboard/usage). A write that would exceed capacity fails with `409 usage_limit_exceeded`; existing files remain readable and deletable. Deleting a stored file frees its storage. Storage does not reset monthly, and sandbox working files are not counted toward stored file capacity. #### Input files Upload bytes to `/files`, then submit `{type: "file", file_id}` or `{type: "image", file_id}` blocks in `content`. File blocks use the Clyck-managed sandbox (`sandbox: {provider: "clyck-managed"}`); other configurations return `400 files_require_sandbox`. Before the submission is accepted, Clyck copies each file into the session's sandbox and gives the model the file's name and absolute path. Acceptance is all or nothing: if a copy fails, or the input is rejected with `409 conversation_busy`, no copies are left behind. The copy is the agent's working copy: later steps see the agent's edits, and deleting the upload leaves it in place. Files of queued input are in the sandbox before earlier work finishes. Image blocks go directly to the model, with or without a sandbox; use a model whose `input` in `GET /models` includes `image`. Images can be inline base64 or a `file_id` in PNG, JPEG, GIF or WebP format. Clyck decodes and normalizes them to at most 2000 pixels per dimension and 4.5 MiB, and the decoded format replaces a declared `mime_type`. Images that cannot be decoded return `400 invalid_image` before acceptance. A submission references up to 16 MiB of file bytes, counting repeated references separately; larger input returns `413 input_files_too_large`. `Entry.input` keeps the submitted references and `entry.model` contains the model-facing content. Files are private to their tenant; a missing file or one belonging to another tenant returns `404`. #### Publishing output artifacts Grant `{type: "platform", name: "publish_file"}` to an agent with the Clyck-managed sandbox. When a file is finished, the agent calls `tools.publish_file({path, filename?, mime_type?})` inside `codemode`. `path` is an absolute path to a regular file; parent directory symlinks are resolved, and a symlink as the final path component or a special file is rejected. The filename defaults to the path's basename and the media type to `application/octet-stream`. Each artifact is up to 16 MiB. Clyck reads the bytes directly from the sandbox, so they never pass through the model, and returns the stored file metadata, a SHA-256 checksum and provenance. Publish a file after the agent has finished writing it. Each publication is an immutable copy. List it with `GET /sessions/{session_id}/artifacts`, download it with `GET /files/{file_id}` and delete it with `DELETE /files/{file_id}`. Published files are kept until you delete them, independently of the sandbox, the source file and the session; keep their file IDs if you delete the session first. Retrying the same publication returns the same file ID and bytes, and a separate call publishes a new copy. Lists and `artifact.created` webhooks include completed publications, including those from a submission that later fails. ### Webhooks Receive background results through signed HTTPS requests when a submission finishes or an artifact is published. Subscribe a public HTTPS URL to `submission.updated`, `artifact.created`, or both. - **`submission.updated`** fires when a submission reaches `done`, `cancelled` or `failed`. Context submissions reach `done` when placed and have no answer. The session stays ready for more input. - **`artifact.created`** fires when a published file is ready to download. Each notification carries the event `id`, `type`, `session_id` and the `submission_id` or `file_id`. Read that resource through this API for its current state, which also keeps retried deliveries from carrying stale data. **Delivery behavior** - **Duplicates:** delivery is at-least-once within the retry window. Retries keep the same event ID and body; deduplicate by event ID. - **Ordering:** notifications can arrive in any order; drive state from the resource you read. - **Retries:** each attempt has a 10-second timeout and counts any `2xx` as acknowledgement. Failed attempts retry after 60 seconds with exponential backoff up to one hour between attempts, for 24 hours from the event; a delivery still unacknowledged then is marked `failed`. `GET /webhooks/{webhook_id}/deliveries` shows each delivery's status, attempts and next attempt time. For complete coverage, also reconcile your tracked submissions through reads, for example on a schedule. - **Recipients:** an event goes to the registrations that exist when it is first queued. - **Destinations:** URLs are public HTTPS endpoints, called without following redirects. Keep credentials out of the URL; requests are authenticated by signature. - **Cancellation:** deleting a registration or a session cancels its pending deliveries; a request already in flight can still arrive. Deleting a session keeps its published files. **Verifying signatures** Registration returns `signing_secret` once; store it to verify requests. The URL, events and secret of a registration are fixed; create a new registration to change them. Each request carries `Webhook-Id` (equal to the body `id`), `Webhook-Timestamp` (Unix seconds) and `Webhook-Signature` (`v1=`). Compute HMAC-SHA256 with the `signing_secret` string as the key over the UTF-8 string `.`, and compare its hexadecimal digest to the signature with a constant-time comparison. Check that the timestamp is recent, verify the signature over the raw body before parsing it, and deduplicate by event ID. Each retry is signed with its own attempt timestamp. ### BYO credentials Store model, sandbox, web search and browser provider API keys in `/credentials`. `category` identifies the use: `model`, `sandbox`, `web_search` or `browser`. Clyck validates provider-specific settings at creation and checks authentication with the provider when the key is used. Models use your own keys. Web search and browser tools use Clyck's provider accounts unless a grant selects your credential, in which case that credential is always used. API keys are encrypted at rest and write-only. Settings and agent configuration are readable by every caller in your tenant, so keep secrets in `api_key`. Tool results are recorded as returned and reach the model, entries and tool calls, so design tools to return results rather than their own credentials. `PATCH` with `api_key` rotates the secret and keeps the credential's ID, `category`, `provider`, `settings` and session bindings. New model requests and tool operations, including those of running sessions, use the new secret; operations already in flight and established connections finish with the previous one, and an existing browser stays attached to the same pages. Delete a credential after archiving or deleting the sessions that use it. Deleting it in Clyck leaves the key active at your provider. Credentials and connections are separate resources with separate IDs; filter the credentials list with `category`. ### Tool connections Store your MCP servers (Streamable HTTP) and HTTP tool endpoints in `/connections` with `type` `mcp` or `http`, then grant agents the tools they need. Clyck validates the configuration at creation and checks authentication when the endpoint is used. Each agent's explicit grants select the tools it may call from a connection. Authentication is encrypted at rest and write-only. Connections are reached over the public internet. A URL naming `localhost` or a literal private, loopback, link-local, shared, multicast or other special-purpose address returns `400 destination_not_allowed`. Clyck resolves hostnames for every connection and contacts only public addresses: an MCP server that resolves to a special-purpose address fails session activation with `409 invalid_configuration` naming the connection, and an HTTP tool call returns a tool error. Clyck calls endpoints directly, without following redirects. Tool results are recorded as returned and reach the model, entries and tool calls, so design endpoints to return results rather than their own credentials. `PATCH` with `credentials` rotates authentication and keeps the ID, `type`, URL and session bindings. `credentials` replaces the complete authentication object, and `{}` removes authentication. New operations use the new authentication; operations already in flight and established connections finish with the previous one. Delete a connection after archiving or deleting the sessions that use it. Filter the connections list with `type`. ### Platform API keys Create, list and revoke the keys that authenticate requests to this API. Each key has full access to its tenant, including key management. ## Operations ### List platform API key metadata - **Method:** `GET` - **Path:** `/api-keys` - **Operation ID:** `listApiKeys` - **Tags:** Platform API keys **Servers:** [Inherited servers](#scalar-context-global-servers) **Authentication:** [Global authentication](#scalar-context-global-authentication) #### Query parameters - **`limit`**: `integer`, default: `100`, minimum: `1`, maximum: `100` - **`cursor`**: `string` #### Responses ##### 200 A page of API key metadata. **Content type:** `application/json` [ApiKeyList](/reference/schemas/ApiKeyList.md) ##### default Error object. Codes include \`invalid_request\`, \`invalid_webhook_signature\`, \`destination_not_allowed\`, \`files_require_sandbox\`, \`invalid_image\`, \`invalid_media_type\`, \`invalid_filename\` and \`invalid_skill\` (\`400\`); \`unauthorized\` (\`401\`); \`card_verification_required\` (\`402\`); \`not_found\` (\`404\`); \`conversation_busy\`, \`request_conflict\`, \`credential_in_use\`, \`connection_in_use\`, \`invalid_configuration\`, \`session_busy\`, \`session_deleting\` and \`usage_limit_exceeded\` (\`409\`); \`concurrency_limit_exceeded\` (\`429\`); \`body_too_large\`, \`file_too_large\`, \`input_files_too_large\` and \`skill_too_large\` (\`413\`); \`unsupported_media_type\` (\`415\`); \`internal_error\` (\`500\`); and \`session_unavailable\`, \`runtime_unavailable\`, \`files_unavailable\`, \`skills_unavailable\` and \`webhooks_unavailable\` (\`503\`, temporary: retry after a short wait). Branch on \`code\`; \`message\` is a human-readable explanation whose wording can change. **Content type:** `application/json` - **`error` (required)**: `object` - **`code` (required)**: `string` - **`message` (required)**: `string` ### Create a platform API key for the current tenant - **Method:** `POST` - **Path:** `/api-keys` - **Operation ID:** `createApiKey` - **Tags:** Platform API keys Any authenticated tenant caller may create keys. The secret is returned only in this response. **Servers:** [Inherited servers](#scalar-context-global-servers) **Authentication:** [Global authentication](#scalar-context-global-authentication) #### Request body **Required:** `true` **Content type:** `application/json` no additional properties - **`name` (required)**: `string`, minLength: `1`, maxLength: `200`, pattern: `\S` #### Responses ##### 201 Key metadata and one-time secret. **Content type:** `application/json` [CreatedApiKey](/reference/schemas/CreatedApiKey.md) ##### default Error object. Codes include \`invalid_request\`, \`invalid_webhook_signature\`, \`destination_not_allowed\`, \`files_require_sandbox\`, \`invalid_image\`, \`invalid_media_type\`, \`invalid_filename\` and \`invalid_skill\` (\`400\`); \`unauthorized\` (\`401\`); \`card_verification_required\` (\`402\`); \`not_found\` (\`404\`); \`conversation_busy\`, \`request_conflict\`, \`credential_in_use\`, \`connection_in_use\`, \`invalid_configuration\`, \`session_busy\`, \`session_deleting\` and \`usage_limit_exceeded\` (\`409\`); \`concurrency_limit_exceeded\` (\`429\`); \`body_too_large\`, \`file_too_large\`, \`input_files_too_large\` and \`skill_too_large\` (\`413\`); \`unsupported_media_type\` (\`415\`); \`internal_error\` (\`500\`); and \`session_unavailable\`, \`runtime_unavailable\`, \`files_unavailable\`, \`skills_unavailable\` and \`webhooks_unavailable\` (\`503\`, temporary: retry after a short wait). Branch on \`code\`; \`message\` is a human-readable explanation whose wording can change. **Content type:** `application/json` - **`error` (required)**: `object` - **`code` (required)**: `string` - **`message` (required)**: `string` ### Revoke a platform API key - **Method:** `DELETE` - **Path:** `/api-keys/{key_id}` - **Operation ID:** `deleteApiKey` - **Tags:** Platform API keys **Servers:** [Inherited servers](#scalar-context-global-servers) **Authentication:** [Global authentication](#scalar-context-global-authentication) #### Path parameters - **`key_id` (required)**: `string`, format: `uuid` #### Responses ##### 204 The key can no longer authenticate new requests. ##### default Error object. Codes include \`invalid_request\`, \`invalid_webhook_signature\`, \`destination_not_allowed\`, \`files_require_sandbox\`, \`invalid_image\`, \`invalid_media_type\`, \`invalid_filename\` and \`invalid_skill\` (\`400\`); \`unauthorized\` (\`401\`); \`card_verification_required\` (\`402\`); \`not_found\` (\`404\`); \`conversation_busy\`, \`request_conflict\`, \`credential_in_use\`, \`connection_in_use\`, \`invalid_configuration\`, \`session_busy\`, \`session_deleting\` and \`usage_limit_exceeded\` (\`409\`); \`concurrency_limit_exceeded\` (\`429\`); \`body_too_large\`, \`file_too_large\`, \`input_files_too_large\` and \`skill_too_large\` (\`413\`); \`unsupported_media_type\` (\`415\`); \`internal_error\` (\`500\`); and \`session_unavailable\`, \`runtime_unavailable\`, \`files_unavailable\`, \`skills_unavailable\` and \`webhooks_unavailable\` (\`503\`, temporary: retry after a short wait). Branch on \`code\`; \`message\` is a human-readable explanation whose wording can change. **Content type:** `application/json` - **`error` (required)**: `object` - **`code` (required)**: `string` - **`message` (required)**: `string` ### List supported model capabilities - **Method:** `GET` - **Path:** `/models` - **Operation ID:** `listModels` - **Tags:** Model catalog **Servers:** [Inherited servers](#scalar-context-global-servers) **Authentication:** [Global authentication](#scalar-context-global-authentication) #### Responses ##### 200 Available provider/model pairs and their capabilities. **Content type:** `application/json` [ModelList](/reference/schemas/ModelList.md) ##### default Error object. Codes include \`invalid_request\`, \`invalid_webhook_signature\`, \`destination_not_allowed\`, \`files_require_sandbox\`, \`invalid_image\`, \`invalid_media_type\`, \`invalid_filename\` and \`invalid_skill\` (\`400\`); \`unauthorized\` (\`401\`); \`card_verification_required\` (\`402\`); \`not_found\` (\`404\`); \`conversation_busy\`, \`request_conflict\`, \`credential_in_use\`, \`connection_in_use\`, \`invalid_configuration\`, \`session_busy\`, \`session_deleting\` and \`usage_limit_exceeded\` (\`409\`); \`concurrency_limit_exceeded\` (\`429\`); \`body_too_large\`, \`file_too_large\`, \`input_files_too_large\` and \`skill_too_large\` (\`413\`); \`unsupported_media_type\` (\`415\`); \`internal_error\` (\`500\`); and \`session_unavailable\`, \`runtime_unavailable\`, \`files_unavailable\`, \`skills_unavailable\` and \`webhooks_unavailable\` (\`503\`, temporary: retry after a short wait). Branch on \`code\`; \`message\` is a human-readable explanation whose wording can change. **Content type:** `application/json` - **`error` (required)**: `object` - **`code` (required)**: `string` - **`message` (required)**: `string` ### List BYO credentials - **Method:** `GET` - **Path:** `/credentials` - **Operation ID:** `listCredentials` - **Tags:** BYO credentials **Servers:** [Inherited servers](#scalar-context-global-servers) **Authentication:** [Global authentication](#scalar-context-global-authentication) #### Query parameters - **`limit`**: `integer`, default: `100`, minimum: `1`, maximum: `100` - **`cursor`**: `string` - **`category`**: `string`, possible values: `"model", "sandbox", "web_search", "browser"` Include only credentials in this category. Keep this filter unchanged when using a cursor. #### Responses ##### 200 A page of credential metadata. API keys are write-only. **Content type:** `application/json` [CredentialList](/reference/schemas/CredentialList.md) ##### default Error object. Codes include \`invalid_request\`, \`invalid_webhook_signature\`, \`destination_not_allowed\`, \`files_require_sandbox\`, \`invalid_image\`, \`invalid_media_type\`, \`invalid_filename\` and \`invalid_skill\` (\`400\`); \`unauthorized\` (\`401\`); \`card_verification_required\` (\`402\`); \`not_found\` (\`404\`); \`conversation_busy\`, \`request_conflict\`, \`credential_in_use\`, \`connection_in_use\`, \`invalid_configuration\`, \`session_busy\`, \`session_deleting\` and \`usage_limit_exceeded\` (\`409\`); \`concurrency_limit_exceeded\` (\`429\`); \`body_too_large\`, \`file_too_large\`, \`input_files_too_large\` and \`skill_too_large\` (\`413\`); \`unsupported_media_type\` (\`415\`); \`internal_error\` (\`500\`); and \`session_unavailable\`, \`runtime_unavailable\`, \`files_unavailable\`, \`skills_unavailable\` and \`webhooks_unavailable\` (\`503\`, temporary: retry after a short wait). Branch on \`code\`; \`message\` is a human-readable explanation whose wording can change. **Content type:** `application/json` - **`error` (required)**: `object` - **`code` (required)**: `string` - **`message` (required)**: `string` ### Store a BYO credential - **Method:** `POST` - **Path:** `/credentials` - **Operation ID:** `createCredential` - **Tags:** BYO credentials **Servers:** [Inherited servers](#scalar-context-global-servers) **Authentication:** [Global authentication](#scalar-context-global-authentication) #### Request body **Required:** `true` **Content type:** `application/json` [CreateCredential](/reference/schemas/CreateCredential.md) Store a provider secret. `category` and `provider` determine the accepted `settings`; secrets are write-only. #### Responses ##### 201 Stored credential metadata. API keys are write-only. **Content type:** `application/json` [Credential](/reference/schemas/Credential.md) Provider credential metadata. API keys are write-only. ##### default Error object. Codes include \`invalid_request\`, \`invalid_webhook_signature\`, \`destination_not_allowed\`, \`files_require_sandbox\`, \`invalid_image\`, \`invalid_media_type\`, \`invalid_filename\` and \`invalid_skill\` (\`400\`); \`unauthorized\` (\`401\`); \`card_verification_required\` (\`402\`); \`not_found\` (\`404\`); \`conversation_busy\`, \`request_conflict\`, \`credential_in_use\`, \`connection_in_use\`, \`invalid_configuration\`, \`session_busy\`, \`session_deleting\` and \`usage_limit_exceeded\` (\`409\`); \`concurrency_limit_exceeded\` (\`429\`); \`body_too_large\`, \`file_too_large\`, \`input_files_too_large\` and \`skill_too_large\` (\`413\`); \`unsupported_media_type\` (\`415\`); \`internal_error\` (\`500\`); and \`session_unavailable\`, \`runtime_unavailable\`, \`files_unavailable\`, \`skills_unavailable\` and \`webhooks_unavailable\` (\`503\`, temporary: retry after a short wait). Branch on \`code\`; \`message\` is a human-readable explanation whose wording can change. **Content type:** `application/json` - **`error` (required)**: `object` - **`code` (required)**: `string` - **`message` (required)**: `string` ### Rotate provider API key - **Method:** `PATCH` - **Path:** `/credentials/{credential_id}` - **Operation ID:** `rotateCredential` - **Tags:** BYO credentials Replaces the secret and keeps the credential's identity, settings and session bindings. New model requests and tool operations, including those of running sessions, use the new secret; operations already in flight and established connections finish with the previous one. **Servers:** [Inherited servers](#scalar-context-global-servers) **Authentication:** [Global authentication](#scalar-context-global-authentication) #### Path parameters - **`credential_id` (required)**: `string`, format: `uuid` #### Request body **Required:** `true` **Content type:** `application/json` no additional properties - **`api_key` (required)**: [ProviderApiKey](/reference/schemas/ProviderApiKey.md) Provider API key; encrypted at rest and write-only. Authentication is checked when the key is used. A selected customer key is always the one used. #### Responses ##### 200 Credential metadata. API keys are write-only. **Content type:** `application/json` [Credential](/reference/schemas/Credential.md) Provider credential metadata. API keys are write-only. ##### default Error object. Codes include \`invalid_request\`, \`invalid_webhook_signature\`, \`destination_not_allowed\`, \`files_require_sandbox\`, \`invalid_image\`, \`invalid_media_type\`, \`invalid_filename\` and \`invalid_skill\` (\`400\`); \`unauthorized\` (\`401\`); \`card_verification_required\` (\`402\`); \`not_found\` (\`404\`); \`conversation_busy\`, \`request_conflict\`, \`credential_in_use\`, \`connection_in_use\`, \`invalid_configuration\`, \`session_busy\`, \`session_deleting\` and \`usage_limit_exceeded\` (\`409\`); \`concurrency_limit_exceeded\` (\`429\`); \`body_too_large\`, \`file_too_large\`, \`input_files_too_large\` and \`skill_too_large\` (\`413\`); \`unsupported_media_type\` (\`415\`); \`internal_error\` (\`500\`); and \`session_unavailable\`, \`runtime_unavailable\`, \`files_unavailable\`, \`skills_unavailable\` and \`webhooks_unavailable\` (\`503\`, temporary: retry after a short wait). Branch on \`code\`; \`message\` is a human-readable explanation whose wording can change. **Content type:** `application/json` - **`error` (required)**: `object` - **`code` (required)**: `string` - **`message` (required)**: `string` ### Get credential metadata - **Method:** `GET` - **Path:** `/credentials/{credential_id}` - **Operation ID:** `getCredential` - **Tags:** BYO credentials **Servers:** [Inherited servers](#scalar-context-global-servers) **Authentication:** [Global authentication](#scalar-context-global-authentication) #### Path parameters - **`credential_id` (required)**: `string`, format: `uuid` #### Responses ##### 200 Credential metadata. API keys are write-only. **Content type:** `application/json` [Credential](/reference/schemas/Credential.md) Provider credential metadata. API keys are write-only. ##### default Error object. Codes include \`invalid_request\`, \`invalid_webhook_signature\`, \`destination_not_allowed\`, \`files_require_sandbox\`, \`invalid_image\`, \`invalid_media_type\`, \`invalid_filename\` and \`invalid_skill\` (\`400\`); \`unauthorized\` (\`401\`); \`card_verification_required\` (\`402\`); \`not_found\` (\`404\`); \`conversation_busy\`, \`request_conflict\`, \`credential_in_use\`, \`connection_in_use\`, \`invalid_configuration\`, \`session_busy\`, \`session_deleting\` and \`usage_limit_exceeded\` (\`409\`); \`concurrency_limit_exceeded\` (\`429\`); \`body_too_large\`, \`file_too_large\`, \`input_files_too_large\` and \`skill_too_large\` (\`413\`); \`unsupported_media_type\` (\`415\`); \`internal_error\` (\`500\`); and \`session_unavailable\`, \`runtime_unavailable\`, \`files_unavailable\`, \`skills_unavailable\` and \`webhooks_unavailable\` (\`503\`, temporary: retry after a short wait). Branch on \`code\`; \`message\` is a human-readable explanation whose wording can change. **Content type:** `application/json` - **`error` (required)**: `object` - **`code` (required)**: `string` - **`message` (required)**: `string` ### Delete a credential - **Method:** `DELETE` - **Path:** `/credentials/{credential_id}` - **Operation ID:** `deleteCredential` - **Tags:** BYO credentials Archive or delete the sessions that use a credential first; while any session that has not finished archiving references it, this returns `409 credential_in_use`. Agent versions keep the IDs they were created with, so create a new version that selects another credential before starting new sessions; a session from a version naming a deleted credential returns `404`. **Servers:** [Inherited servers](#scalar-context-global-servers) **Authentication:** [Global authentication](#scalar-context-global-authentication) #### Path parameters - **`credential_id` (required)**: `string`, format: `uuid` #### Responses ##### 204 Credential deleted from Clyck. The API key stays active at your provider until you revoke it there. ##### default Error object. Codes include \`invalid_request\`, \`invalid_webhook_signature\`, \`destination_not_allowed\`, \`files_require_sandbox\`, \`invalid_image\`, \`invalid_media_type\`, \`invalid_filename\` and \`invalid_skill\` (\`400\`); \`unauthorized\` (\`401\`); \`card_verification_required\` (\`402\`); \`not_found\` (\`404\`); \`conversation_busy\`, \`request_conflict\`, \`credential_in_use\`, \`connection_in_use\`, \`invalid_configuration\`, \`session_busy\`, \`session_deleting\` and \`usage_limit_exceeded\` (\`409\`); \`concurrency_limit_exceeded\` (\`429\`); \`body_too_large\`, \`file_too_large\`, \`input_files_too_large\` and \`skill_too_large\` (\`413\`); \`unsupported_media_type\` (\`415\`); \`internal_error\` (\`500\`); and \`session_unavailable\`, \`runtime_unavailable\`, \`files_unavailable\`, \`skills_unavailable\` and \`webhooks_unavailable\` (\`503\`, temporary: retry after a short wait). Branch on \`code\`; \`message\` is a human-readable explanation whose wording can change. **Content type:** `application/json` - **`error` (required)**: `object` - **`code` (required)**: `string` - **`message` (required)**: `string` ### List tool connections - **Method:** `GET` - **Path:** `/connections` - **Operation ID:** `listConnections` - **Tags:** Tool connections **Servers:** [Inherited servers](#scalar-context-global-servers) **Authentication:** [Global authentication](#scalar-context-global-authentication) #### Query parameters - **`limit`**: `integer`, default: `100`, minimum: `1`, maximum: `100` - **`cursor`**: `string` - **`type`**: `string`, possible values: `"mcp", "http"` Include only connections of this type. Keep this filter unchanged when using a cursor. #### Responses ##### 200 A page of connection metadata. Authentication is write-only. **Content type:** `application/json` [ConnectionList](/reference/schemas/ConnectionList.md) ##### default Error object. Codes include \`invalid_request\`, \`invalid_webhook_signature\`, \`destination_not_allowed\`, \`files_require_sandbox\`, \`invalid_image\`, \`invalid_media_type\`, \`invalid_filename\` and \`invalid_skill\` (\`400\`); \`unauthorized\` (\`401\`); \`card_verification_required\` (\`402\`); \`not_found\` (\`404\`); \`conversation_busy\`, \`request_conflict\`, \`credential_in_use\`, \`connection_in_use\`, \`invalid_configuration\`, \`session_busy\`, \`session_deleting\` and \`usage_limit_exceeded\` (\`409\`); \`concurrency_limit_exceeded\` (\`429\`); \`body_too_large\`, \`file_too_large\`, \`input_files_too_large\` and \`skill_too_large\` (\`413\`); \`unsupported_media_type\` (\`415\`); \`internal_error\` (\`500\`); and \`session_unavailable\`, \`runtime_unavailable\`, \`files_unavailable\`, \`skills_unavailable\` and \`webhooks_unavailable\` (\`503\`, temporary: retry after a short wait). Branch on \`code\`; \`message\` is a human-readable explanation whose wording can change. **Content type:** `application/json` - **`error` (required)**: `object` - **`code` (required)**: `string` - **`message` (required)**: `string` ### Create a tool connection - **Method:** `POST` - **Path:** `/connections` - **Operation ID:** `createConnection` - **Tags:** Tool connections **Servers:** [Inherited servers](#scalar-context-global-servers) **Authentication:** [Global authentication](#scalar-context-global-authentication) #### Request body **Required:** `true` **Content type:** `application/json` [CreateConnection](/reference/schemas/CreateConnection.md) **Example:** ```json { "name": "My tools", "type": "mcp", "url": "https://tools.example.com/mcp", "credentials": { "api_key": "your-tool-endpoint-token" } } ``` #### Responses ##### 201 Stored connection metadata. Authentication is write-only. **Content type:** `application/json` [Connection](/reference/schemas/Connection.md) ##### default Error object. Codes include \`invalid_request\`, \`invalid_webhook_signature\`, \`destination_not_allowed\`, \`files_require_sandbox\`, \`invalid_image\`, \`invalid_media_type\`, \`invalid_filename\` and \`invalid_skill\` (\`400\`); \`unauthorized\` (\`401\`); \`card_verification_required\` (\`402\`); \`not_found\` (\`404\`); \`conversation_busy\`, \`request_conflict\`, \`credential_in_use\`, \`connection_in_use\`, \`invalid_configuration\`, \`session_busy\`, \`session_deleting\` and \`usage_limit_exceeded\` (\`409\`); \`concurrency_limit_exceeded\` (\`429\`); \`body_too_large\`, \`file_too_large\`, \`input_files_too_large\` and \`skill_too_large\` (\`413\`); \`unsupported_media_type\` (\`415\`); \`internal_error\` (\`500\`); and \`session_unavailable\`, \`runtime_unavailable\`, \`files_unavailable\`, \`skills_unavailable\` and \`webhooks_unavailable\` (\`503\`, temporary: retry after a short wait). Branch on \`code\`; \`message\` is a human-readable explanation whose wording can change. **Content type:** `application/json` - **`error` (required)**: `object` - **`code` (required)**: `string` - **`message` (required)**: `string` ### Rotate connection authentication - **Method:** `PATCH` - **Path:** `/connections/{connection_id}` - **Operation ID:** `rotateConnection` - **Tags:** Tool connections Replaces the authentication and keeps the connection's identity, URL and session bindings. New tool operations, including those of running sessions, use the new authentication; operations already in flight and established connections finish with the previous one. **Servers:** [Inherited servers](#scalar-context-global-servers) **Authentication:** [Global authentication](#scalar-context-global-authentication) #### Path parameters - **`connection_id` (required)**: `string`, format: `uuid` #### Request body **Required:** `true` **Content type:** `application/json` no additional properties - **`credentials` (required)**: [ToolEndpointCredentials](/reference/schemas/ToolEndpointCredentials.md) Endpoint authentication; encrypted at rest and never returned. Omit for unauthenticated endpoints, or supply `headers` and an optional `api_key` sent as a `Bearer` `Authorization` header. Keys and header values must not contain carriage returns or newlines. Authentication is checked when the endpoint is used. #### Responses ##### 200 Connection metadata. Authentication is write-only. **Content type:** `application/json` [Connection](/reference/schemas/Connection.md) ##### default Error object. Codes include \`invalid_request\`, \`invalid_webhook_signature\`, \`destination_not_allowed\`, \`files_require_sandbox\`, \`invalid_image\`, \`invalid_media_type\`, \`invalid_filename\` and \`invalid_skill\` (\`400\`); \`unauthorized\` (\`401\`); \`card_verification_required\` (\`402\`); \`not_found\` (\`404\`); \`conversation_busy\`, \`request_conflict\`, \`credential_in_use\`, \`connection_in_use\`, \`invalid_configuration\`, \`session_busy\`, \`session_deleting\` and \`usage_limit_exceeded\` (\`409\`); \`concurrency_limit_exceeded\` (\`429\`); \`body_too_large\`, \`file_too_large\`, \`input_files_too_large\` and \`skill_too_large\` (\`413\`); \`unsupported_media_type\` (\`415\`); \`internal_error\` (\`500\`); and \`session_unavailable\`, \`runtime_unavailable\`, \`files_unavailable\`, \`skills_unavailable\` and \`webhooks_unavailable\` (\`503\`, temporary: retry after a short wait). Branch on \`code\`; \`message\` is a human-readable explanation whose wording can change. **Content type:** `application/json` - **`error` (required)**: `object` - **`code` (required)**: `string` - **`message` (required)**: `string` ### Get connection metadata - **Method:** `GET` - **Path:** `/connections/{connection_id}` - **Operation ID:** `getConnection` - **Tags:** Tool connections **Servers:** [Inherited servers](#scalar-context-global-servers) **Authentication:** [Global authentication](#scalar-context-global-authentication) #### Path parameters - **`connection_id` (required)**: `string`, format: `uuid` #### Responses ##### 200 Connection metadata. Authentication is write-only. **Content type:** `application/json` [Connection](/reference/schemas/Connection.md) ##### default Error object. Codes include \`invalid_request\`, \`invalid_webhook_signature\`, \`destination_not_allowed\`, \`files_require_sandbox\`, \`invalid_image\`, \`invalid_media_type\`, \`invalid_filename\` and \`invalid_skill\` (\`400\`); \`unauthorized\` (\`401\`); \`card_verification_required\` (\`402\`); \`not_found\` (\`404\`); \`conversation_busy\`, \`request_conflict\`, \`credential_in_use\`, \`connection_in_use\`, \`invalid_configuration\`, \`session_busy\`, \`session_deleting\` and \`usage_limit_exceeded\` (\`409\`); \`concurrency_limit_exceeded\` (\`429\`); \`body_too_large\`, \`file_too_large\`, \`input_files_too_large\` and \`skill_too_large\` (\`413\`); \`unsupported_media_type\` (\`415\`); \`internal_error\` (\`500\`); and \`session_unavailable\`, \`runtime_unavailable\`, \`files_unavailable\`, \`skills_unavailable\` and \`webhooks_unavailable\` (\`503\`, temporary: retry after a short wait). Branch on \`code\`; \`message\` is a human-readable explanation whose wording can change. **Content type:** `application/json` - **`error` (required)**: `object` - **`code` (required)**: `string` - **`message` (required)**: `string` ### Delete a tool connection - **Method:** `DELETE` - **Path:** `/connections/{connection_id}` - **Operation ID:** `deleteConnection` - **Tags:** Tool connections Archive or delete the sessions that use a connection first; while any session that has not finished archiving references it, this returns `409 connection_in_use`. Agent versions keep the IDs they were created with, so create a new version that selects another connection before starting new sessions; a session from a version naming a deleted connection returns `404`. **Servers:** [Inherited servers](#scalar-context-global-servers) **Authentication:** [Global authentication](#scalar-context-global-authentication) #### Path parameters - **`connection_id` (required)**: `string`, format: `uuid` #### Responses ##### 204 Tool connection deleted. ##### default Error object. Codes include \`invalid_request\`, \`invalid_webhook_signature\`, \`destination_not_allowed\`, \`files_require_sandbox\`, \`invalid_image\`, \`invalid_media_type\`, \`invalid_filename\` and \`invalid_skill\` (\`400\`); \`unauthorized\` (\`401\`); \`card_verification_required\` (\`402\`); \`not_found\` (\`404\`); \`conversation_busy\`, \`request_conflict\`, \`credential_in_use\`, \`connection_in_use\`, \`invalid_configuration\`, \`session_busy\`, \`session_deleting\` and \`usage_limit_exceeded\` (\`409\`); \`concurrency_limit_exceeded\` (\`429\`); \`body_too_large\`, \`file_too_large\`, \`input_files_too_large\` and \`skill_too_large\` (\`413\`); \`unsupported_media_type\` (\`415\`); \`internal_error\` (\`500\`); and \`session_unavailable\`, \`runtime_unavailable\`, \`files_unavailable\`, \`skills_unavailable\` and \`webhooks_unavailable\` (\`503\`, temporary: retry after a short wait). Branch on \`code\`; \`message\` is a human-readable explanation whose wording can change. **Content type:** `application/json` - **`error` (required)**: `object` - **`code` (required)**: `string` - **`message` (required)**: `string` ### List skills - **Method:** `GET` - **Path:** `/skills` - **Operation ID:** `listSkills` - **Tags:** Skills **Servers:** [Inherited servers](#scalar-context-global-servers) **Authentication:** [Global authentication](#scalar-context-global-authentication) #### Query parameters - **`limit`**: `integer`, default: `100`, minimum: `1`, maximum: `100` - **`cursor`**: `string` #### Responses ##### 200 A page of skills, with descriptions from their latest versions. **Content type:** `application/json` [SkillList](/reference/schemas/SkillList.md) ##### default Error object. Codes include \`invalid_request\`, \`invalid_webhook_signature\`, \`destination_not_allowed\`, \`files_require_sandbox\`, \`invalid_image\`, \`invalid_media_type\`, \`invalid_filename\` and \`invalid_skill\` (\`400\`); \`unauthorized\` (\`401\`); \`card_verification_required\` (\`402\`); \`not_found\` (\`404\`); \`conversation_busy\`, \`request_conflict\`, \`credential_in_use\`, \`connection_in_use\`, \`invalid_configuration\`, \`session_busy\`, \`session_deleting\` and \`usage_limit_exceeded\` (\`409\`); \`concurrency_limit_exceeded\` (\`429\`); \`body_too_large\`, \`file_too_large\`, \`input_files_too_large\` and \`skill_too_large\` (\`413\`); \`unsupported_media_type\` (\`415\`); \`internal_error\` (\`500\`); and \`session_unavailable\`, \`runtime_unavailable\`, \`files_unavailable\`, \`skills_unavailable\` and \`webhooks_unavailable\` (\`503\`, temporary: retry after a short wait). Branch on \`code\`; \`message\` is a human-readable explanation whose wording can change. **Content type:** `application/json` - **`error` (required)**: `object` - **`code` (required)**: `string` - **`message` (required)**: `string` ### Upload skill - **Method:** `POST` - **Path:** `/skills` - **Operation ID:** `createSkill` - **Tags:** Skills Creates a skill with immutable version `1`. Upload the complete directory as multipart `files[]` parts with relative filenames, or as a ZIP. Include `SKILL.md` at the upload root or inside one enclosing directory. Each bundle is limited to 1,000 regular files and 30,000,000 uncompressed bytes; ZIPs contain at most 2,000 entries including directories, and file paths contain at most 4,096 characters. The complete HTTP body is limited to 64,000,000 bytes. Invalid bundles return `400 invalid_skill` and oversized bundles return `413 skill_too_large`; neither publishes a version. Skill storage has no aggregate limit and does not consume uploaded-file allowances. **Servers:** [Inherited servers](#scalar-context-global-servers) **Authentication:** [Global authentication](#scalar-context-global-authentication) #### Request body **Required:** `true` **Content type:** `multipart/form-data` no additional properties - **`files[]` (required)**: `array of string`, minItems: `1`, maxItems: `1000` File parts use their relative skill paths as filenames. A ZIP may be sent as one file part. **Content type:** `application/zip` `string` #### Responses ##### 201 Skill identity with latest_version set to '1'. **Content type:** `application/json` [Skill](/reference/schemas/Skill.md) ##### default Error object. Codes include \`invalid_request\`, \`invalid_webhook_signature\`, \`destination_not_allowed\`, \`files_require_sandbox\`, \`invalid_image\`, \`invalid_media_type\`, \`invalid_filename\` and \`invalid_skill\` (\`400\`); \`unauthorized\` (\`401\`); \`card_verification_required\` (\`402\`); \`not_found\` (\`404\`); \`conversation_busy\`, \`request_conflict\`, \`credential_in_use\`, \`connection_in_use\`, \`invalid_configuration\`, \`session_busy\`, \`session_deleting\` and \`usage_limit_exceeded\` (\`409\`); \`concurrency_limit_exceeded\` (\`429\`); \`body_too_large\`, \`file_too_large\`, \`input_files_too_large\` and \`skill_too_large\` (\`413\`); \`unsupported_media_type\` (\`415\`); \`internal_error\` (\`500\`); and \`session_unavailable\`, \`runtime_unavailable\`, \`files_unavailable\`, \`skills_unavailable\` and \`webhooks_unavailable\` (\`503\`, temporary: retry after a short wait). Branch on \`code\`; \`message\` is a human-readable explanation whose wording can change. **Content type:** `application/json` - **`error` (required)**: `object` - **`code` (required)**: `string` - **`message` (required)**: `string` ### List skill versions - **Method:** `GET` - **Path:** `/skills/{skill_id}/versions` - **Operation ID:** `listSkillVersions` - **Tags:** Skills **Servers:** [Inherited servers](#scalar-context-global-servers) **Authentication:** [Global authentication](#scalar-context-global-authentication) #### Path parameters - **`skill_id` (required)**: `string`, format: `uuid` #### Query parameters - **`limit`**: `integer`, default: `100`, minimum: `1`, maximum: `100` - **`cursor`**: `string` #### Responses ##### 200 A page of immutable version metadata and file manifests, newest first. **Content type:** `application/json` [SkillVersionList](/reference/schemas/SkillVersionList.md) ##### default Error object. Codes include \`invalid_request\`, \`invalid_webhook_signature\`, \`destination_not_allowed\`, \`files_require_sandbox\`, \`invalid_image\`, \`invalid_media_type\`, \`invalid_filename\` and \`invalid_skill\` (\`400\`); \`unauthorized\` (\`401\`); \`card_verification_required\` (\`402\`); \`not_found\` (\`404\`); \`conversation_busy\`, \`request_conflict\`, \`credential_in_use\`, \`connection_in_use\`, \`invalid_configuration\`, \`session_busy\`, \`session_deleting\` and \`usage_limit_exceeded\` (\`409\`); \`concurrency_limit_exceeded\` (\`429\`); \`body_too_large\`, \`file_too_large\`, \`input_files_too_large\` and \`skill_too_large\` (\`413\`); \`unsupported_media_type\` (\`415\`); \`internal_error\` (\`500\`); and \`session_unavailable\`, \`runtime_unavailable\`, \`files_unavailable\`, \`skills_unavailable\` and \`webhooks_unavailable\` (\`503\`, temporary: retry after a short wait). Branch on \`code\`; \`message\` is a human-readable explanation whose wording can change. **Content type:** `application/json` - **`error` (required)**: `object` - **`code` (required)**: `string` - **`message` (required)**: `string` ### Update skill - **Method:** `POST` - **Path:** `/skills/{skill_id}/versions` - **Operation ID:** `createSkillVersion` - **Tags:** Skills Upload replacement files to create a new immutable version. Applies the same bundle validation and limits as uploading a skill. The name in `SKILL.md` must match the skill's existing name. This is a complete snapshot: omitted files are not carried forward. New versions do not change existing agent versions or sessions. Missing and other tenants' skills return `404`. **Servers:** [Inherited servers](#scalar-context-global-servers) **Authentication:** [Global authentication](#scalar-context-global-authentication) #### Path parameters - **`skill_id` (required)**: `string`, format: `uuid` #### Request body **Required:** `true` **Content type:** `multipart/form-data` no additional properties - **`files[]` (required)**: `array of string`, minItems: `1`, maxItems: `1000` File parts use their relative skill paths as filenames. A ZIP may be sent as one file part. **Content type:** `application/zip` `string` #### Responses ##### 201 The newly published version's metadata and file manifest. **Content type:** `application/json` [SkillVersion](/reference/schemas/SkillVersion.md) ##### default Error object. Codes include \`invalid_request\`, \`invalid_webhook_signature\`, \`destination_not_allowed\`, \`files_require_sandbox\`, \`invalid_image\`, \`invalid_media_type\`, \`invalid_filename\` and \`invalid_skill\` (\`400\`); \`unauthorized\` (\`401\`); \`card_verification_required\` (\`402\`); \`not_found\` (\`404\`); \`conversation_busy\`, \`request_conflict\`, \`credential_in_use\`, \`connection_in_use\`, \`invalid_configuration\`, \`session_busy\`, \`session_deleting\` and \`usage_limit_exceeded\` (\`409\`); \`concurrency_limit_exceeded\` (\`429\`); \`body_too_large\`, \`file_too_large\`, \`input_files_too_large\` and \`skill_too_large\` (\`413\`); \`unsupported_media_type\` (\`415\`); \`internal_error\` (\`500\`); and \`session_unavailable\`, \`runtime_unavailable\`, \`files_unavailable\`, \`skills_unavailable\` and \`webhooks_unavailable\` (\`503\`, temporary: retry after a short wait). Branch on \`code\`; \`message\` is a human-readable explanation whose wording can change. **Content type:** `application/json` - **`error` (required)**: `object` - **`code` (required)**: `string` - **`message` (required)**: `string` ### Get skill version - **Method:** `GET` - **Path:** `/skills/{skill_id}/versions/{version}` - **Operation ID:** `getSkillVersion` - **Tags:** Skills Defaults to JSON metadata and every file's exact bytes encoded as base64. Send `Accept: application/zip` to download the complete version as a ZIP. `latest` is resolved for this request; both representations identify the concrete version returned. Missing and other tenants' skills return `404` without exposing their metadata or files. **Servers:** [Inherited servers](#scalar-context-global-servers) **Authentication:** [Global authentication](#scalar-context-global-authentication) #### Path parameters - **`skill_id` (required)**: `string`, format: `uuid` - **`version` (required)**: `string`, pattern: `^(latest|[1-9][0-9]*)$` A concrete positive version number encoded as a string, or latest. Getters always identify a concrete version. #### Responses ##### 200 Complete skill version. ZIP responses have an attachment disposition and X-Skill-Version header. **Headers:** - **`X-Skill-Version`** Concrete version returned, including when the request selected latest. `string`, pattern: `^[1-9][0-9]*$` **Content type:** `application/json` [SkillVersionContents](/reference/schemas/SkillVersionContents.md) **Content type:** `application/zip` `string` ##### default Error object. Codes include \`invalid_request\`, \`invalid_webhook_signature\`, \`destination_not_allowed\`, \`files_require_sandbox\`, \`invalid_image\`, \`invalid_media_type\`, \`invalid_filename\` and \`invalid_skill\` (\`400\`); \`unauthorized\` (\`401\`); \`card_verification_required\` (\`402\`); \`not_found\` (\`404\`); \`conversation_busy\`, \`request_conflict\`, \`credential_in_use\`, \`connection_in_use\`, \`invalid_configuration\`, \`session_busy\`, \`session_deleting\` and \`usage_limit_exceeded\` (\`409\`); \`concurrency_limit_exceeded\` (\`429\`); \`body_too_large\`, \`file_too_large\`, \`input_files_too_large\` and \`skill_too_large\` (\`413\`); \`unsupported_media_type\` (\`415\`); \`internal_error\` (\`500\`); and \`session_unavailable\`, \`runtime_unavailable\`, \`files_unavailable\`, \`skills_unavailable\` and \`webhooks_unavailable\` (\`503\`, temporary: retry after a short wait). Branch on \`code\`; \`message\` is a human-readable explanation whose wording can change. **Content type:** `application/json` - **`error` (required)**: `object` - **`code` (required)**: `string` - **`message` (required)**: `string` ### List agent identities - **Method:** `GET` - **Path:** `/agents` - **Operation ID:** `listAgents` - **Tags:** Agents **Servers:** [Inherited servers](#scalar-context-global-servers) **Authentication:** [Global authentication](#scalar-context-global-authentication) #### Query parameters - **`limit`**: `integer`, default: `100`, minimum: `1`, maximum: `100` - **`cursor`**: `string` #### Responses ##### 200 A page of agent identities. **Content type:** `application/json` [AgentList](/reference/schemas/AgentList.md) ##### default Error object. Codes include \`invalid_request\`, \`invalid_webhook_signature\`, \`destination_not_allowed\`, \`files_require_sandbox\`, \`invalid_image\`, \`invalid_media_type\`, \`invalid_filename\` and \`invalid_skill\` (\`400\`); \`unauthorized\` (\`401\`); \`card_verification_required\` (\`402\`); \`not_found\` (\`404\`); \`conversation_busy\`, \`request_conflict\`, \`credential_in_use\`, \`connection_in_use\`, \`invalid_configuration\`, \`session_busy\`, \`session_deleting\` and \`usage_limit_exceeded\` (\`409\`); \`concurrency_limit_exceeded\` (\`429\`); \`body_too_large\`, \`file_too_large\`, \`input_files_too_large\` and \`skill_too_large\` (\`413\`); \`unsupported_media_type\` (\`415\`); \`internal_error\` (\`500\`); and \`session_unavailable\`, \`runtime_unavailable\`, \`files_unavailable\`, \`skills_unavailable\` and \`webhooks_unavailable\` (\`503\`, temporary: retry after a short wait). Branch on \`code\`; \`message\` is a human-readable explanation whose wording can change. **Content type:** `application/json` - **`error` (required)**: `object` - **`code` (required)**: `string` - **`message` (required)**: `string` ### Create an agent and its first immutable version - **Method:** `POST` - **Path:** `/agents` - **Operation ID:** `createAgent` - **Tags:** Agents Creates the agent and its first immutable version. Sessions start from a specific version and can override `model`, `instructions`, `thinking_level`, `tools`, `skills` and `sandbox` for that session alone: each supplied field replaces the version's field, omitted fields are inherited, and `sandbox` `null` removes an inherited sandbox. Clyck resolves skill `latest` selectors when creating this agent version, validates the resolved configuration and keeps it fixed for the session. New versions apply to new sessions, so running sessions keep the configuration they started with. The model works through one tool, `codemode`, and calls the granted tools from the JavaScript programs it writes. Each grant names exactly the tools the agent may use. Inside `codemode`, HTTP tools use their grant name, sandbox tools are named `sandbox_`, and MCP tools are named `mcp__`, where characters other than letters, digits and `_` become `_` and the suffix is stable for the connection and tool; `ALL_TOOLS` and `searchTools` list the callable names. Programs run in a deterministic runtime so they resume exactly after an interruption: time advances as tool results arrive, so programs wait by calling tools rather than with timers such as `setTimeout`. Each program runs for up to 120 seconds; a first line of `// @options: {"timeout_ms": 30000}` sets a shorter deadline. **Servers:** [Inherited servers](#scalar-context-global-servers) **Authentication:** [Global authentication](#scalar-context-global-authentication) #### Request body **Required:** `true` **Content type:** `application/json` no additional properties - **`config` (required)**: [AgentConfig](/reference/schemas/AgentConfig.md) - **`name` (required)**: `string`, minLength: `1`, maxLength: `200`, pattern: `\S` #### Responses ##### 201 Agent with \`latest_version\` containing its first version. **Content type:** `application/json` [Agent](/reference/schemas/Agent.md) ##### default Error object. Codes include \`invalid_request\`, \`invalid_webhook_signature\`, \`destination_not_allowed\`, \`files_require_sandbox\`, \`invalid_image\`, \`invalid_media_type\`, \`invalid_filename\` and \`invalid_skill\` (\`400\`); \`unauthorized\` (\`401\`); \`card_verification_required\` (\`402\`); \`not_found\` (\`404\`); \`conversation_busy\`, \`request_conflict\`, \`credential_in_use\`, \`connection_in_use\`, \`invalid_configuration\`, \`session_busy\`, \`session_deleting\` and \`usage_limit_exceeded\` (\`409\`); \`concurrency_limit_exceeded\` (\`429\`); \`body_too_large\`, \`file_too_large\`, \`input_files_too_large\` and \`skill_too_large\` (\`413\`); \`unsupported_media_type\` (\`415\`); \`internal_error\` (\`500\`); and \`session_unavailable\`, \`runtime_unavailable\`, \`files_unavailable\`, \`skills_unavailable\` and \`webhooks_unavailable\` (\`503\`, temporary: retry after a short wait). Branch on \`code\`; \`message\` is a human-readable explanation whose wording can change. **Content type:** `application/json` - **`error` (required)**: `object` - **`code` (required)**: `string` - **`message` (required)**: `string` ### Get an agent and its latest version - **Method:** `GET` - **Path:** `/agents/{agent_id}` - **Operation ID:** `getAgent` - **Tags:** Agents **Servers:** [Inherited servers](#scalar-context-global-servers) **Authentication:** [Global authentication](#scalar-context-global-authentication) #### Path parameters - **`agent_id` (required)**: `string`, format: `uuid` #### Responses ##### 200 Agent and latest immutable version. **Content type:** `application/json` [Agent](/reference/schemas/Agent.md) ##### default Error object. Codes include \`invalid_request\`, \`invalid_webhook_signature\`, \`destination_not_allowed\`, \`files_require_sandbox\`, \`invalid_image\`, \`invalid_media_type\`, \`invalid_filename\` and \`invalid_skill\` (\`400\`); \`unauthorized\` (\`401\`); \`card_verification_required\` (\`402\`); \`not_found\` (\`404\`); \`conversation_busy\`, \`request_conflict\`, \`credential_in_use\`, \`connection_in_use\`, \`invalid_configuration\`, \`session_busy\`, \`session_deleting\` and \`usage_limit_exceeded\` (\`409\`); \`concurrency_limit_exceeded\` (\`429\`); \`body_too_large\`, \`file_too_large\`, \`input_files_too_large\` and \`skill_too_large\` (\`413\`); \`unsupported_media_type\` (\`415\`); \`internal_error\` (\`500\`); and \`session_unavailable\`, \`runtime_unavailable\`, \`files_unavailable\`, \`skills_unavailable\` and \`webhooks_unavailable\` (\`503\`, temporary: retry after a short wait). Branch on \`code\`; \`message\` is a human-readable explanation whose wording can change. **Content type:** `application/json` - **`error` (required)**: `object` - **`code` (required)**: `string` - **`message` (required)**: `string` ### List immutable versions newest first - **Method:** `GET` - **Path:** `/agents/{agent_id}/versions` - **Operation ID:** `listAgentVersions` - **Tags:** Agents **Servers:** [Inherited servers](#scalar-context-global-servers) **Authentication:** [Global authentication](#scalar-context-global-authentication) #### Path parameters - **`agent_id` (required)**: `string`, format: `uuid` #### Query parameters - **`limit`**: `integer`, default: `100`, minimum: `1`, maximum: `100` - **`cursor`**: `string` #### Responses ##### 200 A page of immutable agent versions. **Content type:** `application/json` [AgentVersionList](/reference/schemas/AgentVersionList.md) ##### default Error object. Codes include \`invalid_request\`, \`invalid_webhook_signature\`, \`destination_not_allowed\`, \`files_require_sandbox\`, \`invalid_image\`, \`invalid_media_type\`, \`invalid_filename\` and \`invalid_skill\` (\`400\`); \`unauthorized\` (\`401\`); \`card_verification_required\` (\`402\`); \`not_found\` (\`404\`); \`conversation_busy\`, \`request_conflict\`, \`credential_in_use\`, \`connection_in_use\`, \`invalid_configuration\`, \`session_busy\`, \`session_deleting\` and \`usage_limit_exceeded\` (\`409\`); \`concurrency_limit_exceeded\` (\`429\`); \`body_too_large\`, \`file_too_large\`, \`input_files_too_large\` and \`skill_too_large\` (\`413\`); \`unsupported_media_type\` (\`415\`); \`internal_error\` (\`500\`); and \`session_unavailable\`, \`runtime_unavailable\`, \`files_unavailable\`, \`skills_unavailable\` and \`webhooks_unavailable\` (\`503\`, temporary: retry after a short wait). Branch on \`code\`; \`message\` is a human-readable explanation whose wording can change. **Content type:** `application/json` - **`error` (required)**: `object` - **`code` (required)**: `string` - **`message` (required)**: `string` ### Create a new immutable version - **Method:** `POST` - **Path:** `/agents/{agent_id}/versions` - **Operation ID:** `createAgentVersion` - **Tags:** Agents Creates a new immutable version and makes it the agent's `latest_version`. New sessions can start from it, and existing sessions keep the configuration they started with. **Servers:** [Inherited servers](#scalar-context-global-servers) **Authentication:** [Global authentication](#scalar-context-global-authentication) #### Path parameters - **`agent_id` (required)**: `string`, format: `uuid` #### Request body **Required:** `true` **Content type:** `application/json` no additional properties - **`config` (required)**: [AgentConfig](/reference/schemas/AgentConfig.md) #### Responses ##### 201 New version. Existing sessions keep their original configuration. **Content type:** `application/json` [AgentVersion](/reference/schemas/AgentVersion.md) ##### default Error object. Codes include \`invalid_request\`, \`invalid_webhook_signature\`, \`destination_not_allowed\`, \`files_require_sandbox\`, \`invalid_image\`, \`invalid_media_type\`, \`invalid_filename\` and \`invalid_skill\` (\`400\`); \`unauthorized\` (\`401\`); \`card_verification_required\` (\`402\`); \`not_found\` (\`404\`); \`conversation_busy\`, \`request_conflict\`, \`credential_in_use\`, \`connection_in_use\`, \`invalid_configuration\`, \`session_busy\`, \`session_deleting\` and \`usage_limit_exceeded\` (\`409\`); \`concurrency_limit_exceeded\` (\`429\`); \`body_too_large\`, \`file_too_large\`, \`input_files_too_large\` and \`skill_too_large\` (\`413\`); \`unsupported_media_type\` (\`415\`); \`internal_error\` (\`500\`); and \`session_unavailable\`, \`runtime_unavailable\`, \`files_unavailable\`, \`skills_unavailable\` and \`webhooks_unavailable\` (\`503\`, temporary: retry after a short wait). Branch on \`code\`; \`message\` is a human-readable explanation whose wording can change. **Content type:** `application/json` - **`error` (required)**: `object` - **`code` (required)**: `string` - **`message` (required)**: `string` ### List sessions - **Method:** `GET` - **Path:** `/sessions` - **Operation ID:** `listSessions` - **Tags:** Sessions Includes archived sessions. Use `archived` to filter by archive status, and keep that filter when following a cursor. **Servers:** [Inherited servers](#scalar-context-global-servers) **Authentication:** [Global authentication](#scalar-context-global-authentication) #### Query parameters - **`archived`**: `boolean` When supplied, return only archived sessions (true) or sessions that have not been archived (false). - **`limit`**: `integer`, default: `100`, minimum: `1`, maximum: `100` - **`cursor`**: `string` #### Responses ##### 200 A page of sessions. **Content type:** `application/json` [SessionList](/reference/schemas/SessionList.md) ##### default Error object. Codes include \`invalid_request\`, \`invalid_webhook_signature\`, \`destination_not_allowed\`, \`files_require_sandbox\`, \`invalid_image\`, \`invalid_media_type\`, \`invalid_filename\` and \`invalid_skill\` (\`400\`); \`unauthorized\` (\`401\`); \`card_verification_required\` (\`402\`); \`not_found\` (\`404\`); \`conversation_busy\`, \`request_conflict\`, \`credential_in_use\`, \`connection_in_use\`, \`invalid_configuration\`, \`session_busy\`, \`session_deleting\` and \`usage_limit_exceeded\` (\`409\`); \`concurrency_limit_exceeded\` (\`429\`); \`body_too_large\`, \`file_too_large\`, \`input_files_too_large\` and \`skill_too_large\` (\`413\`); \`unsupported_media_type\` (\`415\`); \`internal_error\` (\`500\`); and \`session_unavailable\`, \`runtime_unavailable\`, \`files_unavailable\`, \`skills_unavailable\` and \`webhooks_unavailable\` (\`503\`, temporary: retry after a short wait). Branch on \`code\`; \`message\` is a human-readable explanation whose wording can change. **Content type:** `application/json` - **`error` (required)**: `object` - **`code` (required)**: `string` - **`message` (required)**: `string` ### Create a session from a specific agent version - **Method:** `POST` - **Path:** `/sessions` - **Operation ID:** `createSession` - **Tags:** Sessions Starts a durable conversation from an agent version. `overrides` replace complete top-level configuration fields for this session, and omitted fields inherit from the version. Clyck validates the resolved configuration and keeps it fixed for the session; the agent version is unchanged. A supplied `overrides.skills` list replaces all inherited attachments and resolves `latest` selectors when the session is created; `[]` clears skills. **Durability and recovery.** Accepted input and conversation history persist across process crashes, restarts and deploys, and active work continues automatically afterwards. Check a submission's outcome before submitting replacement work. During recovery, Clyck repeats model requests and tool operations that are safe to repeat. A tool call interrupted after it started is recorded with `outcome` `unknown` rather than repeated, so confirm its effect with the service that owns it before trying again. A model answer interrupted mid-generation stays in history as an assistant message with `stop_reason` `aborted`, and the answer is then generated again. **Availability.** When a session runs or wakes from standby, Clyck connects its model, MCP servers and platform tools. If one is unreachable, Clyck retries with increasing delay of up to five minutes. New work and reads of an active or idle conversation retry activation immediately. Reads from standby do not connect model or tool providers. Requests requiring activation return `503 session_unavailable`, or `409 invalid_configuration` when the configuration needs a change; the message names the model, sandbox, connection or platform tool involved. During a runtime failover, which takes up to about 30 seconds, session requests can wait and then return `503 runtime_unavailable`; retry them. **Sandbox and browser.** A configured sandbox is created or attached when a tool first needs it and is then bound to the session for its lifetime. Sandboxes Clyck creates are deleted when the session is archived or deleted; a sandbox attached with `sandbox_id` stays yours. If sandbox creation is rejected, for example for an invalid credential or rate limiting, a later tool operation tries again once the cause is fixed; if its outcome is uncertain, later operations look for that same sandbox. Paused, stopped and archived Daytona sandboxes are resumed or started before the next sandbox tool call, including after provider-side inactivity suspension. If a bound sandbox becomes unavailable, sandbox tools return errors while the conversation history stays intact; start a new session for a fresh sandbox. Daytona sandbox HTTP failures report `Sandbox tool call failed (HTTP )`. When the provider returns a nonempty JSON `message` string of at most 2,000 characters before and after sanitization, the error appends `Daytona error: ` on a new line. Messages are normalized to one line, with control characters removed and reflected authentication credentials redacted. Missing, malformed or oversized messages produce a status-only error; the rest of the provider response is not relayed. Publish files you want to keep, since published artifacts have their own lifecycle (see Files). The browser stays with the session across submissions and reconnections for up to one hour. Session archival, deletion and `helper.reset()` release it and lose its state. Standby also releases Clyck-provided browsers; the next browser use creates a fresh browser. A browser using your `credential_id` remains bound across standby, subject to its provider lifetime. **Servers:** [Inherited servers](#scalar-context-global-servers) **Authentication:** [Global authentication](#scalar-context-global-authentication) #### Request body **Required:** `true` **Content type:** `application/json` no additional properties - **`agent_version_id` (required)**: `string`, format: `uuid` - **`overrides`**: [SessionOverrides](/reference/schemas/SessionOverrides.md) Supplied top-level fields replace the version's fields completely. Omission inherits. `sandbox` `null` removes the sandbox; `tools` must also be replaced if inherited grants require it. Empty `instructions`, `tools` or `skills` clears that field. Skill latest selectors resolve when the session is created. The resolved `config` follows `AgentConfig` validation. #### Responses ##### 201 Session created in standby. Its model and tools connect when it first runs, and a configured sandbox is created or attached when first needed. **Content type:** `application/json` [Session](/reference/schemas/Session.md) ##### default Error object. Codes include \`invalid_request\`, \`invalid_webhook_signature\`, \`destination_not_allowed\`, \`files_require_sandbox\`, \`invalid_image\`, \`invalid_media_type\`, \`invalid_filename\` and \`invalid_skill\` (\`400\`); \`unauthorized\` (\`401\`); \`card_verification_required\` (\`402\`); \`not_found\` (\`404\`); \`conversation_busy\`, \`request_conflict\`, \`credential_in_use\`, \`connection_in_use\`, \`invalid_configuration\`, \`session_busy\`, \`session_deleting\` and \`usage_limit_exceeded\` (\`409\`); \`concurrency_limit_exceeded\` (\`429\`); \`body_too_large\`, \`file_too_large\`, \`input_files_too_large\` and \`skill_too_large\` (\`413\`); \`unsupported_media_type\` (\`415\`); \`internal_error\` (\`500\`); and \`session_unavailable\`, \`runtime_unavailable\`, \`files_unavailable\`, \`skills_unavailable\` and \`webhooks_unavailable\` (\`503\`, temporary: retry after a short wait). Branch on \`code\`; \`message\` is a human-readable explanation whose wording can change. **Content type:** `application/json` - **`error` (required)**: `object` - **`code` (required)**: `string` - **`message` (required)**: `string` ### Get session configuration - **Method:** `GET` - **Path:** `/sessions/{session_id}` - **Operation ID:** `getSession` - **Tags:** Sessions **Servers:** [Inherited servers](#scalar-context-global-servers) **Authentication:** [Global authentication](#scalar-context-global-authentication) #### Path parameters - **`session_id` (required)**: `string`, format: `uuid` #### Responses ##### 200 Session identity and resolved immutable configuration. **Content type:** `application/json` [Session](/reference/schemas/Session.md) ##### default Error object. Codes include \`invalid_request\`, \`invalid_webhook_signature\`, \`destination_not_allowed\`, \`files_require_sandbox\`, \`invalid_image\`, \`invalid_media_type\`, \`invalid_filename\` and \`invalid_skill\` (\`400\`); \`unauthorized\` (\`401\`); \`card_verification_required\` (\`402\`); \`not_found\` (\`404\`); \`conversation_busy\`, \`request_conflict\`, \`credential_in_use\`, \`connection_in_use\`, \`invalid_configuration\`, \`session_busy\`, \`session_deleting\` and \`usage_limit_exceeded\` (\`409\`); \`concurrency_limit_exceeded\` (\`429\`); \`body_too_large\`, \`file_too_large\`, \`input_files_too_large\` and \`skill_too_large\` (\`413\`); \`unsupported_media_type\` (\`415\`); \`internal_error\` (\`500\`); and \`session_unavailable\`, \`runtime_unavailable\`, \`files_unavailable\`, \`skills_unavailable\` and \`webhooks_unavailable\` (\`503\`, temporary: retry after a short wait). Branch on \`code\`; \`message\` is a human-readable explanation whose wording can change. **Content type:** `application/json` - **`error` (required)**: `object` - **`code` (required)**: `string` - **`message` (required)**: `string` ### Stop work, release owned resources, and delete a session - **Method:** `DELETE` - **Path:** `/sessions/{session_id}` - **Operation ID:** `deleteSession` - **Tags:** Sessions **Servers:** [Inherited servers](#scalar-context-global-servers) **Authentication:** [Global authentication](#scalar-context-global-authentication) #### Path parameters - **`session_id` (required)**: `string`, format: `uuid` #### Responses ##### 204 Session deleted. ##### default Error object. Codes include \`invalid_request\`, \`invalid_webhook_signature\`, \`destination_not_allowed\`, \`files_require_sandbox\`, \`invalid_image\`, \`invalid_media_type\`, \`invalid_filename\` and \`invalid_skill\` (\`400\`); \`unauthorized\` (\`401\`); \`card_verification_required\` (\`402\`); \`not_found\` (\`404\`); \`conversation_busy\`, \`request_conflict\`, \`credential_in_use\`, \`connection_in_use\`, \`invalid_configuration\`, \`session_busy\`, \`session_deleting\` and \`usage_limit_exceeded\` (\`409\`); \`concurrency_limit_exceeded\` (\`429\`); \`body_too_large\`, \`file_too_large\`, \`input_files_too_large\` and \`skill_too_large\` (\`413\`); \`unsupported_media_type\` (\`415\`); \`internal_error\` (\`500\`); and \`session_unavailable\`, \`runtime_unavailable\`, \`files_unavailable\`, \`skills_unavailable\` and \`webhooks_unavailable\` (\`503\`, temporary: retry after a short wait). Branch on \`code\`; \`message\` is a human-readable explanation whose wording can change. **Content type:** `application/json` - **`error` (required)**: `object` - **`code` (required)**: `string` - **`message` (required)**: `string` ### List submissions and their outcomes - **Method:** `GET` - **Path:** `/sessions/{session_id}/submissions` - **Operation ID:** `listSubmissions` - **Tags:** Sessions Pages may be empty or shorter than `limit`. Continue using `next_cursor` until it is `null`. **Servers:** [Inherited servers](#scalar-context-global-servers) **Authentication:** [Global authentication](#scalar-context-global-authentication) #### Path parameters - **`session_id` (required)**: `string`, format: `uuid` #### Query parameters - **`limit`**: `integer`, default: `100`, minimum: `1`, maximum: `100` - **`cursor`**: `string` #### Responses ##### 200 A page of input and context submissions. **Content type:** `application/json` [SubmissionList](/reference/schemas/SubmissionList.md) ##### default Error object. Codes include \`invalid_request\`, \`invalid_webhook_signature\`, \`destination_not_allowed\`, \`files_require_sandbox\`, \`invalid_image\`, \`invalid_media_type\`, \`invalid_filename\` and \`invalid_skill\` (\`400\`); \`unauthorized\` (\`401\`); \`card_verification_required\` (\`402\`); \`not_found\` (\`404\`); \`conversation_busy\`, \`request_conflict\`, \`credential_in_use\`, \`connection_in_use\`, \`invalid_configuration\`, \`session_busy\`, \`session_deleting\` and \`usage_limit_exceeded\` (\`409\`); \`concurrency_limit_exceeded\` (\`429\`); \`body_too_large\`, \`file_too_large\`, \`input_files_too_large\` and \`skill_too_large\` (\`413\`); \`unsupported_media_type\` (\`415\`); \`internal_error\` (\`500\`); and \`session_unavailable\`, \`runtime_unavailable\`, \`files_unavailable\`, \`skills_unavailable\` and \`webhooks_unavailable\` (\`503\`, temporary: retry after a short wait). Branch on \`code\`; \`message\` is a human-readable explanation whose wording can change. **Content type:** `application/json` - **`error` (required)**: `object` - **`code` (required)**: `string` - **`message` (required)**: `string` ### Submit input to a session - **Method:** `POST` - **Path:** `/sessions/{session_id}/submissions` - **Operation ID:** `submitInput` - **Tags:** Sessions Send work or context to the session. A `202` response means the input is saved; read the submission, stream events or use a webhook to follow its outcome. **Input.** `content` is text, or ordered text, image and file blocks. Images are inline base64 or a `file_id`; file blocks are copied into the Clyck-managed sandbox and images are decoded before acceptance (see Files). **Idempotency.** `request_id` makes the submission safe to retry: reusing it within the session returns the original submission unchanged, without rereading files. Reusing it for a different `type` returns `409 request_conflict`. To start a new attempt after a terminal `failed` or `cancelled` outcome, inspect the recorded tool effects and submit the task with a new `request_id`. **Outcomes.** A submission is `queued`, then `placed` in the conversation, and ends `done`, `cancelled` or `failed`. A `done` input names its `answer` entry; `cancelled` (explicitly aborted) and `failed` (ended unsuccessfully) include a `reason` and may name a placed entry. Work interrupted by a recoverable runtime event stays pending and continues until it reaches an outcome. `done` means the agent answered; your application judges whether the answer meets its own goals. Several steering submissions can share one answer, so use each submission's `status` to see whether it was answered. **When the agent is busy.** `when_busy` defaults to `followUp`, which waits for the current answer and then starts new work; follow-ups run one at a time. `steer` joins the current work at the next input boundary, normally after tool calls: every steering submission waiting there is placed together and shares the current answer, and steering still waiting when an answer finishes is placed with the next follow-up and shares that answer. `reject` returns `409 conversation_busy` unless the input can start immediately. Cancelling a queued submission withdraws only that input, which ends `cancelled` with `reason` `aborted`; cancelling the session does the same for active work and queued input. New submissions can start work afterwards. **Context.** `type` `context` appends user-provided context, such as history, facts or application updates, without requesting an answer. It is placed immediately when the session is idle, or at the next input boundary while it is busy, and is then `done` with no answer. Context takes no `when_busy`. It stays queued through session cancellation and is placed at the next boundary, which after cancellation is the next submission; cancel it individually to withdraw it. Context adds user messages and leaves instructions and tool grants unchanged. **Servers:** [Inherited servers](#scalar-context-global-servers) **Authentication:** [Global authentication](#scalar-context-global-authentication) #### Path parameters - **`session_id` (required)**: `string`, format: `uuid` #### Request body **Required:** `true` **Content type:** `application/json` [CreateSubmission](/reference/schemas/CreateSubmission.md) **Example:** ```json { "content": "Analyze the account." } ``` **Example:** ```json { "type": "context", "content": "The account tier is premium.", "request_id": "account-tier-1" } ``` #### Responses ##### 202 Input accepted and saved, or the original submission for the same \`request_id\`. **Content type:** `application/json` [Submission](/reference/schemas/Submission.md) The durable outcome of accepted input. `queued` is waiting; `placed` identifies its input entry; `done` identifies its input entry and `answer` entry. `cancelled` and `failed` are terminal and include a stable `reason` and public `error`. Explicit abortion yields `cancelled`; other unsuccessful endings yield `failed`. Multiple input submissions may share one answer. For `type` `context`, `done` means the context entry was placed; context requests no work and has no `answer` field. `queued` context can be withdrawn individually. **Example:** ```json { "id": 7, "conversation_id": 1, "type": "input", "status": "done", "entry": 40, "answer": 42 } ``` **Example:** ```json { "id": 8, "conversation_id": 1, "type": "input", "status": "failed", "reason": "model_error", "error": { "code": "model_error", "message": "The model could not complete the answer. Check the model configuration and retry the submission." } } ``` ##### 409 Error object. Codes include \`invalid_request\`, \`invalid_webhook_signature\`, \`destination_not_allowed\`, \`files_require_sandbox\`, \`invalid_image\`, \`invalid_media_type\`, \`invalid_filename\` and \`invalid_skill\` (\`400\`); \`unauthorized\` (\`401\`); \`card_verification_required\` (\`402\`); \`not_found\` (\`404\`); \`conversation_busy\`, \`request_conflict\`, \`credential_in_use\`, \`connection_in_use\`, \`invalid_configuration\`, \`session_busy\`, \`session_deleting\` and \`usage_limit_exceeded\` (\`409\`); \`concurrency_limit_exceeded\` (\`429\`); \`body_too_large\`, \`file_too_large\`, \`input_files_too_large\` and \`skill_too_large\` (\`413\`); \`unsupported_media_type\` (\`415\`); \`internal_error\` (\`500\`); and \`session_unavailable\`, \`runtime_unavailable\`, \`files_unavailable\`, \`skills_unavailable\` and \`webhooks_unavailable\` (\`503\`, temporary: retry after a short wait). Branch on \`code\`; \`message\` is a human-readable explanation whose wording can change. **Content type:** `application/json` - **`error` (required)**: `object` - **`code` (required)**: `string` - **`message` (required)**: `string` ##### default Error object. Codes include \`invalid_request\`, \`invalid_webhook_signature\`, \`destination_not_allowed\`, \`files_require_sandbox\`, \`invalid_image\`, \`invalid_media_type\`, \`invalid_filename\` and \`invalid_skill\` (\`400\`); \`unauthorized\` (\`401\`); \`card_verification_required\` (\`402\`); \`not_found\` (\`404\`); \`conversation_busy\`, \`request_conflict\`, \`credential_in_use\`, \`connection_in_use\`, \`invalid_configuration\`, \`session_busy\`, \`session_deleting\` and \`usage_limit_exceeded\` (\`409\`); \`concurrency_limit_exceeded\` (\`429\`); \`body_too_large\`, \`file_too_large\`, \`input_files_too_large\` and \`skill_too_large\` (\`413\`); \`unsupported_media_type\` (\`415\`); \`internal_error\` (\`500\`); and \`session_unavailable\`, \`runtime_unavailable\`, \`files_unavailable\`, \`skills_unavailable\` and \`webhooks_unavailable\` (\`503\`, temporary: retry after a short wait). Branch on \`code\`; \`message\` is a human-readable explanation whose wording can change. **Content type:** `application/json` - **`error` (required)**: `object` - **`code` (required)**: `string` - **`message` (required)**: `string` ### Get a submission and its outcome - **Method:** `GET` - **Path:** `/sessions/{session_id}/submissions/{submission_id}` - **Operation ID:** `getSubmission` - **Tags:** Sessions **Servers:** [Inherited servers](#scalar-context-global-servers) **Authentication:** [Global authentication](#scalar-context-global-authentication) #### Path parameters - **`session_id` (required)**: `string`, format: `uuid` - **`submission_id` (required)**: `integer`, minimum: `1` #### Responses ##### 200 Current submission state and answer when present. **Content type:** `application/json` [Submission](/reference/schemas/Submission.md) The durable outcome of accepted input. `queued` is waiting; `placed` identifies its input entry; `done` identifies its input entry and `answer` entry. `cancelled` and `failed` are terminal and include a stable `reason` and public `error`. Explicit abortion yields `cancelled`; other unsuccessful endings yield `failed`. Multiple input submissions may share one answer. For `type` `context`, `done` means the context entry was placed; context requests no work and has no `answer` field. `queued` context can be withdrawn individually. **Example:** ```json { "id": 7, "conversation_id": 1, "type": "input", "status": "done", "entry": 40, "answer": 42 } ``` **Example:** ```json { "id": 8, "conversation_id": 1, "type": "input", "status": "failed", "reason": "model_error", "error": { "code": "model_error", "message": "The model could not complete the answer. Check the model configuration and retry the submission." } } ``` ##### default Error object. Codes include \`invalid_request\`, \`invalid_webhook_signature\`, \`destination_not_allowed\`, \`files_require_sandbox\`, \`invalid_image\`, \`invalid_media_type\`, \`invalid_filename\` and \`invalid_skill\` (\`400\`); \`unauthorized\` (\`401\`); \`card_verification_required\` (\`402\`); \`not_found\` (\`404\`); \`conversation_busy\`, \`request_conflict\`, \`credential_in_use\`, \`connection_in_use\`, \`invalid_configuration\`, \`session_busy\`, \`session_deleting\` and \`usage_limit_exceeded\` (\`409\`); \`concurrency_limit_exceeded\` (\`429\`); \`body_too_large\`, \`file_too_large\`, \`input_files_too_large\` and \`skill_too_large\` (\`413\`); \`unsupported_media_type\` (\`415\`); \`internal_error\` (\`500\`); and \`session_unavailable\`, \`runtime_unavailable\`, \`files_unavailable\`, \`skills_unavailable\` and \`webhooks_unavailable\` (\`503\`, temporary: retry after a short wait). Branch on \`code\`; \`message\` is a human-readable explanation whose wording can change. **Content type:** `application/json` - **`error` (required)**: `object` - **`code` (required)**: `string` - **`message` (required)**: `string` ### Withdraw queued input - **Method:** `POST` - **Path:** `/sessions/{session_id}/submissions/{submission_id}/cancel` - **Operation ID:** `cancelSubmission` - **Tags:** Sessions Withdraws queued input. `cancelled` means the input was withdrawn and ends `cancelled` with `reason` `aborted`; `already_placed` means it is already in the conversation, so cancel the session to stop its work; `settled` means it already has an outcome. An unknown submission returns `404 not_found`. **Servers:** [Inherited servers](#scalar-context-global-servers) **Authentication:** [Global authentication](#scalar-context-global-authentication) #### Path parameters - **`session_id` (required)**: `string`, format: `uuid` - **`submission_id` (required)**: `integer`, minimum: `1` #### Responses ##### 200 Cancellation result for this submission. **Content type:** `application/json` - **`status` (required)**: `string`, possible values: `"cancelled", "already_placed", "settled"` ##### default Error object. Codes include \`invalid_request\`, \`invalid_webhook_signature\`, \`destination_not_allowed\`, \`files_require_sandbox\`, \`invalid_image\`, \`invalid_media_type\`, \`invalid_filename\` and \`invalid_skill\` (\`400\`); \`unauthorized\` (\`401\`); \`card_verification_required\` (\`402\`); \`not_found\` (\`404\`); \`conversation_busy\`, \`request_conflict\`, \`credential_in_use\`, \`connection_in_use\`, \`invalid_configuration\`, \`session_busy\`, \`session_deleting\` and \`usage_limit_exceeded\` (\`409\`); \`concurrency_limit_exceeded\` (\`429\`); \`body_too_large\`, \`file_too_large\`, \`input_files_too_large\` and \`skill_too_large\` (\`413\`); \`unsupported_media_type\` (\`415\`); \`internal_error\` (\`500\`); and \`session_unavailable\`, \`runtime_unavailable\`, \`files_unavailable\`, \`skills_unavailable\` and \`webhooks_unavailable\` (\`503\`, temporary: retry after a short wait). Branch on \`code\`; \`message\` is a human-readable explanation whose wording can change. **Content type:** `application/json` - **`error` (required)**: `object` - **`code` (required)**: `string` - **`message` (required)**: `string` ### Cancel active work and queued inputs - **Method:** `POST` - **Path:** `/sessions/{session_id}/cancel` - **Operation ID:** `cancelSession` - **Tags:** Sessions **Servers:** [Inherited servers](#scalar-context-global-servers) **Authentication:** [Global authentication](#scalar-context-global-authentication) #### Path parameters - **`session_id` (required)**: `string`, format: `uuid` #### Responses ##### 200 Active work and queued input submissions are cancelled. Queued context submissions stay queued for placement; cancel them individually to withdraw them. The session is ready for new input. Tool effects that already happened remain in place. **Content type:** `application/json` - **`cancelled` (required)**: `boolean`, const: `true` ##### default Error object. Codes include \`invalid_request\`, \`invalid_webhook_signature\`, \`destination_not_allowed\`, \`files_require_sandbox\`, \`invalid_image\`, \`invalid_media_type\`, \`invalid_filename\` and \`invalid_skill\` (\`400\`); \`unauthorized\` (\`401\`); \`card_verification_required\` (\`402\`); \`not_found\` (\`404\`); \`conversation_busy\`, \`request_conflict\`, \`credential_in_use\`, \`connection_in_use\`, \`invalid_configuration\`, \`session_busy\`, \`session_deleting\` and \`usage_limit_exceeded\` (\`409\`); \`concurrency_limit_exceeded\` (\`429\`); \`body_too_large\`, \`file_too_large\`, \`input_files_too_large\` and \`skill_too_large\` (\`413\`); \`unsupported_media_type\` (\`415\`); \`internal_error\` (\`500\`); and \`session_unavailable\`, \`runtime_unavailable\`, \`files_unavailable\`, \`skills_unavailable\` and \`webhooks_unavailable\` (\`503\`, temporary: retry after a short wait). Branch on \`code\`; \`message\` is a human-readable explanation whose wording can change. **Content type:** `application/json` - **`error` (required)**: `object` - **`code` (required)**: `string` - **`message` (required)**: `string` ### Get the session's active, idle, standby or archived state - **Method:** `GET` - **Path:** `/sessions/{session_id}/lifecycle` - **Operation ID:** `getSessionLifecycle` - **Tags:** Sessions Reading the lifecycle does not wake the session or reset its five-minute idle timer. **Servers:** [Inherited servers](#scalar-context-global-servers) **Authentication:** [Global authentication](#scalar-context-global-authentication) #### Path parameters - **`session_id` (required)**: `string`, format: `uuid` #### Responses ##### 200 Current session lifecycle state and the start of its current idle period, when idle. **Content type:** `application/json` [SessionLifecycle](/reference/schemas/SessionLifecycle.md) **Example: active** ```json { "state": "active", "idle_since": null } ``` **Example: idle** ```json { "state": "idle", "idle_since": "2026-10-22T12:00:00.000Z" } ``` **Example: standby** ```json { "state": "standby", "idle_since": null } ``` ##### default Error object. Codes include \`invalid_request\`, \`invalid_webhook_signature\`, \`destination_not_allowed\`, \`files_require_sandbox\`, \`invalid_image\`, \`invalid_media_type\`, \`invalid_filename\` and \`invalid_skill\` (\`400\`); \`unauthorized\` (\`401\`); \`card_verification_required\` (\`402\`); \`not_found\` (\`404\`); \`conversation_busy\`, \`request_conflict\`, \`credential_in_use\`, \`connection_in_use\`, \`invalid_configuration\`, \`session_busy\`, \`session_deleting\` and \`usage_limit_exceeded\` (\`409\`); \`concurrency_limit_exceeded\` (\`429\`); \`body_too_large\`, \`file_too_large\`, \`input_files_too_large\` and \`skill_too_large\` (\`413\`); \`unsupported_media_type\` (\`415\`); \`internal_error\` (\`500\`); and \`session_unavailable\`, \`runtime_unavailable\`, \`files_unavailable\`, \`skills_unavailable\` and \`webhooks_unavailable\` (\`503\`, temporary: retry after a short wait). Branch on \`code\`; \`message\` is a human-readable explanation whose wording can change. **Content type:** `application/json` - **`error` (required)**: `object` - **`code` (required)**: `string` - **`message` (required)**: `string` ### Permanently stop a session and retain its history - **Method:** `POST` - **Path:** `/sessions/{session_id}/archive` - **Operation ID:** `archiveSession` - **Tags:** Sessions Irreversibly closes the session to new work. Stops active work, including background work, and cancels all queued input and context submissions. Completed outcomes and tool effects that already happened remain in place. Interrupted submissions end `cancelled` with `reason` `aborted`. There is no unarchive operation. Releases session-owned sandbox and browser resources, including unpublished sandbox files. An attached customer-owned sandbox stays yours. Published artifacts retain their independent lifecycle. Returns success after final outcomes are saved and resource cleanup completes. Repeating archive succeeds without changing `archived_at`. If interrupted or cleanup fails, the session stays closed to new work; Clyck retries unfinished archival automatically, and the archive request can be retried. History reads may temporarily fail while unfinished archival is being completed. `archived_at` records when closure began. Configuration, history, tool calls, submissions, state and artifact listings remain readable. Reads never connect model or tool providers. The event stream returns a final snapshot and closes. Input and context submissions, including retries with an existing `request_id`, cancellation and standby return `409 session_archived`. Delete remains available and removes the stored session history. Outcome webhooks remain eligible for delivery. This operation takes no request body. **Servers:** [Inherited servers](#scalar-context-global-servers) **Authentication:** [Global authentication](#scalar-context-global-authentication) #### Path parameters - **`session_id` (required)**: `string`, format: `uuid` #### Responses ##### 200 The session is permanently archived and its final history is readable. **Content type:** `application/json` no additional properties - **`state` (required)**: `string`, const: `"archived"` **Example:** ```json { "state": "archived" } ``` ##### default Error object. Codes include \`invalid_request\`, \`invalid_webhook_signature\`, \`destination_not_allowed\`, \`files_require_sandbox\`, \`invalid_image\`, \`invalid_media_type\`, \`invalid_filename\` and \`invalid_skill\` (\`400\`); \`unauthorized\` (\`401\`); \`card_verification_required\` (\`402\`); \`not_found\` (\`404\`); \`conversation_busy\`, \`request_conflict\`, \`credential_in_use\`, \`connection_in_use\`, \`invalid_configuration\`, \`session_busy\`, \`session_deleting\` and \`usage_limit_exceeded\` (\`409\`); \`concurrency_limit_exceeded\` (\`429\`); \`body_too_large\`, \`file_too_large\`, \`input_files_too_large\` and \`skill_too_large\` (\`413\`); \`unsupported_media_type\` (\`415\`); \`internal_error\` (\`500\`); and \`session_unavailable\`, \`runtime_unavailable\`, \`files_unavailable\`, \`skills_unavailable\` and \`webhooks_unavailable\` (\`503\`, temporary: retry after a short wait). Branch on \`code\`; \`message\` is a human-readable explanation whose wording can change. **Content type:** `application/json` - **`error` (required)**: `object` - **`code` (required)**: `string` - **`message` (required)**: `string` ### Release an idle session's runtime resources - **Method:** `POST` - **Path:** `/sessions/{session_id}/standby` - **Operation ID:** `standbySession` - **Tags:** Sessions Enters standby immediately, preserving the session and its sandbox files. Releases any Clyck-provided browser and loses its state; the next browser use creates a fresh browser. A browser using your `credential_id` remains bound, subject to its provider lifetime. Pauses bound Daytona Linux VM and Windows sandboxes, including attached sandboxes, and waits for them to pause; already inactive or unavailable sandboxes are left alone. Daytona containers retain their provider lifecycle settings. The next sandbox tool call resumes or starts a paused, stopped or archived Daytona sandbox before executing. New input or context wakes the session automatically. Already in standby succeeds without changing the session. Returns `409 session_busy` during active work; cancel that work first if it should stop. The operation takes no request body. **Servers:** [Inherited servers](#scalar-context-global-servers) **Authentication:** [Global authentication](#scalar-context-global-authentication) #### Path parameters - **`session_id` (required)**: `string`, format: `uuid` #### Responses ##### 200 The session is in standby. Bound Daytona VMs are paused when available; Blaxel manages its sandbox suspension automatically. **Content type:** `application/json` no additional properties - **`state` (required)**: `string`, const: `"standby"` **Example:** ```json { "state": "standby" } ``` ##### default Error object. Codes include \`invalid_request\`, \`invalid_webhook_signature\`, \`destination_not_allowed\`, \`files_require_sandbox\`, \`invalid_image\`, \`invalid_media_type\`, \`invalid_filename\` and \`invalid_skill\` (\`400\`); \`unauthorized\` (\`401\`); \`card_verification_required\` (\`402\`); \`not_found\` (\`404\`); \`conversation_busy\`, \`request_conflict\`, \`credential_in_use\`, \`connection_in_use\`, \`invalid_configuration\`, \`session_busy\`, \`session_deleting\` and \`usage_limit_exceeded\` (\`409\`); \`concurrency_limit_exceeded\` (\`429\`); \`body_too_large\`, \`file_too_large\`, \`input_files_too_large\` and \`skill_too_large\` (\`413\`); \`unsupported_media_type\` (\`415\`); \`internal_error\` (\`500\`); and \`session_unavailable\`, \`runtime_unavailable\`, \`files_unavailable\`, \`skills_unavailable\` and \`webhooks_unavailable\` (\`503\`, temporary: retry after a short wait). Branch on \`code\`; \`message\` is a human-readable explanation whose wording can change. **Content type:** `application/json` - **`error` (required)**: `object` - **`code` (required)**: `string` - **`message` (required)**: `string` ### Read recorded conversation history - **Method:** `GET` - **Path:** `/sessions/{session_id}/entries` - **Operation ID:** `listEntries` - **Tags:** Sessions Read the complete committed history in ID order, newest first unless `order` is `ascending`. `min_entry_id` and `max_entry_id` are inclusive bounds: set both to a submission's `answer` to read that answer, or use `ascending` order with `min_entry_id` one greater than the last entry you received to read new entries. Continue a paginated query with its cursor and the same bounds and order. History includes every committed entry, including entries that context summarization has removed from the live snapshot. Thinking returned by the provider appears as `thinking` blocks in history, state and streamed messages. Its content is what the provider returns for the model: full text, a summary, an empty string or content marked `redacted`. Provider signatures and replay metadata stay internal. **Servers:** [Inherited servers](#scalar-context-global-servers) **Authentication:** [Global authentication](#scalar-context-global-authentication) #### Path parameters - **`session_id` (required)**: `string`, format: `uuid` #### Query parameters - **`limit`**: `integer`, default: `100`, minimum: `1`, maximum: `100` - **`cursor`**: `string` - **`order`**: `string`, possible values: `"ascending", "descending"`, default: `"descending"` - **`min_entry_id`**: `integer`, minimum: `1` - **`max_entry_id`**: `integer`, minimum: `1` #### Responses ##### 200 A page of recorded conversation entries. **Content type:** `application/json` [EntryList](/reference/schemas/EntryList.md) ##### default Error object. Codes include \`invalid_request\`, \`invalid_webhook_signature\`, \`destination_not_allowed\`, \`files_require_sandbox\`, \`invalid_image\`, \`invalid_media_type\`, \`invalid_filename\` and \`invalid_skill\` (\`400\`); \`unauthorized\` (\`401\`); \`card_verification_required\` (\`402\`); \`not_found\` (\`404\`); \`conversation_busy\`, \`request_conflict\`, \`credential_in_use\`, \`connection_in_use\`, \`invalid_configuration\`, \`session_busy\`, \`session_deleting\` and \`usage_limit_exceeded\` (\`409\`); \`concurrency_limit_exceeded\` (\`429\`); \`body_too_large\`, \`file_too_large\`, \`input_files_too_large\` and \`skill_too_large\` (\`413\`); \`unsupported_media_type\` (\`415\`); \`internal_error\` (\`500\`); and \`session_unavailable\`, \`runtime_unavailable\`, \`files_unavailable\`, \`skills_unavailable\` and \`webhooks_unavailable\` (\`503\`, temporary: retry after a short wait). Branch on \`code\`; \`message\` is a human-readable explanation whose wording can change. **Content type:** `application/json` - **`error` (required)**: `object` - **`code` (required)**: `string` - **`message` (required)**: `string` ### List retained top-level and nested tool calls - **Method:** `GET` - **Path:** `/sessions/{session_id}/tool-calls` - **Operation ID:** `listToolCalls` - **Tags:** Sessions The durable record of `codemode` calls and every tool they called: arguments, recorded results, outcomes, diagnostics and available timing and usage, with `parent_call_id` linking nested calls. Records persist across reconnects and restarts, including results a `codemode` program did not pass back to the model, and are deleted with the session. Live output windows are shown in the event stream rather than stored here. Calls are listed in order of first appearance, ascending by default, and cursors keep the chosen order. Records progress while you paginate; read a call again for its current state. For an `unknown` outcome, confirm the effect with the service that owns it before retrying. **Servers:** [Inherited servers](#scalar-context-global-servers) **Authentication:** [Global authentication](#scalar-context-global-authentication) #### Path parameters - **`session_id` (required)**: `string`, format: `uuid` #### Query parameters - **`limit`**: `integer`, default: `100`, minimum: `1`, maximum: `100` - **`cursor`**: `string` - **`order`**: `string`, possible values: `"ascending", "descending"`, default: `"ascending"` #### Responses ##### 200 A page of tool calls. **Content type:** `application/json` [ToolCallList](/reference/schemas/ToolCallList.md) ##### default Error object. Codes include \`invalid_request\`, \`invalid_webhook_signature\`, \`destination_not_allowed\`, \`files_require_sandbox\`, \`invalid_image\`, \`invalid_media_type\`, \`invalid_filename\` and \`invalid_skill\` (\`400\`); \`unauthorized\` (\`401\`); \`card_verification_required\` (\`402\`); \`not_found\` (\`404\`); \`conversation_busy\`, \`request_conflict\`, \`credential_in_use\`, \`connection_in_use\`, \`invalid_configuration\`, \`session_busy\`, \`session_deleting\` and \`usage_limit_exceeded\` (\`409\`); \`concurrency_limit_exceeded\` (\`429\`); \`body_too_large\`, \`file_too_large\`, \`input_files_too_large\` and \`skill_too_large\` (\`413\`); \`unsupported_media_type\` (\`415\`); \`internal_error\` (\`500\`); and \`session_unavailable\`, \`runtime_unavailable\`, \`files_unavailable\`, \`skills_unavailable\` and \`webhooks_unavailable\` (\`503\`, temporary: retry after a short wait). Branch on \`code\`; \`message\` is a human-readable explanation whose wording can change. **Content type:** `application/json` - **`error` (required)**: `object` - **`code` (required)**: `string` - **`message` (required)**: `string` ### Get a retained tool call and its recorded response - **Method:** `GET` - **Path:** `/sessions/{session_id}/tool-calls/{call_id}` - **Operation ID:** `getToolCall` - **Tags:** Sessions **Servers:** [Inherited servers](#scalar-context-global-servers) **Authentication:** [Global authentication](#scalar-context-global-authentication) #### Path parameters - **`session_id` (required)**: `string`, format: `uuid` - **`call_id` (required)**: `string` #### Responses ##### 200 Tool call, including completion fields when available. **Content type:** `application/json` [ToolCall](/reference/schemas/ToolCall.md) Durable execution record for `codemode` or an inner tool. `call_id` and `parent_call_id` match stream/state IDs and remain stable for the session. `args` are the latest recorded execution arguments, including repairs; `pending` calls expose requested arguments. `done` means execution ended, and `outcome` reports how: `success` and `error` have a recorded result, and `unknown` means the call ended without one, so confirm any external effect with the service that owns it before retrying. Result, diagnostics, duration and usage follow `ToolCompleted`. Nested usage is reported separately from the parent's usage, so add each once. **Example:** ```json { "call_id": "c2", "parent_call_id": "c1", "name": "search", "args": { "query": "streaming" }, "status": "done", "outcome": "success", "result": { "matches": 2 }, "duration_ms": 25, "diagnostics": [] } ``` ##### default Error object. Codes include \`invalid_request\`, \`invalid_webhook_signature\`, \`destination_not_allowed\`, \`files_require_sandbox\`, \`invalid_image\`, \`invalid_media_type\`, \`invalid_filename\` and \`invalid_skill\` (\`400\`); \`unauthorized\` (\`401\`); \`card_verification_required\` (\`402\`); \`not_found\` (\`404\`); \`conversation_busy\`, \`request_conflict\`, \`credential_in_use\`, \`connection_in_use\`, \`invalid_configuration\`, \`session_busy\`, \`session_deleting\` and \`usage_limit_exceeded\` (\`409\`); \`concurrency_limit_exceeded\` (\`429\`); \`body_too_large\`, \`file_too_large\`, \`input_files_too_large\` and \`skill_too_large\` (\`413\`); \`unsupported_media_type\` (\`415\`); \`internal_error\` (\`500\`); and \`session_unavailable\`, \`runtime_unavailable\`, \`files_unavailable\`, \`skills_unavailable\` and \`webhooks_unavailable\` (\`503\`, temporary: retry after a short wait). Branch on \`code\`; \`message\` is a human-readable explanation whose wording can change. **Content type:** `application/json` - **`error` (required)**: `object` - **`code` (required)**: `string` - **`message` (required)**: `string` ### Get the current conversation state - **Method:** `GET` - **Path:** `/sessions/{session_id}/state` - **Operation ID:** `getState` - **Tags:** Sessions **Servers:** [Inherited servers](#scalar-context-global-servers) **Authentication:** [Global authentication](#scalar-context-global-authentication) #### Path parameters - **`session_id` (required)**: `string`, format: `uuid` #### Responses ##### 200 Conversation entries, pending inputs, current work and usage. **Content type:** `application/json` [State](/reference/schemas/State.md) Complete replacement live state used by `GET state` and `snapshot` events. Every snapshot establishes fresh preview and compaction identities. `entries` are the committed entries in the current active conversation context, which can omit earlier history after summarization or a context reset; retrieve complete or missing history through `GET entries`. Partial generation content is only a preview. This state has queued inputs and active submission IDs, not every terminal submission; reconcile tracked submissions using their read endpoints. ##### default Error object. Codes include \`invalid_request\`, \`invalid_webhook_signature\`, \`destination_not_allowed\`, \`files_require_sandbox\`, \`invalid_image\`, \`invalid_media_type\`, \`invalid_filename\` and \`invalid_skill\` (\`400\`); \`unauthorized\` (\`401\`); \`card_verification_required\` (\`402\`); \`not_found\` (\`404\`); \`conversation_busy\`, \`request_conflict\`, \`credential_in_use\`, \`connection_in_use\`, \`invalid_configuration\`, \`session_busy\`, \`session_deleting\` and \`usage_limit_exceeded\` (\`409\`); \`concurrency_limit_exceeded\` (\`429\`); \`body_too_large\`, \`file_too_large\`, \`input_files_too_large\` and \`skill_too_large\` (\`413\`); \`unsupported_media_type\` (\`415\`); \`internal_error\` (\`500\`); and \`session_unavailable\`, \`runtime_unavailable\`, \`files_unavailable\`, \`skills_unavailable\` and \`webhooks_unavailable\` (\`503\`, temporary: retry after a short wait). Branch on \`code\`; \`message\` is a human-readable explanation whose wording can change. **Content type:** `application/json` - **`error` (required)**: `object` - **`code` (required)**: `string` - **`message` (required)**: `string` ### Observe live conversation events - **Method:** `GET` - **Path:** `/sessions/{session_id}/events` - **Operation ID:** `observeEvents` - **Tags:** Sessions Follow a session live. Send `Accept: text/event-stream`. Each SSE frame has an event name in `event` and a JSON payload in `data`; `x-event-schemas` maps each event name to its data schema, and heartbeats are SSE comments. A connection follows submissions while the session is active or idle, and closes when the session enters standby or is archived. A stream opened in standby or after archival returns its snapshot and then closes without waking the session. Submit new work, then open or reconnect the stream for its current snapshot. Work continues when a stream disconnects. **Snapshots.** The first event is a `snapshot` of the complete live state (`State`), taken atomically with registration for later changes. Every later `snapshot` also replaces all live state, including previews and tool activity; a consumer that falls behind the stream's buffer receives a fresh snapshot to catch up, in place of the events it supersedes, including `submission.updated`. After any later snapshot, read the submissions you track for their outcomes. Snapshots take the place of event replay, so frames carry no `id`. To reconnect, open a new stream, read `GET entries` for history committed meanwhile, and read tracked submissions for their outcomes. Events are ordered on each connection, and progress updates can be coalesced rather than sent per token. **Messages.** `message.started` establishes a preview identified by `preview_id`, `message.delta` changes it and `message.replaced` replaces it entirely; apply replacements rather than concatenating updates. Content indexes address the public `content` array, including thinking blocks: a `content` insertion starts a block, and `text` or `thinking` deltas append to it. `message.completed` delivers the committed message with its durable `entry_id`, and a `preview_id` when it matches a preview; replace that preview, and use `entry_id` to reconcile the entry across snapshots, history pages and completion events. A preview ID is valid within its snapshot. A completed message can be a tool call or an intermediate answer; `submission.updated` and submission reads report whether input was answered, and `execution.ended` marks the end of a stretch of work. **Tools.** `call_id` identifies a tool operation and `parent_call_id` links a call made inside `codemode` to it. Both are opaque and stable across history and reconnects. Committed `toolCall.id` and `toolResult.tool_call_id` use the same IDs, and `entry_id` links to the committed tool-result entry when available. Tool-call IDs inside an assistant preview belong to that preview and are replaced by durable IDs at commitment. Tool output is a live window of recent output; `GET tool-calls` keeps the complete recorded results. An `unknown` outcome means the call ended without a recorded result, so confirm its effect before retrying. | Event | Data schema | Meaning | | -------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------ | | `snapshot` | `State` | Replace all live state and preview identities. | | `submission.updated` | `Submission` | Current durable input outcome. | | `execution.started`, `execution.ended` | `ExecutionEvent` | Work began or ended for the listed submissions. | | `message.started` | `MessageStarted` | Establish an assistant preview. | | `message.delta` | `MessageDelta` | Insert content or append text, thinking or argument strings. | | `message.replaced` | `MessageReplaced` | Replace the entire preview. | | `message.completed` | `MessageCompleted` | Reconcile the authoritative committed entry. | | `tool.started` | `ToolStarted` | A model-facing or nested operation began. | | `tool.updated` | `ToolUpdated` | Update retained output, progress or diagnostics. | | `tool.completed` | `ToolCompleted` | Recorded result or explicitly unknown outcome. | | `retry.started`, `retry.ended` | `Retry`, `RetryEnded` | Retry waiting began or ended. | | `compaction.started`, `compaction.completed` | `CompactionStarted`, `CompactionCompleted` | Context summarization activity and outcome. | | `usage.updated` | `CumulativeUsage` | Replace cumulative recorded usage. | | `inbox.updated` | `InboxUpdated` | Replace the queued-input list. | | `execution.error` | `ExecutionFailed` | A safe execution-failure notification. | Snapshot `entries` hold the active conversation context; `GET entries` holds the complete history, including entries summarized out of the active context. Stored credentials never appear in conversation responses. **Servers:** [Inherited servers](#scalar-context-global-servers) **Authentication:** [Global authentication](#scalar-context-global-authentication) #### Path parameters - **`session_id` (required)**: `string`, format: `uuid` #### Responses ##### 200 A snapshot followed by typed live events until the connection closes. **Content type:** `text/event-stream` `string` **Example:** ```json "event: snapshot\ndata: {\"conversation\":{\"id\":1},\"entries\":[],\"agent\":{},\"inbox\":[],\"execution\":{\"busy\":false,\"inputs\":[],\"tools\":[],\"nested_tools\":[],\"compactions\":[]},\"usage\":{\"models\":[],\"tools\":[]}}\n" ``` ##### default Error object. Codes include \`invalid_request\`, \`invalid_webhook_signature\`, \`destination_not_allowed\`, \`files_require_sandbox\`, \`invalid_image\`, \`invalid_media_type\`, \`invalid_filename\` and \`invalid_skill\` (\`400\`); \`unauthorized\` (\`401\`); \`card_verification_required\` (\`402\`); \`not_found\` (\`404\`); \`conversation_busy\`, \`request_conflict\`, \`credential_in_use\`, \`connection_in_use\`, \`invalid_configuration\`, \`session_busy\`, \`session_deleting\` and \`usage_limit_exceeded\` (\`409\`); \`concurrency_limit_exceeded\` (\`429\`); \`body_too_large\`, \`file_too_large\`, \`input_files_too_large\` and \`skill_too_large\` (\`413\`); \`unsupported_media_type\` (\`415\`); \`internal_error\` (\`500\`); and \`session_unavailable\`, \`runtime_unavailable\`, \`files_unavailable\`, \`skills_unavailable\` and \`webhooks_unavailable\` (\`503\`, temporary: retry after a short wait). Branch on \`code\`; \`message\` is a human-readable explanation whose wording can change. **Content type:** `application/json` - **`error` (required)**: `object` - **`code` (required)**: `string` - **`message` (required)**: `string` ### List published output artifacts - **Method:** `GET` - **Path:** `/sessions/{session_id}/artifacts` - **Operation ID:** `listSessionArtifacts` - **Tags:** Files Lists completed publications newest first. Retain file IDs before deleting a session; published files remain independently downloadable and deletable. **Servers:** [Inherited servers](#scalar-context-global-servers) **Authentication:** [Global authentication](#scalar-context-global-authentication) #### Path parameters - **`session_id` (required)**: `string`, format: `uuid` #### Query parameters - **`limit`**: `integer`, default: `100`, minimum: `1`, maximum: `100` - **`cursor`**: `string` #### Responses ##### 200 A page of immutable published files and provenance. **Content type:** `application/json` [ArtifactList](/reference/schemas/ArtifactList.md) ##### default Error object. Codes include \`invalid_request\`, \`invalid_webhook_signature\`, \`destination_not_allowed\`, \`files_require_sandbox\`, \`invalid_image\`, \`invalid_media_type\`, \`invalid_filename\` and \`invalid_skill\` (\`400\`); \`unauthorized\` (\`401\`); \`card_verification_required\` (\`402\`); \`not_found\` (\`404\`); \`conversation_busy\`, \`request_conflict\`, \`credential_in_use\`, \`connection_in_use\`, \`invalid_configuration\`, \`session_busy\`, \`session_deleting\` and \`usage_limit_exceeded\` (\`409\`); \`concurrency_limit_exceeded\` (\`429\`); \`body_too_large\`, \`file_too_large\`, \`input_files_too_large\` and \`skill_too_large\` (\`413\`); \`unsupported_media_type\` (\`415\`); \`internal_error\` (\`500\`); and \`session_unavailable\`, \`runtime_unavailable\`, \`files_unavailable\`, \`skills_unavailable\` and \`webhooks_unavailable\` (\`503\`, temporary: retry after a short wait). Branch on \`code\`; \`message\` is a human-readable explanation whose wording can change. **Content type:** `application/json` - **`error` (required)**: `object` - **`code` (required)**: `string` - **`message` (required)**: `string` ### List webhook registrations - **Method:** `GET` - **Path:** `/webhooks` - **Operation ID:** `listWebhooks` - **Tags:** Webhooks **Servers:** [Inherited servers](#scalar-context-global-servers) **Authentication:** [Global authentication](#scalar-context-global-authentication) #### Query parameters - **`limit`**: `integer`, default: `100`, minimum: `1`, maximum: `100` - **`cursor`**: `string` #### Responses ##### 200 Registrations newest first, without signing secrets. **Content type:** `application/json` [WebhookList](/reference/schemas/WebhookList.md) ##### default Error object. Codes include \`invalid_request\`, \`invalid_webhook_signature\`, \`destination_not_allowed\`, \`files_require_sandbox\`, \`invalid_image\`, \`invalid_media_type\`, \`invalid_filename\` and \`invalid_skill\` (\`400\`); \`unauthorized\` (\`401\`); \`card_verification_required\` (\`402\`); \`not_found\` (\`404\`); \`conversation_busy\`, \`request_conflict\`, \`credential_in_use\`, \`connection_in_use\`, \`invalid_configuration\`, \`session_busy\`, \`session_deleting\` and \`usage_limit_exceeded\` (\`409\`); \`concurrency_limit_exceeded\` (\`429\`); \`body_too_large\`, \`file_too_large\`, \`input_files_too_large\` and \`skill_too_large\` (\`413\`); \`unsupported_media_type\` (\`415\`); \`internal_error\` (\`500\`); and \`session_unavailable\`, \`runtime_unavailable\`, \`files_unavailable\`, \`skills_unavailable\` and \`webhooks_unavailable\` (\`503\`, temporary: retry after a short wait). Branch on \`code\`; \`message\` is a human-readable explanation whose wording can change. **Content type:** `application/json` - **`error` (required)**: `object` - **`code` (required)**: `string` - **`message` (required)**: `string` ### Register a webhook endpoint - **Method:** `POST` - **Path:** `/webhooks` - **Operation ID:** `createWebhook` - **Tags:** Webhooks **Servers:** [Inherited servers](#scalar-context-global-servers) **Authentication:** [Global authentication](#scalar-context-global-authentication) #### Request body **Required:** `true` **Content type:** `application/json` no additional properties - **`events` (required)**: `array`, minItems: `1`, maxItems: `2`, uniqueItems: `true` **Items:** `string`, possible values: `"submission.updated", "artifact.created"` - **`url` (required)**: `string`, format: `uri`, maxLength: `2048` Public HTTPS URL without credentials or a fragment. #### Responses ##### 201 Registration with its one-time signing secret. Save it to verify requests. **Content type:** `application/json` [CreatedWebhook](/reference/schemas/CreatedWebhook.md) ##### default Error object. Codes include \`invalid_request\`, \`invalid_webhook_signature\`, \`destination_not_allowed\`, \`files_require_sandbox\`, \`invalid_image\`, \`invalid_media_type\`, \`invalid_filename\` and \`invalid_skill\` (\`400\`); \`unauthorized\` (\`401\`); \`card_verification_required\` (\`402\`); \`not_found\` (\`404\`); \`conversation_busy\`, \`request_conflict\`, \`credential_in_use\`, \`connection_in_use\`, \`invalid_configuration\`, \`session_busy\`, \`session_deleting\` and \`usage_limit_exceeded\` (\`409\`); \`concurrency_limit_exceeded\` (\`429\`); \`body_too_large\`, \`file_too_large\`, \`input_files_too_large\` and \`skill_too_large\` (\`413\`); \`unsupported_media_type\` (\`415\`); \`internal_error\` (\`500\`); and \`session_unavailable\`, \`runtime_unavailable\`, \`files_unavailable\`, \`skills_unavailable\` and \`webhooks_unavailable\` (\`503\`, temporary: retry after a short wait). Branch on \`code\`; \`message\` is a human-readable explanation whose wording can change. **Content type:** `application/json` - **`error` (required)**: `object` - **`code` (required)**: `string` - **`message` (required)**: `string` ### Delete a registration and its delivery history - **Method:** `DELETE` - **Path:** `/webhooks/{webhook_id}` - **Operation ID:** `deleteWebhook` - **Tags:** Webhooks Cancels pending deliveries. A request already in flight may still arrive. **Servers:** [Inherited servers](#scalar-context-global-servers) **Authentication:** [Global authentication](#scalar-context-global-authentication) #### Path parameters - **`webhook_id` (required)**: `string`, format: `uuid` #### Responses ##### 204 Registration deleted. ##### default Error object. Codes include \`invalid_request\`, \`invalid_webhook_signature\`, \`destination_not_allowed\`, \`files_require_sandbox\`, \`invalid_image\`, \`invalid_media_type\`, \`invalid_filename\` and \`invalid_skill\` (\`400\`); \`unauthorized\` (\`401\`); \`card_verification_required\` (\`402\`); \`not_found\` (\`404\`); \`conversation_busy\`, \`request_conflict\`, \`credential_in_use\`, \`connection_in_use\`, \`invalid_configuration\`, \`session_busy\`, \`session_deleting\` and \`usage_limit_exceeded\` (\`409\`); \`concurrency_limit_exceeded\` (\`429\`); \`body_too_large\`, \`file_too_large\`, \`input_files_too_large\` and \`skill_too_large\` (\`413\`); \`unsupported_media_type\` (\`415\`); \`internal_error\` (\`500\`); and \`session_unavailable\`, \`runtime_unavailable\`, \`files_unavailable\`, \`skills_unavailable\` and \`webhooks_unavailable\` (\`503\`, temporary: retry after a short wait). Branch on \`code\`; \`message\` is a human-readable explanation whose wording can change. **Content type:** `application/json` - **`error` (required)**: `object` - **`code` (required)**: `string` - **`message` (required)**: `string` ### Inspect webhook deliveries - **Method:** `GET` - **Path:** `/webhooks/{webhook_id}/deliveries` - **Operation ID:** `listWebhookDeliveries` - **Tags:** Webhooks Lists deliveries newest first. Attempts count requests claimed for sending, including attempts interrupted before acknowledgement. **Servers:** [Inherited servers](#scalar-context-global-servers) **Authentication:** [Global authentication](#scalar-context-global-authentication) #### Path parameters - **`webhook_id` (required)**: `string`, format: `uuid` #### Query parameters - **`limit`**: `integer`, default: `100`, minimum: `1`, maximum: `100` - **`cursor`**: `string` #### Responses ##### 200 A page of delivery outcomes and retry times. **Content type:** `application/json` [WebhookDeliveryList](/reference/schemas/WebhookDeliveryList.md) ##### default Error object. Codes include \`invalid_request\`, \`invalid_webhook_signature\`, \`destination_not_allowed\`, \`files_require_sandbox\`, \`invalid_image\`, \`invalid_media_type\`, \`invalid_filename\` and \`invalid_skill\` (\`400\`); \`unauthorized\` (\`401\`); \`card_verification_required\` (\`402\`); \`not_found\` (\`404\`); \`conversation_busy\`, \`request_conflict\`, \`credential_in_use\`, \`connection_in_use\`, \`invalid_configuration\`, \`session_busy\`, \`session_deleting\` and \`usage_limit_exceeded\` (\`409\`); \`concurrency_limit_exceeded\` (\`429\`); \`body_too_large\`, \`file_too_large\`, \`input_files_too_large\` and \`skill_too_large\` (\`413\`); \`unsupported_media_type\` (\`415\`); \`internal_error\` (\`500\`); and \`session_unavailable\`, \`runtime_unavailable\`, \`files_unavailable\`, \`skills_unavailable\` and \`webhooks_unavailable\` (\`503\`, temporary: retry after a short wait). Branch on \`code\`; \`message\` is a human-readable explanation whose wording can change. **Content type:** `application/json` - **`error` (required)**: `object` - **`code` (required)**: `string` - **`message` (required)**: `string` ### Store a downloadable file - **Method:** `POST` - **Path:** `/files` - **Operation ID:** `uploadFile` - **Tags:** Files Files are at most 16 MiB (`413 file_too_large`). Uploading beyond the tenant's available storage returns `409 usage_limit_exceeded`. The stored content type is the request `Content-Type`, or `application/octet-stream` when it is omitted. **Servers:** [Inherited servers](#scalar-context-global-servers) **Authentication:** [Global authentication](#scalar-context-global-authentication) #### Header parameters - **`X-Filename` (required)**: `string`, minLength: `1`, maxLength: `255` HTTP header values are Latin-1; percent-encoded or non-ASCII names are stored as received. **Not:** `any`, pattern: `[\r\n\u0000]` #### Request body **Required:** `true` **Content type:** `application/octet-stream` `string` **Content type:** `*/*` `string` #### Responses ##### 201 File metadata. The original content type is retained. **Content type:** `application/json` [File](/reference/schemas/File.md) ##### default Error object. Codes include \`invalid_request\`, \`invalid_webhook_signature\`, \`destination_not_allowed\`, \`files_require_sandbox\`, \`invalid_image\`, \`invalid_media_type\`, \`invalid_filename\` and \`invalid_skill\` (\`400\`); \`unauthorized\` (\`401\`); \`card_verification_required\` (\`402\`); \`not_found\` (\`404\`); \`conversation_busy\`, \`request_conflict\`, \`credential_in_use\`, \`connection_in_use\`, \`invalid_configuration\`, \`session_busy\`, \`session_deleting\` and \`usage_limit_exceeded\` (\`409\`); \`concurrency_limit_exceeded\` (\`429\`); \`body_too_large\`, \`file_too_large\`, \`input_files_too_large\` and \`skill_too_large\` (\`413\`); \`unsupported_media_type\` (\`415\`); \`internal_error\` (\`500\`); and \`session_unavailable\`, \`runtime_unavailable\`, \`files_unavailable\`, \`skills_unavailable\` and \`webhooks_unavailable\` (\`503\`, temporary: retry after a short wait). Branch on \`code\`; \`message\` is a human-readable explanation whose wording can change. **Content type:** `application/json` - **`error` (required)**: `object` - **`code` (required)**: `string` - **`message` (required)**: `string` ### Download original file bytes - **Method:** `GET` - **Path:** `/files/{file_id}` - **Operation ID:** `downloadFile` - **Tags:** Files **Servers:** [Inherited servers](#scalar-context-global-servers) **Authentication:** [Global authentication](#scalar-context-global-authentication) #### Path parameters - **`file_id` (required)**: `string`, format: `uuid` #### Responses ##### 200 Original bytes with stored content type and attachment disposition. **Content type:** `*/*` `string` ##### default Error object. Codes include \`invalid_request\`, \`invalid_webhook_signature\`, \`destination_not_allowed\`, \`files_require_sandbox\`, \`invalid_image\`, \`invalid_media_type\`, \`invalid_filename\` and \`invalid_skill\` (\`400\`); \`unauthorized\` (\`401\`); \`card_verification_required\` (\`402\`); \`not_found\` (\`404\`); \`conversation_busy\`, \`request_conflict\`, \`credential_in_use\`, \`connection_in_use\`, \`invalid_configuration\`, \`session_busy\`, \`session_deleting\` and \`usage_limit_exceeded\` (\`409\`); \`concurrency_limit_exceeded\` (\`429\`); \`body_too_large\`, \`file_too_large\`, \`input_files_too_large\` and \`skill_too_large\` (\`413\`); \`unsupported_media_type\` (\`415\`); \`internal_error\` (\`500\`); and \`session_unavailable\`, \`runtime_unavailable\`, \`files_unavailable\`, \`skills_unavailable\` and \`webhooks_unavailable\` (\`503\`, temporary: retry after a short wait). Branch on \`code\`; \`message\` is a human-readable explanation whose wording can change. **Content type:** `application/json` - **`error` (required)**: `object` - **`code` (required)**: `string` - **`message` (required)**: `string` ### Delete a stored file - **Method:** `DELETE` - **Path:** `/files/{file_id}` - **Operation ID:** `deleteFile` - **Tags:** Files **Servers:** [Inherited servers](#scalar-context-global-servers) **Authentication:** [Global authentication](#scalar-context-global-authentication) #### Path parameters - **`file_id` (required)**: `string`, format: `uuid` #### Responses ##### 204 File deleted. ##### default Error object. Codes include \`invalid_request\`, \`invalid_webhook_signature\`, \`destination_not_allowed\`, \`files_require_sandbox\`, \`invalid_image\`, \`invalid_media_type\`, \`invalid_filename\` and \`invalid_skill\` (\`400\`); \`unauthorized\` (\`401\`); \`card_verification_required\` (\`402\`); \`not_found\` (\`404\`); \`conversation_busy\`, \`request_conflict\`, \`credential_in_use\`, \`connection_in_use\`, \`invalid_configuration\`, \`session_busy\`, \`session_deleting\` and \`usage_limit_exceeded\` (\`409\`); \`concurrency_limit_exceeded\` (\`429\`); \`body_too_large\`, \`file_too_large\`, \`input_files_too_large\` and \`skill_too_large\` (\`413\`); \`unsupported_media_type\` (\`415\`); \`internal_error\` (\`500\`); and \`session_unavailable\`, \`runtime_unavailable\`, \`files_unavailable\`, \`skills_unavailable\` and \`webhooks_unavailable\` (\`503\`, temporary: retry after a short wait). Branch on \`code\`; \`message\` is a human-readable explanation whose wording can change. **Content type:** `application/json` - **`error` (required)**: `object` - **`code` (required)**: `string` - **`message` (required)**: `string` ## Schemas ### ApiKeyList **Type:** `object` - **`data` (required)**: array of [ApiKey](/reference/schemas/ApiKey.md) - **`next_cursor` (required)**: `string | null` ### CredentialList **Type:** `object` - **`data` (required)**: array of [Credential](/reference/schemas/Credential.md) - **`next_cursor` (required)**: `string | null` ### ConnectionList **Type:** `object` - **`data` (required)**: array of [Connection](/reference/schemas/Connection.md) - **`next_cursor` (required)**: `string | null` ### AgentList **Type:** `object` - **`data` (required)**: array of [Agent](/reference/schemas/Agent.md) - **`next_cursor` (required)**: `string | null` ### AgentVersionList **Type:** `object` - **`data` (required)**: array of [AgentVersion](/reference/schemas/AgentVersion.md) - **`next_cursor` (required)**: `string | null` ### SessionList **Type:** `object` - **`data` (required)**: array of [Session](/reference/schemas/Session.md) - **`next_cursor` (required)**: `string | null` ### SubmissionList **Type:** `object` - **`data` (required)**: array of [Submission](/reference/schemas/Submission.md) - **`next_cursor` (required)**: `string | null` ### EntryList **Type:** `object` - **`data` (required)**: array of [Entry](/reference/schemas/Entry.md) - **`next_cursor` (required)**: `string | null` ### ApiKey **Type:** `object` - **`created_at` (required)**: `string`, format: `date-time` - **`id` (required)**: `string`, format: `uuid` - **`name` (required)**: `string` - **`prefix` (required)**: `string` - **`suffix` (required)**: `string` ### CreatedApiKey **Type:** `object` - **`created_at` (required)**: `string`, format: `date-time` - **`id` (required)**: `string`, format: `uuid` - **`name` (required)**: `string` - **`prefix` (required)**: `string` - **`secret` (required)**: `string` Returned only on creation. - **`suffix` (required)**: `string` ### ProviderApiKey **Type:** `string`, minLength: `1`, maxLength: `10000`, pattern: `\S`, writeOnly Provider API key; encrypted at rest and write-only. Authentication is checked when the key is used. A selected customer key is always the one used. **Not:** `string`, pattern: `[\r\n]` ### CreateCredential Store a provider secret. `category` and `provider` determine the accepted `settings`; secrets are write-only. **One of:** discriminated by `category` - [CreateModelCredential](/reference/schemas/CreateModelCredential.md), category: `model` - [CreateSandboxCredential](/reference/schemas/CreateSandboxCredential.md), category: `sandbox` - [CreateWebSearchCredential](/reference/schemas/CreateWebSearchCredential.md), category: `web_search` - [CreateBrowserCredential](/reference/schemas/CreateBrowserCredential.md), category: `browser` ### Credential Provider credential metadata. API keys are write-only. **One of:** discriminated by `category` - [ModelCredential](/reference/schemas/ModelCredential.md), category: `model` - [SandboxCredential](/reference/schemas/SandboxCredential.md), category: `sandbox` - [WebSearchCredential](/reference/schemas/WebSearchCredential.md), category: `web_search` - [BrowserCredential](/reference/schemas/BrowserCredential.md), category: `browser` ### CreateModelCredential **Type:** `object`, no additional properties - **`api_key` (required)**: [ProviderApiKey](/reference/schemas/ProviderApiKey.md) Provider API key; encrypted at rest and write-only. Authentication is checked when the key is used. A selected customer key is always the one used. - **`category` (required)**: `string`, const: `"model"` - **`name` (required)**: `string`, minLength: `1`, maxLength: `200`, pattern: `\S` - **`provider` (required)**: `string`, minLength: `1`, maxLength: `100`, pattern: `\S` Provider identifier from `GET /models`. The provider/model pair is validated when creating an agent version or session. - **`settings`**: `object`, no additional properties **Example:** ```json { "name": "My anthropic account", "category": "model", "provider": "anthropic", "settings": {}, "api_key": "your-provider-api-key" } ``` ### ModelCredential **Type:** `object`, no additional properties - **`category` (required)**: `string`, const: `"model"` - **`created_at` (required)**: `string`, format: `date-time` - **`id` (required)**: `string`, format: `uuid` - **`name` (required)**: `string`, minLength: `1`, maxLength: `200`, pattern: `\S` - **`provider` (required)**: `string`, minLength: `1`, maxLength: `100`, pattern: `\S` Provider identifier from `GET /models`. The provider/model pair is validated when creating an agent version or session. - **`settings` (required)**: `object`, no additional properties ### CreateSandboxCredential **Type:** `object`, no additional properties **One of:** - `object` - **`provider`**: `string`, const: `"daytona"` - **`settings`**: `object`, no additional properties - `object` - **`settings` (required)**: `object`, no additional properties - **`workspace` (required)**: `string`, minLength: `1`, maxLength: `200`, pattern: `\S` - **`provider`**: `string`, const: `"blaxel"` * **`api_key` (required)**: [ProviderApiKey](/reference/schemas/ProviderApiKey.md) Provider API key; encrypted at rest and write-only. Authentication is checked when the key is used. A selected customer key is always the one used. * **`category` (required)**: `string`, const: `"sandbox"` * **`name` (required)**: `string`, minLength: `1`, maxLength: `200`, pattern: `\S` * **`provider` (required)**: `string`, possible values: `"daytona", "blaxel"` * **`settings`**: `object` **Example:** ```json { "name": "My blaxel account", "category": "sandbox", "provider": "blaxel", "settings": { "workspace": "your-workspace" }, "api_key": "your-provider-api-key" } ``` ### SandboxCredential **Type:** `object`, no additional properties **One of:** - `object` - **`provider`**: `string`, const: `"daytona"` - **`settings`**: `object`, no additional properties - `object` - **`settings` (required)**: `object`, no additional properties - **`workspace` (required)**: `string`, minLength: `1`, maxLength: `200`, pattern: `\S` - **`provider`**: `string`, const: `"blaxel"` * **`category` (required)**: `string`, const: `"sandbox"` * **`created_at` (required)**: `string`, format: `date-time` * **`id` (required)**: `string`, format: `uuid` * **`name` (required)**: `string`, minLength: `1`, maxLength: `200`, pattern: `\S` * **`provider` (required)**: `string`, possible values: `"daytona", "blaxel"` * **`settings` (required)**: `object` ### CreateWebSearchCredential **Type:** `object`, no additional properties - **`api_key` (required)**: [ProviderApiKey](/reference/schemas/ProviderApiKey.md) Provider API key; encrypted at rest and write-only. Authentication is checked when the key is used. A selected customer key is always the one used. - **`category` (required)**: `string`, const: `"web_search"` - **`name` (required)**: `string`, minLength: `1`, maxLength: `200`, pattern: `\S` - **`provider` (required)**: `string`, const: `"exa"` - **`settings`**: `object`, no additional properties **Example:** ```json { "name": "My exa account", "category": "web_search", "provider": "exa", "settings": {}, "api_key": "your-provider-api-key" } ``` ### WebSearchCredential **Type:** `object`, no additional properties - **`category` (required)**: `string`, const: `"web_search"` - **`created_at` (required)**: `string`, format: `date-time` - **`id` (required)**: `string`, format: `uuid` - **`name` (required)**: `string`, minLength: `1`, maxLength: `200`, pattern: `\S` - **`provider` (required)**: `string`, const: `"exa"` - **`settings` (required)**: `object`, no additional properties ### CreateBrowserCredential **Type:** `object`, no additional properties - **`api_key` (required)**: [ProviderApiKey](/reference/schemas/ProviderApiKey.md) Provider API key; encrypted at rest and write-only. Authentication is checked when the key is used. A selected customer key is always the one used. - **`category` (required)**: `string`, const: `"browser"` - **`name` (required)**: `string`, minLength: `1`, maxLength: `200`, pattern: `\S` - **`provider` (required)**: `string`, const: `"browserbase"` - **`settings`**: `object`, no additional properties - **`project_id`**: `string`, minLength: `1`, maxLength: `200`, pattern: `\S` **Example:** ```json { "name": "My browserbase account", "category": "browser", "provider": "browserbase", "settings": { "project_id": "your-project-id" }, "api_key": "your-provider-api-key" } ``` ### BrowserCredential **Type:** `object`, no additional properties - **`category` (required)**: `string`, const: `"browser"` - **`created_at` (required)**: `string`, format: `date-time` - **`id` (required)**: `string`, format: `uuid` - **`name` (required)**: `string`, minLength: `1`, maxLength: `200`, pattern: `\S` - **`provider` (required)**: `string`, const: `"browserbase"` - **`settings` (required)**: `object`, no additional properties - **`project_id`**: `string`, minLength: `1`, maxLength: `200`, pattern: `\S` ### ToolEndpointCredentials **Type:** `object`, writeOnly, no additional properties Endpoint authentication; encrypted at rest and never returned. Omit for unauthenticated endpoints, or supply `headers` and an optional `api_key` sent as a `Bearer` `Authorization` header. Keys and header values must not contain carriage returns or newlines. Authentication is checked when the endpoint is used. - **`api_key`**: [ProviderApiKey](/reference/schemas/ProviderApiKey.md) Provider API key; encrypted at rest and write-only. Authentication is checked when the key is used. A selected customer key is always the one used. - **`headers`**: `object` **Additional properties:** **Not:** `string`, pattern: `[\r\n]` `string` ### CreateConnection **Type:** `object`, no additional properties - **`name` (required)**: `string`, minLength: `1`, maxLength: `200`, pattern: `\S` - **`type` (required)**: `string`, possible values: `"mcp", "http"` - **`url` (required)**: `string`, format: `uri`, minLength: `1`, maxLength: `2048` Absolute HTTPS endpoint URL without embedded credentials. - **`credentials`**: [ToolEndpointCredentials](/reference/schemas/ToolEndpointCredentials.md) Endpoint authentication; encrypted at rest and never returned. Omit for unauthenticated endpoints, or supply `headers` and an optional `api_key` sent as a `Bearer` `Authorization` header. Keys and header values must not contain carriage returns or newlines. Authentication is checked when the endpoint is used. **Example:** ```json { "name": "My tools", "type": "mcp", "url": "https://tools.example.com/mcp", "credentials": { "api_key": "your-tool-endpoint-token" } } ``` ### Connection **Type:** `object`, no additional properties - **`created_at` (required)**: `string`, format: `date-time` - **`id` (required)**: `string`, format: `uuid` - **`name` (required)**: `string`, minLength: `1`, maxLength: `200`, pattern: `\S` - **`type` (required)**: `string`, possible values: `"mcp", "http"` - **`url` (required)**: `string`, format: `uri`, minLength: `1`, maxLength: `2048` Absolute HTTPS endpoint URL without embedded credentials. ### SkillVersionSelector **Type:** `string`, pattern: `^(latest|[1-9][0-9]*)$` A concrete positive version number encoded as a string, or latest. Getters always identify a concrete version. ### SkillAttachment **Type:** `object`, no additional properties - **`skill_id` (required)**: `string`, format: `uuid` - **`version` (required)**: `string`, pattern: `^(latest|[1-9][0-9]*)$` A concrete positive version number encoded as a string, or latest. Getters always identify a concrete version. ### Skill **Type:** `object`, no additional properties - **`created_at` (required)**: `string`, format: `date-time` - **`description` (required)**: `string`, minLength: `1`, maxLength: `1024`, pattern: `\S` Description from the latest version. XML-like text is allowed. - **`id` (required)**: `string`, format: `uuid` - **`latest_version` (required)**: `string`, pattern: `^[1-9][0-9]*$` - **`name` (required)**: `string`, minLength: `1`, maxLength: `64`, pattern: `^[a-z0-9]+(-[a-z0-9]+)*$` ### SkillManifestFile **Type:** `object`, no additional properties - **`mime_type` (required)**: `string` - **`path` (required)**: `string`, minLength: `1`, maxLength: `4096` Exact relative path of a regular uploaded file. Absolute paths, empty or dot segments, backslashes and NULs are rejected. - **`sha256` (required)**: `string`, pattern: `^[a-f0-9]{64}$` - **`size` (required)**: `integer`, minimum: `0`, maximum: `30000000` ### SkillVersion **Type:** `object`, no additional properties - **`created_at` (required)**: `string`, format: `date-time` - **`description` (required)**: `string`, minLength: `1`, maxLength: `1024`, pattern: `\S` - **`files` (required)**: array of [SkillManifestFile](/reference/schemas/SkillManifestFile.md), minItems: `1`, maxItems: `1000` - **`name` (required)**: `string`, minLength: `1`, maxLength: `64`, pattern: `^[a-z0-9]+(-[a-z0-9]+)*$` - **`sha256` (required)**: `string`, pattern: `^[a-f0-9]{64}$` Content hash of the complete version. - **`size` (required)**: `integer`, minimum: `1`, maximum: `30000000` Sum of all decoded uncompressed file contents in bytes. - **`skill_id` (required)**: `string`, format: `uuid` - **`version` (required)**: `string`, pattern: `^[1-9][0-9]*$` ### SkillVersionContents **Type:** `object`, no additional properties - **`created_at` (required)**: `string`, format: `date-time` - **`description` (required)**: `string`, minLength: `1`, maxLength: `1024`, pattern: `\S` - **`files` (required)**: `array`, minItems: `1`, maxItems: `1000` **Items:** no additional properties - **`content` (required)**: `string` Exact original file bytes encoded as base64. - **`encoding` (required)**: `string`, const: `"base64"` - **`mime_type` (required)**: `string` - **`path` (required)**: `string`, minLength: `1`, maxLength: `4096` - **`sha256` (required)**: `string`, pattern: `^[a-f0-9]{64}$` - **`size` (required)**: `integer`, minimum: `0`, maximum: `30000000` - **`name` (required)**: `string`, minLength: `1`, maxLength: `64`, pattern: `^[a-z0-9]+(-[a-z0-9]+)*$` - **`sha256` (required)**: `string`, pattern: `^[a-f0-9]{64}$` - **`size` (required)**: `integer`, minimum: `1`, maximum: `30000000` - **`skill_id` (required)**: `string`, format: `uuid` - **`version` (required)**: `string`, pattern: `^[1-9][0-9]*$` ### SkillList **Type:** `object`, no additional properties - **`data` (required)**: array of [Skill](/reference/schemas/Skill.md) - **`next_cursor` (required)**: `string | null` ### SkillVersionList **Type:** `object`, no additional properties - **`data` (required)**: array of [SkillVersion](/reference/schemas/SkillVersion.md) - **`next_cursor` (required)**: `string | null` ### AgentConfig **Type:** `object`, no additional properties - **`model` (required)**: [AgentModel](/reference/schemas/AgentModel.md) - **`tools` (required)**: array of [ToolGrant](/reference/schemas/ToolGrant.md), maxItems: `100` Explicit grants available inside `codemode`. Tool names must be unique. A single browser grant enables the browser API with platform-provided credentials or a customer Browserbase credential. HTTP tools cannot use `codemode`, `read_skill`, `browser_client`, `browser_command`, or the reserved `mcp_` and `sandbox_` prefixes. - **`instructions`**: `string`, maxLength: `100000` - **`sandbox`**: [Sandbox](/reference/schemas/Sandbox.md) One sandbox per session, bound for its lifetime when a tool first needs it. Sandboxes Clyck creates belong to the session and are deleted when it is archived or deleted. An existing `sandbox_id` attaches your own sandbox, which stays yours. If the bound sandbox becomes unavailable, sandbox tools return errors; start a new session for a fresh sandbox. - **`skills`**: array of [SkillAttachment](/reference/schemas/SkillAttachment.md) Attached skill versions, at most one per skill ID. Omission means no skills. latest resolves when creating this agent version; returned configurations contain concrete versions. Attached skills automatically enable read_skill without a sandbox or separate tool grant. - **`thinking_level`**: `string`, possible values: `"off", "minimal", "low", "medium", "high", "xhigh", "max"`, default: `"off"` Reasoning level for this agent version. Configure it on the agent rather than individual submissions. **Example:** ```json { "model": { "provider": "anthropic", "id": "claude-sonnet-5-5", "credential_id": "10000000-0000-4000-8000-000000000001" }, "instructions": "Answer the user's questions.", "tools": [ { "type": "platform", "name": "web_search" }, { "type": "platform", "name": "browser" } ] } ``` ### AgentModel **Type:** `object`, no additional properties - **`credential_id` (required)**: `string`, format: `uuid` A model API key whose provider matches the selected provider. - **`id` (required)**: `string`, minLength: `1`, maxLength: `300` - **`provider` (required)**: `string`, minLength: `1`, maxLength: `100` ### Sandbox One sandbox per session, bound for its lifetime when a tool first needs it. Sandboxes Clyck creates belong to the session and are deleted when it is archived or deleted. An existing `sandbox_id` attaches your own sandbox, which stays yours. If the bound sandbox becomes unavailable, sandbox tools return errors; start a new session for a fresh sandbox. **One of:** - **One of:** - **Not:** `object` **Required fields:** `sandbox_id` `object` **Required fields:** `snapshot` - **Not:** `object` **Required fields:** `snapshot` `object` **Required fields:** `sandbox_id` `object`, no additional properties - **`credential_id` (required)**: `string`, format: `uuid` Customer Daytona credential. - **`provider` (required)**: `string`, const: `"daytona"` - **`sandbox_id`**: `string`, minLength: `1`, maxLength: `500` Existing sandbox accessible with the selected credential. It must be running before tools can execute. Clyck waits for startup already in progress, but does not start stopped sandboxes or resume paused or archived ones; start or resume the sandbox in Daytona before using it. Missing, stopped, paused or archived sandboxes cause tool errors. Computer use requires Daytona's desktop software to be installed; Clyck starts its desktop services automatically. - **`snapshot`**: `string`, minLength: `1`, maxLength: `500` Snapshot used to create the sandbox. Required unless attaching `sandbox_id`. It must be available to the selected credential's account in the `target` region. A snapshot existing in Daytona does not guarantee availability in that region. Computer use requires a snapshot containing Daytona's required desktop software; Clyck starts its desktop services automatically. - **`target`**: `string`, default: `"us"`, minLength: `1`, maxLength: `500` Creation region. The selected snapshot must be available in this region. Ignored when attaching an existing sandbox with `sandbox_id`. - `object`, no additional properties Clyck-managed sandboxes use 2048 MiB of memory and a Clyck-selected image and region. Only the working directory may be customized. No customer credentials are needed. - **`provider` (required)**: `string`, const: `"clyck-managed"` - **`cwd`**: `string`, default: `"/workspace"`, maxLength: `500`, pattern: `^/` Absolute working directory for filesystem and shell tools. - `object`, no additional properties A sandbox in your own Blaxel workspace, using your stored Blaxel API key. - **`credential_id` (required)**: `string`, format: `uuid` Customer Blaxel credential. - **`provider` (required)**: `string`, const: `"blaxel"` - **`cwd`**: `string`, default: `"/workspace"`, maxLength: `500`, pattern: `^/` Absolute working directory for filesystem and shell tools. - **`image`**: `string`, minLength: `1`, maxLength: `500` Image for a new sandbox; omitted uses the Clyck default sandbox image. - **`memory`**: `integer`, minimum: `1` Memory in MiB for a new sandbox; omitted uses 2048 MiB. - **`region`**: `string`, minLength: `1`, maxLength: `500` Region for a new sandbox; omitted uses the platform default. - **`sandbox_id`**: `string`, minLength: `1`, maxLength: `500` Existing sandbox in the credential's workspace. ### ToolGrant **One of:** - `object`, no additional properties - **`name` (required)**: `string`, const: `"publish_file"` Publish a regular file from a Clyck-managed sandbox. - **`type` (required)**: `string`, const: `"platform"` - `object`, no additional properties - **`name` (required)**: `string`, possible values: `"web_search", "browser"` `web_search` enables web search. `browser` enables the browser automation API inside `codemode`. Both use platform-provided credentials unless `credential_id` selects a customer credential. - **`type` (required)**: `string`, const: `"platform"` - **`credential_id`**: `string`, format: `uuid` Optional Exa credential for `web_search` or Browserbase credential for `browser`. - `object`, no additional properties - **`connection_id` (required)**: `string`, format: `uuid` - **`tools` (required)**: `array`, minItems: `1`, maxItems: `100`, uniqueItems: `true` Exact tool names your MCP server advertises. Sessions call the server for these tools, so keep it reachable and offering them. **Items:** `string`, minLength: `1`, maxLength: `200` - **`type` (required)**: `string`, const: `"mcp"` - `object`, no additional properties - **`tools` (required)**: `array`, minItems: `1`, maxItems: `100`, uniqueItems: `true` Clyck-managed and Blaxel sandboxes provide `read`, `write`, `edit` and `bash`; Daytona sandboxes provide the other listed names, including `computer_use_*` desktop tools. Daytona computer use requires a snapshot or attached sandbox with Daytona's required desktop software installed; Clyck starts desktop services automatically, so no startup call is needed. Use these unprefixed names in grants; inside `codemode` their callable names begin with `sandbox_`. Daytona `file_download` returns decoded text; for lossless binary reads, base64-encode the file with `execute_command`. The session configuration and lifecycle create and delete the sandbox itself. **Items:** `string`, possible values: `"read", "write", "edit", "bash", "execute_command", "file_upload", "file_download", "create_folder", "get_file_info", "list_files", "move_file", "delete_file", "computer_use_status", "computer_use_mouse_position", "computer_use_mouse_move", "computer_use_mouse_click", "computer_use_mouse_drag", "computer_use_mouse_scroll", "computer_use_keyboard_type", "computer_use_keyboard_press", "computer_use_keyboard_hotkey", "computer_use_screenshot", "computer_use_screenshot_region", "computer_use_screenshot_compressed", "computer_use_screenshot_compressed_region", "computer_use_display_info", "computer_use_windows", "computer_use_accessibility_tree", "computer_use_accessibility_find", "computer_use_accessibility_focus", "computer_use_accessibility_invoke", "computer_use_accessibility_set_value"` - **`type` (required)**: `string`, const: `"sandbox"` - `object`, no additional properties Calling the tool sends `POST` to the connection URL with the arguments as a JSON body, `Content-Type`: `application/json`, the connection's `headers`, and `Authorization: Bearer ` when the connection has an `api_key`. Every tool of a connection uses the connection URL, so give tools that your endpoint routes separately their own connection URLs. Respond directly rather than with a redirect. A `2xx` JSON body becomes the tool result, and `204` returns `null`; return business outcomes the model should read, such as "not found", as `2xx` results. Any other status fails the call with its HTTP status code. - **`connection_id` (required)**: `string`, format: `uuid` - **`description` (required)**: `string`, minLength: `1`, maxLength: `10000` - **`name` (required)**: `string`, maxLength: `100`, pattern: `^[a-zA-Z_][a-zA-Z0-9_]*$` **Not:** **Any of:** - `string`, possible values: `"codemode", "read_skill", "browser_client", "browser_command"` - `string`, pattern: `^(mcp_|sandbox_)` - **`parameters` (required)**: `object` Object JSON Schema for tool arguments. - **`type` (required)**: `string`, const: `"http"` ### Agent **Type:** `object` - **`created_at` (required)**: `string`, format: `date-time` - **`id` (required)**: `string`, format: `uuid` - **`name` (required)**: `string` - **`latest_version`**: [AgentVersion](/reference/schemas/AgentVersion.md) ### AgentVersion **Type:** `object` - **`agent_id` (required)**: `string`, format: `uuid` - **`config` (required)**: [AgentConfig](/reference/schemas/AgentConfig.md) - **`created_at` (required)**: `string`, format: `date-time` - **`id` (required)**: `string`, format: `uuid` - **`version` (required)**: `integer`, minimum: `1` ### Session **Type:** `object` - **`agent_version_id` (required)**: `string`, format: `uuid` - **`archived_at` (required)**: `string | null`, format: `date-time` When the session was permanently closed to new work, or null before archival. - **`config` (required)**: [AgentConfig](/reference/schemas/AgentConfig.md) - **`created_at` (required)**: `string`, format: `date-time` - **`id` (required)**: `string`, format: `uuid` ### SessionLifecycle **Type:** `object`, no additional properties - **`idle_since` (required)**: `string | null`, format: `date-time` Start of the current idle period, or null when active, in standby or archived. - **`state` (required)**: `string`, possible values: `"active", "idle", "standby", "archived"` Active is processing work; idle is retaining runtime resources during the five-minute grace period; standby has released runtime resources; archived is permanently closed to new work and retains readable history. ### SessionOverrides **Type:** `object`, no additional properties Supplied top-level fields replace the version's fields completely. Omission inherits. `sandbox` `null` removes the sandbox; `tools` must also be replaced if inherited grants require it. Empty `instructions`, `tools` or `skills` clears that field. Skill latest selectors resolve when the session is created. The resolved `config` follows `AgentConfig` validation. - **`instructions`**: `string`, maxLength: `100000` - **`model`**: [AgentModel](/reference/schemas/AgentModel.md) - **`sandbox`**: [Sandbox](/reference/schemas/Sandbox.md) | `null` One sandbox per session, bound for its lifetime when a tool first needs it. Sandboxes Clyck creates belong to the session and are deleted when it is archived or deleted. An existing `sandbox_id` attaches your own sandbox, which stays yours. If the bound sandbox becomes unavailable, sandbox tools return errors; start a new session for a fresh sandbox. - **`skills`**: array of [SkillAttachment](/reference/schemas/SkillAttachment.md) - **`thinking_level`**: `string`, possible values: `"off", "minimal", "low", "medium", "high", "xhigh", "max"` - **`tools`**: array of [ToolGrant](/reference/schemas/ToolGrant.md), maxItems: `100` ### CreateSubmission **One of:** - `object`, no additional properties - **`content` (required)**: [InputContent](/reference/schemas/InputContent.md) - **`request_id`**: `string`, minLength: `1`, maxLength: `200`, pattern: `\S` - **`type`**: `string`, const: `"input"`, default: `"input"` - **`when_busy`**: `string`, possible values: `"steer", "followUp", "reject"`, default: `"followUp"` - `object`, no additional properties - **`content` (required)**: [InputContent](/reference/schemas/InputContent.md) - **`type` (required)**: `string`, const: `"context"` - **`request_id`**: `string`, minLength: `1`, maxLength: `200`, pattern: `\S` **Example:** ```json { "content": "Analyze the account." } ``` **Example:** ```json { "type": "context", "content": "The account tier is premium.", "request_id": "account-tier-1" } ``` ### InputContent **One of:** - `string`, minLength: `1`, maxLength: `100000` - array of [InputBlock](/reference/schemas/InputBlock.md), minItems: `1`, maxItems: `100` ### InputBlock **One of:** - `object`, no additional properties - **`text` (required)**: `string` - **`type` (required)**: `string`, const: `"text"` - `object`, no additional properties - **`data` (required)**: `string`, minLength: `4` - **`mime_type` (required)**: `string`, possible values: `"image/png", "image/jpeg", "image/webp", "image/gif"` - **`type` (required)**: `string`, const: `"image"` - `object`, no additional properties - **`file_id` (required)**: `string`, format: `uuid` An uploaded file owned by this tenant. A file block is copied into the session's sandbox as a working copy; an image block supplies decoded image content directly to the model. - **`type` (required)**: `string`, possible values: `"file", "image"` ### Submission **Type:** `object`, no additional properties The durable outcome of accepted input. `queued` is waiting; `placed` identifies its input entry; `done` identifies its input entry and `answer` entry. `cancelled` and `failed` are terminal and include a stable `reason` and public `error`. Explicit abortion yields `cancelled`; other unsuccessful endings yield `failed`. Multiple input submissions may share one answer. For `type` `context`, `done` means the context entry was placed; context requests no work and has no `answer` field. `queued` context can be withdrawn individually. - **`conversation_id` (required)**: `integer`, minimum: `1` - **`id` (required)**: `integer`, minimum: `1` - **`status` (required)**: `string`, possible values: `"queued", "placed", "done", "cancelled", "failed"` - **`type` (required)**: `string`, possible values: `"input", "context"` - **`answer`**: `integer`, minimum: `1` - **`entry`**: `integer`, minimum: `1` - **`error`**: [ExecutionError](/reference/schemas/ExecutionError.md) A stable category and a safe, actionable explanation, free of raw provider errors, response bodies and credentials; a tool's own result can describe its failure in more detail. The `message` is for display; branch on `code`. Submission status and tool outcomes report the overall result. - **`reason`**: `string`, possible values: `"aborted", "model_error", "no_model", "reset", "execution_failed"` - **`request_id`**: `string` The `request_id` supplied with the submission; absent when none was supplied. **Example:** ```json { "id": 7, "conversation_id": 1, "type": "input", "status": "done", "entry": 40, "answer": 42 } ``` **Example:** ```json { "id": 8, "conversation_id": 1, "type": "input", "status": "failed", "reason": "model_error", "error": { "code": "model_error", "message": "The model could not complete the answer. Check the model configuration and retry the submission." } } ``` ### Entry **Type:** `object`, no additional properties - **`conversation_id` (required)**: `integer`, minimum: `1` - **`id` (required)**: `integer`, minimum: `1` Durable history reference. - **`kind` (required)**: `string`, possible values: `"message", "summary", "reset", "other"` Public entry classification; use `model` messages to render content. `other` entries record session bookkeeping, have no public messages and are not streamed as message events. - **`model` (required)**: array of [Message](/reference/schemas/Message.md) - **`head`**: `integer`, minimum: `1` - **`input`**: [InputContent](/reference/schemas/InputContent.md) Original submitted content for context and file-reference inputs, preserving file IDs independently of transformed model content. ### ContentBlock Public message content, including provider-returned thinking. Thinking is what the provider returns for the model: full text, a summary, an empty string or content marked `redacted`. Provider signatures and replay metadata stay internal. **One of:** - `object`, no additional properties - **`text` (required)**: `string` - **`type` (required)**: `string`, const: `"text"` - `object`, no additional properties - **`thinking` (required)**: `string` Provider-returned thinking text or summary; may be empty. - **`type` (required)**: `string`, const: `"thinking"` - **`redacted`**: `boolean` When `true`, the provider marked this content as redacted. - `object`, no additional properties - **`data` (required)**: `string` - **`mime_type` (required)**: `string` - **`type` (required)**: `string`, const: `"image"` - `object`, no additional properties - **`arguments` (required)**: `object` - **`id` (required)**: `string` Opaque execution identity for committed messages; preview-scoped identity before commitment. - **`name` (required)**: `string` - **`type` (required)**: `string`, const: `"toolCall"` ### Message **Type:** `object`, no additional properties - **`content` (required)**: array of [ContentBlock](/reference/schemas/ContentBlock.md) - **`role` (required)**: `string`, possible values: `"user", "assistant", "toolResult"` - **`duration_ms`**: `number`, minimum: `0` Generation time of an assistant message or execution time of a tool result, when available. - **`is_error`**: `boolean` - **`stop_reason`**: `string`, possible values: `"pending", "stop", "length", "toolUse", "error", "aborted"` `pending` is a preview; `stop` is a normal completion; `length` is a limit; `toolUse` requests tools; `error` and `aborted` are unsuccessful endings. An `aborted` message keeps the partial content generated before cancellation or interruption; the submission's `answer` names the answer entry. - **`timestamp`**: `number` Unix time in milliseconds. - **`tool_call_id`**: `string` Canonical execution ID of the tool call answered by this committed result. - **`tool_name`**: `string` - **`usage`**: [Usage](/reference/schemas/Usage.md) Token counters and estimated cost in USD, as reported by the provider and the model catalog. `null` means the measurement is unavailable. Zero counters within an available object are reported or calculated zeros, and an object that would be entirely zero is represented as `null`, which can include a free operation. Costs are estimates for your own tracking; your provider's bill is authoritative. Counters on a preview are provisional and become final at commitment. An aborted message reports the usage known when it stopped. ### ExecutionError **Type:** `object`, no additional properties A stable category and a safe, actionable explanation, free of raw provider errors, response bodies and credentials; a tool's own result can describe its failure in more detail. The `message` is for display; branch on `code`. Submission status and tool outcomes report the overall result. - **`code` (required)**: `string`, possible values: `"aborted", "model_error", "no_model", "reset", "execution_failed", "retry_scheduled", "compaction_failed", "tool_error", "tool_unavailable", "invalid_arguments", "blocked", "invalid_structured_output", "unknown_outcome"` - **`message` (required)**: `string` ### Usage **Type:** `object`, no additional properties Token counters and estimated cost in USD, as reported by the provider and the model catalog. `null` means the measurement is unavailable. Zero counters within an available object are reported or calculated zeros, and an object that would be entirely zero is represented as `null`, which can include a free operation. Costs are estimates for your own tracking; your provider's bill is authoritative. Counters on a preview are provisional and become final at commitment. An aborted message reports the usage known when it stopped. - **`cost` (required)**: `object | null`, no additional properties - **`cache_read` (required)**: `number`, minimum: `0` - **`cache_write` (required)**: `number`, minimum: `0` - **`currency` (required)**: `string`, const: `"USD"` - **`input` (required)**: `number`, minimum: `0` - **`output` (required)**: `number`, minimum: `0` - **`total` (required)**: `number`, minimum: `0` - **`tokens` (required)**: `object | null`, no additional properties - **`cache_read` (required)**: `number`, minimum: `0` - **`cache_write` (required)**: `number`, minimum: `0` - **`input` (required)**: `number`, minimum: `0` - **`output` (required)**: `number`, minimum: `0` - **`total` (required)**: `number`, minimum: `0` - **`cache_write_1h`**: `number`, minimum: `0` Optional subset of `cache_write` with one-hour retention; do not add it again. - **`reasoning`**: `number`, minimum: `0` Optional subset of `output`; do not add it again. **Example:** ```json { "tokens": { "input": 20, "output": 5, "cache_read": 0, "cache_write": 0, "total": 25 }, "cost": null } ``` **Example:** ```json { "tokens": null, "cost": null } ``` ### CumulativeUsage **Type:** `object`, no additional properties The session's cumulative recorded usage, grouped by model and tool. Model totals include committed assistant messages and context summarization attempts. Tool totals include reported tool usage. The value replaces previous cumulative usage, so use each `usage.updated` value as the new total. A source without a bucket has no recorded usage. Totals cover usage that providers and tools reported. - **`models` (required)**: `array` **Items:** no additional properties - **`model_id` (required)**: `string` - **`provider` (required)**: `string` - **`usage` (required)**: [Usage](/reference/schemas/Usage.md) Token counters and estimated cost in USD, as reported by the provider and the model catalog. `null` means the measurement is unavailable. Zero counters within an available object are reported or calculated zeros, and an object that would be entirely zero is represented as `null`, which can include a free operation. Costs are estimates for your own tracking; your provider's bill is authoritative. Counters on a preview are provisional and become final at commitment. An aborted message reports the usage known when it stopped. - **`tools` (required)**: `array` **Items:** no additional properties - **`name` (required)**: `string` - **`usage` (required)**: [Usage](/reference/schemas/Usage.md) Token counters and estimated cost in USD, as reported by the provider and the model catalog. `null` means the measurement is unavailable. Zero counters within an available object are reported or calculated zeros, and an object that would be entirely zero is represented as `null`, which can include a free operation. Costs are estimates for your own tracking; your provider's bill is authoritative. Counters on a preview are provisional and become final at commitment. An aborted message reports the usage known when it stopped. **Example:** ```json { "models": [], "tools": [] } ``` ### Inbox **Type:** `array` Current queued inputs, in queue order. Replace the previous inbox with this value. **Array of:** no additional properties - **`id` (required)**: `integer`, minimum: `1` - **`mode` (required)**: `string`, possible values: `"steer", "followUp", "context"` ### Retry **Type:** `object`, no additional properties - **`at` (required)**: `number` Scheduled retry time as Unix milliseconds; actual execution may start later. - **`attempt` (required)**: `integer`, minimum: `0` Attempt index supplied for the current generation. - **`error` (required)**: [ExecutionError](/reference/schemas/ExecutionError.md) A stable category and a safe, actionable explanation, free of raw provider errors, response bodies and credentials; a tool's own result can describe its failure in more detail. The `message` is for display; branch on `code`. Submission status and tool outcomes report the overall result. **Example:** ```json { "attempt": 1, "at": 1792195200000, "error": { "code": "retry_scheduled", "message": "The model request failed and a retry is scheduled." } } ``` ### ToolDiagnostic **Type:** `object`, no additional properties - **`code` (required)**: `string`, possible values: `"aborted", "model_error", "no_model", "reset", "execution_failed", "retry_scheduled", "compaction_failed", "tool_error", "tool_unavailable", "invalid_arguments", "blocked", "invalid_structured_output", "unknown_outcome", "tool_diagnostic"` Stable public diagnostic category; `tool_diagnostic` is an informational or warning diagnostic from the tool. - **`message` (required)**: `string` Safe display text. - **`severity` (required)**: `string`, possible values: `"info", "warn", "error"` ### ToolProgress **Type:** `object`, no additional properties Optional progress reported by a tool. Each value replaces the previous progress object. Units and completeness are tool-dependent; tools that report no progress can still be working. - **`completed`**: `number`, minimum: `0` - **`message`**: `string` - **`total`**: `number`, minimum: `0` - **`unit`**: `string` ### ToolCallList **Type:** `object`, no additional properties - **`data` (required)**: array of [ToolCall](/reference/schemas/ToolCall.md) - **`next_cursor` (required)**: `string | null` ### ToolCall **Type:** `object`, no additional properties Durable execution record for `codemode` or an inner tool. `call_id` and `parent_call_id` match stream/state IDs and remain stable for the session. `args` are the latest recorded execution arguments, including repairs; `pending` calls expose requested arguments. `done` means execution ended, and `outcome` reports how: `success` and `error` have a recorded result, and `unknown` means the call ended without one, so confirm any external effect with the service that owns it before retrying. Result, diagnostics, duration and usage follow `ToolCompleted`. Nested usage is reported separately from the parent's usage, so add each once. - **`args` (required)**: `object` - **`call_id` (required)**: `string` - **`name` (required)**: `string` - **`status` (required)**: `string`, possible values: `"pending", "running", "done"` - **`diagnostics`**: array of [ToolDiagnostic](/reference/schemas/ToolDiagnostic.md) - **`duration_ms`**: `number`, minimum: `0` - **`ended_at`**: `number` Unix milliseconds when execution ended, when available. - **`entry_id`**: `integer`, minimum: `1` - **`error`**: [ExecutionError](/reference/schemas/ExecutionError.md) A stable category and a safe, actionable explanation, free of raw provider errors, response bodies and credentials; a tool's own result can describe its failure in more detail. The `message` is for display; branch on `code`. Submission status and tool outcomes report the overall result. - **`outcome`**: `string`, possible values: `"success", "error", "unknown"` - **`parent_call_id`**: `string` - **`progress`**: [ToolProgress](/reference/schemas/ToolProgress.md) Optional progress reported by a tool. Each value replaces the previous progress object. Units and completeness are tool-dependent; tools that report no progress can still be working. - **`result`**: `any` Recorded JSON result for an inner tool, or public `content` array for a model-facing tool. - **`started_at`**: `number` Unix milliseconds when execution started, when available. - **`usage`**: [Usage](/reference/schemas/Usage.md) Token counters and estimated cost in USD, as reported by the provider and the model catalog. `null` means the measurement is unavailable. Zero counters within an available object are reported or calculated zeros, and an object that would be entirely zero is represented as `null`, which can include a free operation. Costs are estimates for your own tracking; your provider's bill is authoritative. Counters on a preview are provisional and become final at commitment. An aborted message reports the usage known when it stopped. **Example:** ```json { "call_id": "c2", "parent_call_id": "c1", "name": "search", "args": { "query": "streaming" }, "status": "done", "outcome": "success", "result": { "matches": 2 }, "duration_ms": 25, "diagnostics": [] } ``` ### ToolActivity **Type:** `object`, no additional properties Current tool activity. `call_id` is opaque; `parent_call_id` identifies the enclosing operation for nested calls. `args` are the requested arguments for a model-facing call; for a running nested call they are its current execution arguments. `tool.started` supplies execution arguments after any repair. `output` is a live window of recent output; the dropped byte and line counts describe output trimmed from its front. `done` means execution ended, and `outcome` reports how; `unknown` means the call ended without a recorded result, so confirm any external effect before retrying. When a snapshot carries only the summary of a failed nested call, it omits `outcome` and `error`; `GET tool-calls/{call_id}` has the recorded outcome. Nested calls can remain listed after their parent completes, and `GET tool-calls` keeps every call with its results. - **`call_id` (required)**: `string` - **`name` (required)**: `string` - **`status` (required)**: `string`, possible values: `"pending", "running", "done"` - **`args`**: `object` - **`diagnostics`**: array of [ToolDiagnostic](/reference/schemas/ToolDiagnostic.md) - **`dropped_bytes`**: `integer`, minimum: `0` - **`dropped_lines`**: `integer`, minimum: `0` - **`duration_ms`**: `number`, minimum: `0` Execution time of the attempt that produced a result; omitted when unavailable. - **`entry_id`**: `integer`, minimum: `1` Durable tool-result entry when available. - **`error`**: [ExecutionError](/reference/schemas/ExecutionError.md) A stable category and a safe, actionable explanation, free of raw provider errors, response bodies and credentials; a tool's own result can describe its failure in more detail. The `message` is for display; branch on `code`. Submission status and tool outcomes report the overall result. - **`outcome`**: `string`, possible values: `"success", "error", "unknown"` - **`output`**: `string` - **`parent_call_id`**: `string` - **`progress`**: [ToolProgress](/reference/schemas/ToolProgress.md) Optional progress reported by a tool. Each value replaces the previous progress object. Units and completeness are tool-dependent; tools that report no progress can still be working. - **`usage`**: [Usage](/reference/schemas/Usage.md) Token counters and estimated cost in USD, as reported by the provider and the model catalog. `null` means the measurement is unavailable. Zero counters within an available object are reported or calculated zeros, and an object that would be entirely zero is represented as `null`, which can include a free operation. Costs are estimates for your own tracking; your provider's bill is authoritative. Counters on a preview are provisional and become final at commitment. An aborted message reports the usage known when it stopped. ### Compaction **Type:** `object`, no additional properties Current context summarization activity. `compaction_id` is opaque and scoped to the current snapshot. - **`attempt` (required)**: `integer`, minimum: `0` - **`blocking` (required)**: `boolean` Whether generation is waiting for this summarization. - **`compaction_id` (required)**: `string` - **`reason` (required)**: `string`, possible values: `"manual", "threshold", "overflow"` - **`retry`**: [Retry](/reference/schemas/Retry.md) ### CompactionFailure **Type:** `object`, no additional properties Most recent summarization failure since a summary was last produced. - **`compaction_id` (required)**: `string` - **`error` (required)**: [ExecutionError](/reference/schemas/ExecutionError.md) A stable category and a safe, actionable explanation, free of raw provider errors, response bodies and credentials; a tool's own result can describe its failure in more detail. The `message` is for display; branch on `code`. Submission status and tool outcomes report the overall result. - **`reason` (required)**: `string`, possible values: `"manual", "threshold", "overflow"` ### State **Type:** `object`, no additional properties Complete replacement live state used by `GET state` and `snapshot` events. Every snapshot establishes fresh preview and compaction identities. `entries` are the committed entries in the current active conversation context, which can omit earlier history after summarization or a context reset; retrieve complete or missing history through `GET entries`. Partial generation content is only a preview. This state has queued inputs and active submission IDs, not every terminal submission; reconcile tracked submissions using their read endpoints. - **`agent` (required)**: `object`, no additional properties - **`model`**: `object`, no additional properties - **`model_id` (required)**: `string` - **`provider` (required)**: `string` - **`thinking_level`**: `string` - **`conversation` (required)**: `object`, no additional properties - **`id` (required)**: `integer`, minimum: `1` - **`parent`**: `object`, no additional properties - **`at` (required)**: `integer`, minimum: `1` - **`conversation_id` (required)**: `integer`, minimum: `1` - **`entries` (required)**: array of [Entry](/reference/schemas/Entry.md) - **`execution` (required)**: `object`, no additional properties - **`busy` (required)**: `boolean` - **`compactions` (required)**: array of [Compaction](/reference/schemas/Compaction.md) - **`inputs` (required)**: `array` **Items:** `integer`, minimum: `1` - **`nested_tools` (required)**: array of [ToolActivity](/reference/schemas/ToolActivity.md) - **`tools` (required)**: array of [ToolActivity](/reference/schemas/ToolActivity.md) - **`compaction_failure`**: [CompactionFailure](/reference/schemas/CompactionFailure.md) Most recent summarization failure since a summary was last produced. - **`generation`**: `object`, no additional properties - **`attempt` (required)**: `integer`, minimum: `0` - **`message`**: [Message](/reference/schemas/Message.md) - **`preview_id`**: `string` Opaque identity established by this snapshot. - **`retry`**: [Retry](/reference/schemas/Retry.md) - **`inbox` (required)**: [Inbox](/reference/schemas/Inbox.md) Current queued inputs, in queue order. Replace the previous inbox with this value. - **`usage` (required)**: [CumulativeUsage](/reference/schemas/CumulativeUsage.md) The session's cumulative recorded usage, grouped by model and tool. Model totals include committed assistant messages and context summarization attempts. Tool totals include reported tool usage. The value replaces previous cumulative usage, so use each `usage.updated` value as the new total. A source without a bucket has no recorded usage. Totals cover usage that providers and tools reported. ### ExecutionEvent **Type:** `object`, no additional properties Execution started or ended for these submission IDs. When `execution.ended` arrives, discard any remaining preview and active tool activity for that execution, and read the submissions for their outcomes. - **`inputs` (required)**: `array` **Items:** `integer`, minimum: `1` **Example:** ```json { "inputs": [ 7 ] } ``` ### MessageStarted **Type:** `object`, no additional properties Establish an assistant preview with its initial public content. `preview_id` is opaque and valid only until the next snapshot or the preview is completed or discarded by `execution.ended`. - **`message` (required)**: [Message](/reference/schemas/Message.md) - **`preview_id` (required)**: `string` **Example:** ```json { "preview_id": "p1", "message": { "role": "assistant", "content": [] } } ``` ### MessageDelta Changes to one preview. `content` inserts a new block at the zero-based public `content_index`, including the initial `thinking` block. `text` appends `delta` to the `text` field of the `text` block there; `thinking` appends `delta` to the `thinking` field of the `thinking` block there. `arguments` appends `delta` to the existing string at `path` within that `toolCall` block's `arguments` object, as a parsed value rather than serialized JSON. Path strings name object properties and integers name array indexes. Indexes address the public `content` array, including thinking blocks. Content replacement, changes to redacted markers, argument shape changes and other non-append changes use `message.replaced`, which supplies full thinking blocks. Snapshots and completed messages also contain full blocks. Apply changes in delivery order. **One of:** discriminated by `type` - `object`, no additional properties - **`block` (required)**: [ContentBlock](/reference/schemas/ContentBlock.md) Public message content, including provider-returned thinking. Thinking is what the provider returns for the model: full text, a summary, an empty string or content marked `redacted`. Provider signatures and replay metadata stay internal. - **`content_index` (required)**: `integer`, minimum: `0` - **`preview_id` (required)**: `string` - **`type` (required)**: `string`, const: `"content"` - `object`, no additional properties - **`content_index` (required)**: `integer`, minimum: `0` - **`delta` (required)**: `string` - **`preview_id` (required)**: `string` - **`type` (required)**: `string`, const: `"text"` - `object`, no additional properties - **`content_index` (required)**: `integer`, minimum: `0` - **`delta` (required)**: `string` - **`preview_id` (required)**: `string` - **`type` (required)**: `string`, const: `"thinking"` - `object`, no additional properties - **`content_index` (required)**: `integer`, minimum: `0` - **`delta` (required)**: `string` - **`path` (required)**: `array`, minItems: `1` **Items:** **One of:** - `string` - `integer`, minimum: `0` - **`preview_id` (required)**: `string` - **`type` (required)**: `string`, const: `"arguments"` **Example:** ```json { "preview_id": "p1", "content_index": 0, "type": "content", "block": { "type": "text", "text": "" } } ``` **Example:** ```json { "preview_id": "p1", "content_index": 0, "type": "text", "delta": "Hello" } ``` **Example:** ```json { "preview_id": "p2", "content_index": 0, "type": "arguments", "path": [ "code" ], "delta": "text(result);" } ``` **Example:** ```json { "preview_id": "p3", "content_index": 0, "type": "content", "block": { "type": "thinking", "thinking": "" } } ``` **Example:** ```json { "preview_id": "p3", "content_index": 0, "type": "thinking", "delta": "Considering the available options." } ``` ### MessageReplaced **Type:** `object`, no additional properties Replace the entire preview under `preview_id`, including all `content` and `usage`. Replacements can shorten content, revise tool arguments or start a new generation attempt. Never append the replacement to the previous message. `preview_id` remains the same until completion or a fresh snapshot. - **`message` (required)**: [Message](/reference/schemas/Message.md) - **`preview_id` (required)**: `string` **Example:** ```json { "preview_id": "p1", "message": { "role": "assistant", "content": [ { "type": "text", "text": "Starting again." } ] } } ``` ### MessageCompleted **Type:** `object`, no additional properties An authoritative committed message with its durable history entry. Replace the matching preview when `preview_id` is present; otherwise append or reconcile by `entry_id`. Completion may be delivered without a preceding preview, including user and tool-result messages. The full entry is the same projection returned by `GET entries`. Work can continue after a message completes; submission status reports when input is answered. - **`entry` (required)**: [Entry](/reference/schemas/Entry.md) - **`entry_id` (required)**: `integer`, minimum: `1` - **`message` (required)**: [Message](/reference/schemas/Message.md) - **`preview_id`**: `string` - **`usage`**: [Usage](/reference/schemas/Usage.md) Token counters and estimated cost in USD, as reported by the provider and the model catalog. `null` means the measurement is unavailable. Zero counters within an available object are reported or calculated zeros, and an object that would be entirely zero is represented as `null`, which can include a free operation. Costs are estimates for your own tracking; your provider's bill is authoritative. Counters on a preview are provisional and become final at commitment. An aborted message reports the usage known when it stopped. **Example:** ```json { "entry_id": 42, "preview_id": "p1", "entry": { "id": 42, "conversation_id": 1, "kind": "message", "model": [ { "role": "assistant", "content": [ { "type": "text", "text": "Hello there." } ] } ] }, "message": { "role": "assistant", "content": [ { "type": "text", "text": "Hello there." } ] } } ``` ### ToolStarted **Type:** `object`, no additional properties A tool began execution with these arguments. Applies to `codemode` and calls made inside it. A nested call includes `parent_call_id`. Match operations by opaque `call_id`, never by parsing its value or assuming a name is unique. A tool can complete without a start notification when it could not start or updates were coalesced. - **`args` (required)**: `object` - **`call_id` (required)**: `string` - **`name` (required)**: `string` - **`parent_call_id`**: `string` **Example:** ```json { "call_id": "c2", "name": "search", "parent_call_id": "c1", "args": { "query": "streaming" } } ``` ### ToolOutputChange A change to the retained output window. `replace` discards all prior retained text and uses `text`. `append` first removes `trim_start` UTF-16 code units from the front of the retained string, then appends `text`. An empty `text` is meaningful: it can represent a trim without an append. Use string slicing in JavaScript; clients in other languages must account for UTF-16 surrogate pairs. This is not an append-only full log. A fresh snapshot supplies the replacement retained window and available dropped byte/line totals. **One of:** discriminated by `type` - `object`, no additional properties - **`text` (required)**: `string` - **`type` (required)**: `string`, const: `"replace"` - `object`, no additional properties - **`text` (required)**: `string` - **`trim_start` (required)**: `integer`, minimum: `0` - **`type` (required)**: `string`, const: `"append"` **Example:** ```json { "type": "replace", "text": "Recent output" } ``` **Example:** ```json { "type": "append", "trim_start": 7, "text": " plus new output" } ``` ### ToolUpdated **Type:** `object`, no additional properties Changes to current output, progress or diagnostics. Fields omitted from an update remain unchanged. `progress` replaces the previous progress object; `null` clears it. `diagnostics` replaces the previous list. These fields contain the documented tool-facing presentation, not arbitrary internal execution details. - **`call_id` (required)**: `string` - **`name` (required)**: `string` - **`diagnostics`**: array of [ToolDiagnostic](/reference/schemas/ToolDiagnostic.md) - **`output`**: [ToolOutputChange](/reference/schemas/ToolOutputChange.md) A change to the retained output window. `replace` discards all prior retained text and uses `text`. `append` first removes `trim_start` UTF-16 code units from the front of the retained string, then appends `text`. An empty `text` is meaningful: it can represent a trim without an append. Use string slicing in JavaScript; clients in other languages must account for UTF-16 surrogate pairs. This is not an append-only full log. A fresh snapshot supplies the replacement retained window and available dropped byte/line totals. - **`parent_call_id`**: `string` - **`progress`**: [ToolProgress](/reference/schemas/ToolProgress.md) | `null` Optional progress reported by a tool. Each value replaces the previous progress object. Units and completeness are tool-dependent; tools that report no progress can still be working. **Example:** ```json { "call_id": "c2", "name": "search", "parent_call_id": "c1", "output": { "type": "replace", "text": "Found 2 results" }, "progress": { "completed": 2, "total": 5, "unit": "pages" } } ``` ### ToolCompleted **Type:** `object`, no additional properties End of a tool operation. `success` and `error` mean a result was recorded; `unknown` means execution ended without a recorded result, including a call interrupted after it started, so confirm any external effect before retrying. `error.code` is `aborted` when cancellation ended the call, and a call that had already started can have taken effect. For nested tools, `result` is the tool's JSON result, according to its own output schema; for a model-facing tool it is the public result content array. The result envelope is stable, while tool-defined JSON is application data. Errors may still include `result` data. `duration_ms` and `usage` are omitted when unavailable. Clear the running `output` and `progress` unless completion supplies final `progress`. Completed calls can leave the live snapshot; retrieve their recorded results through `GET tool-calls` after reconnect. - **`call_id` (required)**: `string` - **`diagnostics` (required)**: array of [ToolDiagnostic](/reference/schemas/ToolDiagnostic.md) - **`name` (required)**: `string` - **`outcome` (required)**: `string`, possible values: `"success", "error", "unknown"` - **`duration_ms`**: `number`, minimum: `0` - **`entry_id`**: `integer`, minimum: `1` - **`error`**: [ExecutionError](/reference/schemas/ExecutionError.md) A stable category and a safe, actionable explanation, free of raw provider errors, response bodies and credentials; a tool's own result can describe its failure in more detail. The `message` is for display; branch on `code`. Submission status and tool outcomes report the overall result. - **`parent_call_id`**: `string` - **`progress`**: [ToolProgress](/reference/schemas/ToolProgress.md) Optional progress reported by a tool. Each value replaces the previous progress object. Units and completeness are tool-dependent; tools that report no progress can still be working. - **`result`**: `any` Tool-defined JSON result or public model-facing result content. - **`usage`**: [Usage](/reference/schemas/Usage.md) Token counters and estimated cost in USD, as reported by the provider and the model catalog. `null` means the measurement is unavailable. Zero counters within an available object are reported or calculated zeros, and an object that would be entirely zero is represented as `null`, which can include a free operation. Costs are estimates for your own tracking; your provider's bill is authoritative. Counters on a preview are provisional and become final at commitment. An aborted message reports the usage known when it stopped. **Example:** ```json { "call_id": "c2", "name": "search", "parent_call_id": "c1", "outcome": "success", "result": { "matches": 2 }, "duration_ms": 25, "diagnostics": [] } ``` **Example:** ```json { "call_id": "c3", "name": "update_account", "outcome": "unknown", "diagnostics": [], "error": { "code": "unknown_outcome", "message": "The call ended without a known result. External effects may have occurred." } } ``` ### RetryEnded **Type:** `object`, no additional properties Retry waiting ended for this attempt. Later events report what happened next. - **`attempt` (required)**: `integer`, minimum: `0` **Example:** ```json { "attempt": 1 } ``` ### CompactionStarted **Type:** `object`, no additional properties Context summarization began. `compaction_id` is opaque and scoped to this snapshot. - **`blocking` (required)**: `boolean` - **`compaction_id` (required)**: `string` - **`reason` (required)**: `string`, possible values: `"manual", "threshold", "overflow"` **Example:** ```json { "compaction_id": "compact1", "reason": "threshold", "blocking": false } ``` ### CompactionCompleted **Type:** `object`, no additional properties Context summarization ended. `completed` means it ended without a failure, which includes cancellation and having nothing to summarize; a produced summary appears as a committed `summary` entry. `error` includes a public failure. Remove this compaction from current activity. - **`compaction_id` (required)**: `string` - **`outcome` (required)**: `string`, possible values: `"completed", "error"` - **`reason` (required)**: `string`, possible values: `"manual", "threshold", "overflow"` - **`error`**: [ExecutionError](/reference/schemas/ExecutionError.md) A stable category and a safe, actionable explanation, free of raw provider errors, response bodies and credentials; a tool's own result can describe its failure in more detail. The `message` is for display; branch on `code`. Submission status and tool outcomes report the overall result. **Example:** ```json { "compaction_id": "compact1", "reason": "threshold", "outcome": "completed" } ``` ### InboxUpdated **Type:** `object`, no additional properties - **`items` (required)**: [Inbox](/reference/schemas/Inbox.md) Current queued inputs, in queue order. Replace the previous inbox with this value. **Example:** ```json { "items": [ { "id": 7, "mode": "followUp" } ] } ``` ### ExecutionFailed **Type:** `object`, no additional properties An execution failure notification. Submission outcomes remain authoritative for whether input was answered. - **`error` (required)**: [ExecutionError](/reference/schemas/ExecutionError.md) A stable category and a safe, actionable explanation, free of raw provider errors, response bodies and credentials; a tool's own result can describe its failure in more detail. The `message` is for display; branch on `code`. Submission status and tool outcomes report the overall result. **Example:** ```json { "error": { "code": "execution_failed", "message": "Execution failed. Inspect submission status before deciding whether to retry." } } ``` ### ModelList **Type:** `object` - **`data` (required)**: `array` **Items:** - **`id` (required)**: `string` - **`provider` (required)**: `string` - **`context_window`**: `integer`, minimum: `1` Maximum model context in tokens. - **`input`**: `array` Supported input content types. **Items:** `string`, possible values: `"text", "image"` - **`name`**: `string` - **`next_cursor` (required)**: `null` ### File **Type:** `object` - **`created_at` (required)**: `string`, format: `date-time` - **`filename` (required)**: `string`, minLength: `1`, maxLength: `255` **Not:** `string`, pattern: `[\r\n\u0000]` - **`id` (required)**: `string`, format: `uuid` - **`mime_type` (required)**: `string` - **`size` (required)**: `integer`, minimum: `0` ### Artifact **Type:** `object`, no additional properties - **`created_at` (required)**: `string`, format: `date-time` - **`filename` (required)**: `string`, minLength: `1`, maxLength: `255` - **`id` (required)**: `string`, format: `uuid` File ID for download or deletion. - **`mime_type` (required)**: `string` - **`session_id` (required)**: `string`, format: `uuid` - **`sha256` (required)**: `string`, pattern: `^[a-f0-9]{64}$` - **`size` (required)**: `integer`, minimum: `0`, maximum: `16777216` - **`source_path` (required)**: `string`, pattern: `^/` - **`tool_call_id` (required)**: `string` Producing tool execution reference. ### ArtifactList **Type:** `object`, no additional properties - **`data` (required)**: array of [Artifact](/reference/schemas/Artifact.md) - **`next_cursor` (required)**: `string | null` ### Webhook **Type:** `object`, no additional properties - **`created_at` (required)**: `string`, format: `date-time` - **`events` (required)**: `array`, minItems: `1`, maxItems: `2`, uniqueItems: `true` **Items:** `string`, possible values: `"submission.updated", "artifact.created"` - **`id` (required)**: `string`, format: `uuid` - **`url` (required)**: `string`, format: `uri` ### CreatedWebhook **Type:** `object`, no additional properties - **`created_at` (required)**: `string`, format: `date-time` - **`events` (required)**: `array`, minItems: `1`, maxItems: `2`, uniqueItems: `true` **Items:** `string`, possible values: `"submission.updated", "artifact.created"` - **`id` (required)**: `string`, format: `uuid` - **`signing_secret` (required)**: `string` Returned only by registration creation. - **`url` (required)**: `string`, format: `uri` ### WebhookList **Type:** `object`, no additional properties - **`data` (required)**: array of [Webhook](/reference/schemas/Webhook.md) - **`next_cursor` (required)**: `string | null` ### WebhookEvent **One of:** - `object`, no additional properties - **`created_at` (required)**: `string`, format: `date-time` - **`id` (required)**: `string`, format: `uuid` - **`session_id` (required)**: `string`, format: `uuid` - **`submission_id` (required)**: `integer`, minimum: `1` - **`type` (required)**: `string`, const: `"submission.updated"` - `object`, no additional properties - **`created_at` (required)**: `string`, format: `date-time` - **`file_id` (required)**: `string`, format: `uuid` - **`id` (required)**: `string`, format: `uuid` - **`session_id` (required)**: `string`, format: `uuid` - **`type` (required)**: `string`, const: `"artifact.created"` **Example:** ```json { "id": "20000000-0000-4000-8000-000000000001", "type": "submission.updated", "created_at": "2026-10-19T12:00:00Z", "session_id": "30000000-0000-4000-8000-000000000001", "submission_id": 7 } ``` ### WebhookDelivery **Type:** `object`, no additional properties - **`attempts` (required)**: `integer`, minimum: `0` - **`created_at` (required)**: `string`, format: `date-time` - **`delivered_at` (required)**: `string | null` - **`event_id` (required)**: `string`, format: `uuid` - **`expires_at` (required)**: `string`, format: `date-time` - **`id` (required)**: `string`, format: `uuid` - **`last_error` (required)**: `string | null` Safe delivery error code; never includes the signing secret or response body. - **`last_status_code` (required)**: `integer | null` - **`next_attempt_at` (required)**: `string | null` Next eligible attempt time while pending. - **`status` (required)**: `string`, possible values: `"pending", "succeeded", "failed", "cancelled"` ### WebhookDeliveryList **Type:** `object`, no additional properties - **`data` (required)**: array of [WebhookDelivery](/reference/schemas/WebhookDelivery.md) - **`next_cursor` (required)**: `string | null`