{ "openapi": "3.1.0", "info": { "title": "Tonbo Management API", "version": "2.0.0", "description": "Stable, bearer-only control-plane API. Every credential belongs to exactly\none account, so account-scoped operations take the account from the\ncredential, never from the path. People present a personal key (`tbo_…`)\ndirectly; Agent keys are exchanged at `POST https://tonbo.dev/api/iam/token`\nfirst, and presented directly they answer 401 `exchange_required`. Each\naccount operation names the capability of contracts/iam/account-roles-v1.json\nit needs and its one client: the `tonbo` command that calls it\n(`x-tonbo-cli`), or `x-tonbo-yield` for the `@tonbo/yield` session capture\nclient; registering a computer names its `yield` command (`x-yield-cli`).\nThe `/agents/{agent_id}/…`\noperations are the offline Managed Agents runtime, kept for their deployed\ncallers. Each operation declares whether its implementation is enforced or\nproposed.\n\nResponses may gain fields; clients ignore fields they do not know. Request\nbodies stay closed: an unknown field is refused. A breaking change to an\nenforced operation ships as a new version, or with a compatibility window\nthat names its consumer and removal condition.\n" }, "x-tonbo-status": "mixed", "servers": [ { "url": "https://api.tonbo.dev/v1" } ], "security": [ { "MemberBearer": [] }, { "AgentBearer": [] } ], "tags": [ { "name": "Account", "description": "The caller's account, its regions, members and Agents." }, { "name": "Buckets", "description": "The account's Streams buckets; streams live at each bucket's url." }, { "name": "Databases", "description": "The account's databases, each one stream at its url; Control creates and deletes them." }, { "name": "Machines", "description": "The account's Machines (contracts/machines/machine-v2.json). Exec and file actions on a Machine are not offered yet." }, { "name": "Streams", "description": "The account's raw durable streams, each at its url; Control creates and deletes them." }, { "name": "API keys", "description": "Keys of the account's members, people and Agents." }, { "name": "Usage", "description": "The account's rated usage." }, { "name": "Sessions", "description": "Where the account's captured agent sessions are stored (contracts/sessions/README.md)." }, { "name": "Git", "description": "The account's git workspaces (apps/user-center/docs/decisions/adr-0016-org-git-workspaces.md); repositories are served by gitd at each workspace's git origin." }, { "name": "Agents", "description": "The offline Managed Agents runtime, addressed by Agent." }, { "name": "Operations", "description": "Durable, generation-fenced execution of authorized control requests." } ], "paths": { "/account": { "get": { "operationId": "getAccount", "tags": [ "Account" ], "summary": "Read the caller's account, membership and limits", "x-tonbo-status": "enforced", "x-tonbo-capability": "account.read", "x-tonbo-cli": "tonbo account show", "security": [ { "MemberBearer": [] } ], "responses": { "200": { "description": "The account", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Account" } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/regions": { "get": { "operationId": "listRegions", "tags": [ "Account" ], "summary": "List the regions new resources can be created in", "x-tonbo-status": "enforced", "x-tonbo-capability": "account.read", "x-tonbo-cli": "tonbo region list", "security": [ { "MemberBearer": [] } ], "responses": { "200": { "description": "Regions", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Region" } } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/members": { "get": { "operationId": "listMembers", "tags": [ "Account" ], "summary": "List the account's people and Agents with their roles", "x-tonbo-status": "enforced", "x-tonbo-capability": "account.read", "x-tonbo-cli": "tonbo member list", "security": [ { "MemberBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Members", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Member" } }, "next_cursor": { "$ref": "#/components/schemas/NextCursor" } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/members/devices": { "get": { "operationId": "listMemberDevices", "tags": [ "Account" ], "summary": "List the organization's members' devices", "description": "What an organization sees of its members' own computers (contracts/machines/machine-v2.json `kinds.byoc.projection`; ADR-0016 W-17): for each current member who is a person, each device of their personal account that is not being forgotten, with its handle in this organization (null when it has none), its name, the agent harnesses on it and whether it reported within `online_window_seconds`. The organization holds no device record: each read joins the member's current membership at request time, so a person who leaves is absent from the next read, and the answer is never cached. It never answers a device's hostname, device id, operating system version, architecture, client version, key state, Machine id or personal account. A person with a role reads it, with a read-only key too; an Agent, a key narrowed to buckets or by name, and a personal account answer 403. `unavailable_regions` names the regions whose devices could not be read and are missing.", "x-tonbo-status": "enforced", "x-tonbo-capability": "account.read", "x-tonbo-yield": true, "security": [ { "MemberBearer": [] } ], "responses": { "200": { "description": "The members' devices, by member and then name", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "unavailable_regions" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MemberDevice" } }, "unavailable_regions": { "type": "array", "items": { "$ref": "#/components/schemas/RegionId" } } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/members/{subject}": { "parameters": [ { "name": "subject", "in": "path", "required": true, "description": "The member to change, by the `subject` `GET /v1/members` lists: a person's user id, or `agent.` for an Agent.", "schema": { "$ref": "#/components/schemas/MemberSubject" } } ], "patch": { "operationId": "updateMember", "tags": [ "Account" ], "summary": "Change a member's role, or rename an Agent", "description": "Owners and admins give a person or an Agent another role; only an owner grants `owner`. `name` renames an Agent: it follows the Agent name rule and is unique among the account's active Agents (409 otherwise), and the Agent keeps its id, keys, home region and public hostname. A person's name belongs to their own profile, so `name` on a person is refused with 422 `validation_error` on the field `name`. Both fields in one request change together or not at all. People change members; an Agent's credential is refused with 403.", "x-tonbo-status": "enforced", "x-tonbo-capability": "members.write", "x-tonbo-cli": "tonbo member update", "security": [ { "MemberBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMemberRequest" } } } }, "responses": { "200": { "description": "The member", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Member" } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/agents": { "post": { "operationId": "createAgent", "tags": [ "Account" ], "summary": "Create an Agent, an identity with a role in the account", "description": "Owners and admins create Agents; only an owner grants `owner`. A replay with the same Idempotency-Key returns the Agent the first request created.", "x-tonbo-status": "enforced", "x-tonbo-capability": "agents.create", "x-tonbo-cli": "tonbo agent create", "security": [ { "MemberBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAccountAgentRequest" } } } }, "responses": { "201": { "description": "The Agent", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AccountAgent" } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api-keys": { "get": { "operationId": "listApiKeys", "tags": [ "API keys" ], "summary": "List your keys, or every key of the account for an owner or admin", "x-tonbo-status": "enforced", "x-tonbo-capability": "api_keys.own", "x-tonbo-cli": "tonbo api-key list", "security": [ { "MemberBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Live keys", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } }, "next_cursor": { "$ref": "#/components/schemas/NextCursor" } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "createApiKey", "tags": [ "API keys" ], "summary": "Create a key; its secret is in this answer only", "description": "A personal key acts as you; an Agent key (`member: agent.`), which owners and admins create, acts as the Agent, whose role may not exceed yours. `read_only`, and either `buckets` or any of `databases`, `database_prefixes`, `streams` and `stream_prefixes`, narrow the key for its whole life: a different narrowing takes a new key. An access token never creates a key, and neither does a narrowed key.", "x-tonbo-status": "enforced", "x-tonbo-capability": "api_keys.own", "x-tonbo-cli": "tonbo api-key create", "x-tonbo-idempotency": "none: the secret is never stored, so a replay cannot return it; a live key name is unique, so a blind retry answers 409 instead of creating a second key.", "security": [ { "MemberBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyRequest" } } } }, "responses": { "201": { "description": "The key and its secret", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ApiKeyWithSecret" } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api-keys/{key_id}": { "parameters": [ { "name": "key_id", "in": "path", "required": true, "description": "The key's `id`, as `GET /v1/api-keys` lists it.", "schema": { "$ref": "#/components/schemas/Uuid" } } ], "get": { "operationId": "getApiKey", "tags": [ "API keys" ], "summary": "Read one key", "x-tonbo-status": "enforced", "x-tonbo-capability": "api_keys.own", "x-tonbo-cli": "tonbo api-key show", "security": [ { "MemberBearer": [] } ], "responses": { "200": { "description": "The key", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ApiKey" } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "revokeApiKey", "tags": [ "API keys" ], "summary": "Revoke a key and every token minted from it", "description": "Your own key, or any key of the account for an owner or admin. A narrowed key may revoke itself (`tonbo logout`).", "x-tonbo-status": "enforced", "x-tonbo-capability": "api_keys.own", "x-tonbo-cli": "tonbo api-key revoke", "security": [ { "MemberBearer": [] } ], "responses": { "200": { "description": "The revocation", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "id", "revoked_at" ], "properties": { "id": { "$ref": "#/components/schemas/Uuid" }, "revoked_at": { "$ref": "#/components/schemas/Timestamp" } } } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/buckets": { "get": { "operationId": "listBuckets", "tags": [ "Buckets" ], "summary": "List the account's buckets", "description": "A key narrowed to a bucket list sees only those buckets.", "x-tonbo-status": "enforced", "x-tonbo-capability": "account.read", "x-tonbo-cli": "tonbo bucket list", "security": [ { "MemberBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Buckets", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Bucket" } }, "next_cursor": { "$ref": "#/components/schemas/NextCursor" } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "createBucket", "tags": [ "Buckets" ], "summary": "Create a bucket", "description": "Owners and admins create buckets, at most `limits.buckets` live per account. A name is reserved to its account forever, deleted or not. A replay with the same Idempotency-Key answers the bucket the first request created; the key reused for another name answers 409. A narrowed key never creates a bucket.", "x-tonbo-status": "enforced", "x-tonbo-capability": "buckets.write", "x-tonbo-cli": "tonbo bucket create", "security": [ { "MemberBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBucketRequest" } } } }, "responses": { "201": { "description": "The bucket", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Bucket" } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/buckets/{name}": { "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/BucketName" } } ], "get": { "operationId": "getBucket", "tags": [ "Buckets" ], "summary": "Read a bucket", "x-tonbo-status": "enforced", "x-tonbo-capability": "account.read", "x-tonbo-cli": "tonbo bucket show", "security": [ { "MemberBearer": [] } ], "responses": { "200": { "description": "The bucket", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Bucket" } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "operationId": "updateBucket", "tags": [ "Buckets" ], "summary": "Publish a bucket for anonymous reads, or take it private", "x-tonbo-status": "enforced", "x-tonbo-capability": "buckets.write", "x-tonbo-cli": "tonbo bucket update", "security": [ { "MemberBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBucketRequest" } } } }, "responses": { "200": { "description": "The bucket", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Bucket" } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "deleteBucket", "tags": [ "Buckets" ], "summary": "Delete a bucket and every stream in it", "description": "The bucket becomes `deleting` and is purged; its name is never used again. Deleting an Agent never deletes a bucket.", "x-tonbo-status": "enforced", "x-tonbo-capability": "buckets.write", "x-tonbo-cli": "tonbo bucket delete", "security": [ { "MemberBearer": [] } ], "responses": { "200": { "description": "The bucket, being deleted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Bucket" } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/usage": { "get": { "operationId": "getUsage", "tags": [ "Usage" ], "summary": "Read the account's rated usage of one month", "x-tonbo-status": "enforced", "x-tonbo-capability": "usage.read", "x-tonbo-cli": "tonbo usage show", "security": [ { "MemberBearer": [] } ], "parameters": [ { "name": "period", "in": "query", "description": "The calendar month in UTC; the current month when omitted.", "schema": { "type": "string", "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])$" } } ], "responses": { "200": { "description": "Usage", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Usage" } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/sessions/store": { "get": { "operationId": "getSessionsStore", "tags": [ "Sessions" ], "summary": "Read where the account's captured sessions are stored", "description": "The account's session store, ensured on read (its cell recorded once, by the databases and buckets selector, at the account's first discovery), where the `@tonbo/yield` client writes session streams and `proc.inbox` (contracts/sessions/capture-v1.json), and the account's default git workspace, where its snapshots and recall live. Any person with a role on the account may read it with an unnarrowed key; an Agent and a read-only or narrowed key are refused (403). An organization's key is answered only with `capture=team`, the store its shared team Projects' sessions are captured into (ADR-0017 D-2; contracts/sessions/capture-v1.json `store.team_capture`); without it the key answers 409 `personal_account_required`, since a person's own sessions live in their personal store. 503 `session_store_creating` with Retry-After while the store is being created at its first discovery; 409 `sessions_store_unavailable` while its account is suspended for payment; 410 `session_store_gone` once its inbox is being deleted with the account, which is terminal; 503 `region_unavailable` when its cell is not served here (contracts/sessions/capture-v1.json `store.refusals`).", "x-tonbo-status": "enforced", "x-tonbo-capability": "account.read", "x-tonbo-yield": true, "security": [ { "MemberBearer": [] } ], "parameters": [ { "name": "capture", "in": "query", "required": false, "description": "`team` asks for an organization's store, for a shared team Project's sessions; a personal account's answer does not change with it.", "schema": { "type": "string", "enum": [ "team" ] } } ], "responses": { "200": { "description": "The session store", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SessionsStore" } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "description": "The store is being deleted with its account (`session_store_gone`); nothing more is captured into it", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "The store is being created (`session_store_creating`), or its region is unavailable (`region_unavailable`); both carry Retry-After", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/git/workspaces": { "get": { "operationId": "listGitWorkspaces", "tags": [ "Git" ], "summary": "List the account's git workspaces", "description": "Every workspace of the account that is not purged, the default first, with its id (the `git_workspace` of its tokens and the `workspace` a git token exchange names), its `ws_hex`, its name, whether it is the account's default, its git cell and that cell's git origin. Every account has a default workspace from its creation. Any person with a role on the account may list them; an Agent is refused, since an Agent's git token takes the account's default workspace or names one. Listing admits nothing: every git token is admitted at its mint.", "x-tonbo-status": "enforced", "x-tonbo-capability": "account.read", "x-tonbo-cli": "tonbo workspace list", "security": [ { "MemberBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Git workspaces", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/GitWorkspace" } }, "next_cursor": { "$ref": "#/components/schemas/NextCursor" } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/bindings": { "get": { "operationId": "listProjectBindings", "tags": [ "Sessions" ], "summary": "Resolve a device's folders to the account's Projects", "description": "The caller's own folder bindings on one local device to Projects of the key's account, oldest first, each with its Project (its origin key, snapshot repository and workspace) and, for an organization's Project, the device's handle there (apps/user-center/docs/decisions/adr-0016-org-git-workspaces.md W-18; contracts/sessions/capture-v1.json `projects`). The daemon asks each account it holds a key of. Only a person's own unnarrowed key; an Agent and a read-only or narrowed key are refused (403).", "x-tonbo-status": "enforced", "x-tonbo-capability": "account.read", "x-tonbo-yield": true, "security": [ { "MemberBearer": [] } ], "parameters": [ { "name": "device_id", "in": "query", "required": true, "description": "The local device id yield keeps on the computer (ADR-0015 Q1).", "schema": { "$ref": "#/components/schemas/Uuid" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "The device's bindings in this account", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SessionProjectBinding" } }, "next_cursor": { "$ref": "#/components/schemas/NextCursor" } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/connect": { "post": { "operationId": "connectProjectFolder", "tags": [ "Sessions" ], "summary": "Bind a folder to a Project of the account", "description": "Binds the caller's folder on one local device to a Project of the key's account, in exactly one form: `origin`, the folder's origin remote URL, whose key (@tonbo/project-naming) groups every clone of one repository into the account's one Project with that origin, made in the account's default workspace when there is none and named `name` or the origin's last path segment; `project_id`, an existing Project of the account; or `name` alone, a new Project the person names, whose snapshot repository is `snap-`. No path is sent: `folder_id` is a random id the daemon keeps. An organization's Project needs the device registered as the person's `byoc` Machine and answers the device's handle there; a personal Project needs no registration. A folder bound to another Project of this account moves to the new one (a new binding id); one bound to another account's Project is refused with 409 `folder_bound_elsewhere`; 409 `project_repository_taken` when another Project of the account has the origin's repository; 409 `device_not_registered` for an organization's Project from an unregistered device (contracts/sessions/capture-v1.json `projects.refusals`). Only a person's own unnarrowed key.", "x-tonbo-status": "enforced", "x-tonbo-capability": "account.read", "x-tonbo-yield": true, "x-tonbo-idempotency": "none: a repeat binds the same folder to the same Project: an origin's Project is found by its origin key, and a named Project is reused while the folder is bound to a Project of that name.", "security": [ { "MemberBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectProjectFolderRequest" } } } }, "responses": { "200": { "description": "The folder was already bound to that Project", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SessionProjectBinding" } } } } } }, "201": { "description": "The new binding", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SessionProjectBinding" } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/bindings/{binding_id}": { "parameters": [ { "name": "binding_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } } ], "delete": { "operationId": "disconnectProjectFolder", "tags": [ "Sessions" ], "summary": "Disconnect a folder from its Project", "description": "Deletes the caller's own folder binding to a Project of the key's account; the Project stays. 404 for any other binding. Only a person's own unnarrowed key.", "x-tonbo-status": "enforced", "x-tonbo-capability": "account.read", "x-tonbo-yield": true, "security": [ { "MemberBearer": [] } ], "responses": { "204": { "description": "The binding was deleted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/yield/sessions/{sessionId}/latest-result": { "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } } ], "get": { "operationId": "latestPersonalHandoffResult", "tags": [ "Sessions" ], "summary": "Resolve the author's latest live unpulled result for a session", "description": "Read-only alias for the handoff's author, in a personal account or a team Project. The returned handoff id must still pass the result route's live gitd pin check before fetching.", "x-tonbo-status": "enforced", "x-tonbo-capability": "account.read", "x-tonbo-yield": true, "security": [ { "MemberBearer": [] } ], "responses": { "200": { "description": "Selected handoff id", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "$ref": "#/components/schemas/Uuid" } } } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RegionUnavailable" } } } }, "/yield/handoffs": { "get": { "operationId": "listHandoffs", "tags": [ "Sessions" ], "summary": "List the caller's open handoffs", "description": "Open handoffs (created, claimed, running or need_human) the caller authored, holds, or is named in, newest activity first. A personal login lists every account of its person; an organization's login lists that organization's. Each handoff is read through the same routines as a show, so current membership is rechecked; the list carries metadata only, never turns.", "x-tonbo-status": "enforced", "x-tonbo-capability": "account.read", "x-tonbo-yield": true, "security": [ { "MemberBearer": [] } ], "responses": { "200": { "description": "The open handoffs", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/HandoffListItem" } } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RegionUnavailable" } } }, "post": { "operationId": "createPersonalHandoff", "tags": [ "Sessions" ], "summary": "Create a manual handoff in the caller's personal account or team Project", "description": "Only an unnarrowed personal login key may create. The key's account selects the scope: a personal account's Project, or an organization's shared team Project, where the session must be the caller's own team session and a person target (target_sub) must be a current member. A team handoff may carry context_excerpt, the only raw content of a team session a teammate receives, and only from take. User Center resolves the live Project binding, pins the pushed snapshot in gitd for 30 days, then writes one handoff. A stable pin_id replays exactly one row. A machine target (target_machine_id) must be one of the author's own devices; only that device's daemon claims it. The response shows the pin expiry so yield can display it.", "x-tonbo-status": "enforced", "x-tonbo-capability": "account.read", "x-tonbo-yield": true, "security": [ { "MemberBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePersonalHandoffRequest" } } } }, "responses": { "201": { "description": "The new handoff, or an exact replay", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PersonalHandoffCreated" } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RegionUnavailable" } } } }, "/yield/handoffs/events": { "get": { "operationId": "listHandoffEvents", "tags": [ "Sessions" ], "summary": "Read handoff transitions after a cursor, immediately or by long poll", "description": "The transitions (created, claimed, running, done, need_human, failed, returned, cancelled) after `after` of the handoffs the caller authored, may take, or is named in, in commit order; visibility is rechecked on every read and an event of a handoff the caller can no longer read is skipped. With `wait` greater than 0 the request is held until an event arrives or the wait ends. Pass `next_after` as the next `after`. A personal login reads every account of its person; an organization's login reads that organization's.", "x-tonbo-status": "enforced", "x-tonbo-capability": "account.read", "x-tonbo-yield": true, "security": [ { "MemberBearer": [] } ], "parameters": [ { "name": "after", "in": "query", "required": false, "description": "The cursor; 0 or omitted reads from the start.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "wait", "in": "query", "required": false, "description": "Seconds to hold the request for a first event; 0 or omitted answers at once.", "schema": { "type": "integer", "minimum": 0, "maximum": 25 } } ], "responses": { "200": { "description": "Events after the cursor, at most 100, and the next cursor", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "events", "next_after" ], "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/HandoffEvent" } }, "next_after": { "type": "integer", "minimum": 0 } } } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RegionUnavailable" } } } }, "/yield/handoffs/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } } ], "get": { "operationId": "showPersonalHandoff", "tags": [ "Sessions" ], "summary": "Read a handoff without claiming it", "description": "The author reads a personal handoff; any current member of the organization reads a team Project's handoff. This read does not renew, claim, or release a snapshot pin; expiry is the last authoritative receipt recorded on the handoff.", "x-tonbo-status": "enforced", "x-tonbo-capability": "account.read", "x-tonbo-yield": true, "security": [ { "MemberBearer": [] } ], "responses": { "200": { "description": "The handoff and its recorded snapshot context", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PersonalHandoffView" } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RegionUnavailable" } } } }, "/yield/handoffs/{id}/take": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } } ], "post": { "operationId": "takePersonalHandoff", "tags": [ "Sessions" ], "summary": "Claim a manual handoff after verifying its source pin", "description": "The claimant may retry a claim after a failed local fetch. A handoff dispatched to a device (target_kind machine) is taken only by that device's daemon, which names its device_id; any other take is refused. On the author's own take User Center checks the pin with gitd and renews it before SQL claim when less than 24 hours remain; a teammate's take needs more than 24 hours left on the recorded pin and is checked against current membership and the assignment under the account lock. The response contains a pinned ref for yield to fetch; claim alone never releases the pin.", "x-tonbo-status": "enforced", "x-tonbo-capability": "account.read", "x-tonbo-yield": true, "security": [ { "MemberBearer": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "device_id": { "description": "The taking daemon's device id; required to take a handoff dispatched to a device.", "oneOf": [ { "$ref": "#/components/schemas/Uuid" }, { "type": "null" } ] } } } } } }, "responses": { "200": { "description": "The claimed handoff and source snapshot", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PersonalHandoffTake" } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RegionUnavailable" } } } }, "/yield/handoffs/{id}/restored": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } } ], "post": { "operationId": "markPersonalHandoffRestored", "tags": [ "Sessions" ], "summary": "Acknowledge a successful local restore and release the source pin", "description": "yield calls only after it has fetched and checked out the pinned snapshot. SQL commits restored_at before User Center releases the source pin, which only the author's own restore can do (source_pin_released is false for a teammate; the author's pull or cancel releases it, or it expires); repeating the request retries a pending release without changing the marker.", "x-tonbo-status": "enforced", "x-tonbo-capability": "account.read", "x-tonbo-yield": true, "security": [ { "MemberBearer": [] } ], "responses": { "200": { "description": "Restore acknowledged and source pin released", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PersonalHandoffRestored" } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RegionUnavailable" } } } }, "/yield/handoffs/{id}/started": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } } ], "post": { "operationId": "startPersonalHandoff", "tags": [ "Sessions" ], "summary": "Mark work started or resume it after human input", "description": "The owner explicitly starts or resumes work in a restored workspace. Claim or restore alone never means running. Resuming need_human clears its temporary reason in the current H2a row.", "x-tonbo-status": "enforced", "x-tonbo-capability": "account.read", "x-tonbo-yield": true, "security": [ { "MemberBearer": [] } ], "responses": { "200": { "description": "Work is running, or an exact start/resume retry", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PersonalHandoffStarted" } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RegionUnavailable" } } } }, "/yield/handoffs/{id}/need-human": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } } ], "post": { "operationId": "needHumanPersonalHandoff", "tags": [ "Sessions" ], "summary": "Record why a restored personal handoff needs human input", "description": "The original personal claimant may stop an active restored handoff. An exact retry returns the recorded reason. This transition creates no result pin.", "x-tonbo-status": "enforced", "x-tonbo-capability": "account.read", "x-tonbo-yield": true, "security": [ { "MemberBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeedHumanPersonalHandoffRequest" } } } }, "responses": { "200": { "description": "Help requested, or exact retry", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PersonalHandoffNeedsHuman" } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RegionUnavailable" } } } }, "/yield/handoffs/{id}/cancel": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } } ], "post": { "operationId": "cancelPersonalHandoff", "tags": [ "Sessions" ], "summary": "Cancel an unclaimed handoff and release its source pin", "description": "The author cancels before any claim; in a team Project the author may also cancel a claim held by someone who has left the organization.", "x-tonbo-status": "enforced", "x-tonbo-capability": "account.read", "x-tonbo-yield": true, "security": [ { "MemberBearer": [] } ], "responses": { "200": { "description": "Cancellation recorded and source pin released", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PersonalHandoffCancelled" } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RegionUnavailable" } } } }, "/yield/handoffs/{id}/renew-source": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } } ], "post": { "operationId": "renewPersonalHandoffSource", "tags": [ "Sessions" ], "summary": "Renew an unconsumed source pin for 30 days", "description": "The original author may renew before expiry; an expired or already restored pin cannot be revived.", "x-tonbo-status": "enforced", "x-tonbo-capability": "account.read", "x-tonbo-yield": true, "security": [ { "MemberBearer": [] } ], "responses": { "200": { "description": "The renewed source expiry", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PersonalHandoffSourceRenewed" } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RegionUnavailable" } } } }, "/yield/handoffs/{id}/done": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } } ], "post": { "operationId": "finishPersonalHandoff", "tags": [ "Sessions" ], "summary": "Complete a running manual handoff with a pinned result", "description": "The claimant pushes a result commit first. User Center verifies its exact own ref and Tonbo-Handoff trailer in gitd, then pins for 30 days before recording done. A failed directory write leaves a bounded pin until expiry rather than risking release of another handoff's reused pin ID.", "x-tonbo-status": "enforced", "x-tonbo-capability": "account.read", "x-tonbo-yield": true, "security": [ { "MemberBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinishPersonalHandoffRequest" } } } }, "responses": { "200": { "description": "Completed handoff or exact retry", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PersonalHandoffDone" } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RegionUnavailable" } } } }, "/yield/handoffs/{id}/result": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } } ], "get": { "operationId": "pullPersonalHandoff", "tags": [ "Sessions" ], "summary": "Verify and read an unpulled result pin", "description": "The original author sees only a live pin, renewed before local fetch when nearly expired. A teammate's result is pinned under the teammate's sub and must have more than 24 hours left.", "x-tonbo-status": "enforced", "x-tonbo-capability": "account.read", "x-tonbo-yield": true, "security": [ { "MemberBearer": [] } ], "responses": { "200": { "description": "Pinned result and fetch ref", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PersonalHandoffResult" } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RegionUnavailable" } } } }, "/yield/handoffs/{id}/pulled": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } } ], "post": { "operationId": "markPersonalHandoffPulled", "tags": [ "Sessions" ], "summary": "Acknowledge a local result pull and release its pin", "description": "SQL records result_pulled_at before gitd release. Replaying retries an incomplete release. For a teammate's result the author releases their own source pin instead; the result pin ends at its expiry (result_pin_released false).", "x-tonbo-status": "enforced", "x-tonbo-capability": "account.read", "x-tonbo-yield": true, "security": [ { "MemberBearer": [] } ], "responses": { "200": { "description": "Pull acknowledged and result pin released", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PersonalHandoffPulled" } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RegionUnavailable" } } } }, "/yield/handoffs/{id}/renew-result": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } } ], "post": { "operationId": "renewPersonalHandoffResult", "tags": [ "Sessions" ], "summary": "Renew a completed result pin for 30 days", "description": "The original author may renew their own result pin before expiry while the handoff is done; successful yield pull releases it. A teammate's result keeps its 30-day pin.", "x-tonbo-status": "enforced", "x-tonbo-capability": "account.read", "x-tonbo-yield": true, "security": [ { "MemberBearer": [] } ], "responses": { "200": { "description": "The renewed result expiry", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PersonalHandoffResultRenewed" } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RegionUnavailable" } } } }, "/yield/metrics": { "post": { "operationId": "recordYieldMetric", "tags": [ "Sessions" ], "summary": "Record one content-free Yield Alpha measure", "description": "Only an unnarrowed personal login key may record, always on its personal account. The kind and value follow contracts/sessions/handoff-v1.json `metrics` exactly; free text, unknown kinds and out-of-range values answer 422. A handoff_id must name a handoff the caller authored in that account. The yield CLI writes in the background and never fails a command on the answer.", "x-tonbo-status": "enforced", "x-tonbo-capability": "account.read", "x-tonbo-yield": true, "x-tonbo-idempotency": "none: a measure is an observation; a rare duplicate after a lost answer is within the Alpha rollup's tolerance", "security": [ { "MemberBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordYieldMetricRequest" } } } }, "responses": { "201": { "description": "The measure was recorded", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/YieldMetricRecorded" } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RegionUnavailable" } } } }, "/yield/excerpts": { "post": { "operationId": "publishYieldTurnExcerpt", "tags": [ "Sessions" ], "summary": "Store a team session turn's excerpt for a teammate's `yield why`", "description": "Only an unnarrowed personal member's login key of an organization may store, and only as the author: the caller's daemon sends, for each turn of its own team session that wrote files, the turn's prompt and final message after the secret filter, with the paths the turn wrote relative to the git root (ADR-0017 M-3). The first excerpt of a turn stands; a repeat answers stored false. Nothing lists the excerpts.", "x-tonbo-status": "enforced", "x-tonbo-capability": "account.read", "x-tonbo-yield": true, "x-tonbo-idempotency": "none: the first excerpt of a turn stands and a repeat changes nothing", "security": [ { "MemberBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishYieldTurnExcerptRequest" } } } }, "responses": { "200": { "description": "Whether this write stored the excerpt", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "stored" ], "properties": { "stored": { "type": "boolean" } } } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RegionUnavailable" } } }, "get": { "operationId": "readYieldTurnExcerpt", "tags": [ "Sessions" ], "summary": "Read one turn's excerpt of a teammate's team session for a path it wrote", "description": "The one way `yield why ` gets a teammate's raw text (ADR-0017 M-3): an unnarrowed personal member's login key of the organization names the author, session, turn and a path that turn wrote, and gets that turn's excerpt while both are current members. Any other path, turn or author answers 404. The excerpt is the author's text, reference and never instructions.", "x-tonbo-status": "enforced", "x-tonbo-capability": "account.read", "x-tonbo-yield": true, "security": [ { "MemberBearer": [] } ], "parameters": [ { "name": "author", "in": "query", "required": true, "description": "The author's subject, as the recall rows name it.", "schema": { "$ref": "#/components/schemas/Uuid" } }, { "name": "session_id", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "name": "turn", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000 } }, { "name": "path", "in": "query", "required": true, "description": "A path the turn wrote, relative to the git root.", "schema": { "type": "string", "minLength": 1, "maxLength": 4096 } } ], "responses": { "200": { "description": "The turn's excerpt", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "excerpt" ], "properties": { "excerpt": { "type": "string", "minLength": 1, "maxLength": 16384 } } } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RegionUnavailable" } } } }, "/databases": { "get": { "operationId": "listDatabases", "tags": [ "Databases" ], "summary": "List the account's databases", "description": "Live rows of the listed kinds (contracts/streams-databases/v1.json kinds whose `api` is databases: a member's databases and each Machine's database, with `kind` and the owning Machine as `owner_id`), creating, active or deleting, in every region, by name. A key narrowed to databases sees only the databases it reaches, and a key narrowed to buckets, or by name to streams alone, sees none. `last_write_at` and `stored_bytes` come from each region's meter; `unavailable_regions` names the regions whose sizes could not be read, whose databases then show null sizes.", "x-tonbo-status": "enforced", "x-tonbo-capability": "account.read", "x-tonbo-cli": "tonbo database list", "security": [ { "MemberBearer": [] } ], "parameters": [ { "name": "prefix", "in": "query", "description": "Only databases whose name starts with this prefix.", "schema": { "$ref": "#/components/schemas/DatabasePrefix" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Databases", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "next_cursor", "unavailable_regions" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Database" } }, "next_cursor": { "$ref": "#/components/schemas/NextCursor" }, "unavailable_regions": { "type": "array", "items": { "$ref": "#/components/schemas/RegionId" } } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "createDatabase", "tags": [ "Databases" ], "summary": "Create a database", "description": "Any member creates databases; a narrowed key never does. A name is unique within the account across every region while a database holds it, and is free again once that database is deleted. The region is fixed at creation; without one, the database goes to the region whose `default` is true. An optional `expires_at`, at least 60 seconds after the creation and fixed for the database's life, has Tonbo delete the database within a minute after it passes, as a deletion would; a replay is not held to the 60 seconds. Databases and streams expire by the same rule; a Machine's database never expires. The answer is 201 once the database is active and 202 while it is still being created; read it again until it is active. A replay with the same Idempotency-Key answers the same database; the key reused for another name, region or expiry answers 409. An account holds at most `limits.databases_per_account` live databases (contracts/streams-databases/v1.json); past that the answer is 403 and names whom to contact. An account whose credit is exhausted answers 402.", "x-tonbo-status": "enforced", "x-tonbo-capability": "databases.write", "x-tonbo-cli": "tonbo database create", "security": [ { "MemberBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDatabaseRequest" } } } }, "responses": { "201": { "description": "The database, active", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Database" } } } } } }, "202": { "description": "The database, still being created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Database" } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RegionUnavailable" } } } }, "/databases/{name}": { "parameters": [ { "name": "name", "in": "path", "required": true, "description": "The database's name, or a Machine's database as `m.`.", "schema": { "$ref": "#/components/schemas/ListedDatabaseName" } } ], "get": { "operationId": "getDatabase", "tags": [ "Databases" ], "summary": "Read a database", "description": "A live database of the account, with its `url`, `expires_at` and `state`; clients that open a database by name, such as `@tonbo/sqlite-ursula/tonbo`, resolve it here. A key narrowed to databases reads the databases it names and those under its prefixes, and any other name answers 404 with the same status and body as a database that does not exist, so the narrowing does not disclose whether the account's other databases exist. A key narrowed to buckets, or by name to streams alone, reads none.", "x-tonbo-status": "enforced", "x-tonbo-capability": "account.read", "x-tonbo-cli": "tonbo database show", "security": [ { "MemberBearer": [] } ], "responses": { "200": { "description": "The database", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Database" } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "operationId": "updateDatabase", "tags": [ "Databases" ], "summary": "Publish a database for anonymous reads, or take it private", "description": "Owners and admins, on an active database. Anonymous readers reach only the database's current incarnation. A Machine's database answers 409 `managed_by_machine` (contracts/streams-databases/v1.json `kinds.managed_refusal`).", "x-tonbo-status": "enforced", "x-tonbo-capability": "databases.publish", "x-tonbo-cli": "tonbo database update", "security": [ { "MemberBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDatabaseRequest" } } } }, "responses": { "200": { "description": "The database", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Database" } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "deleteDatabase", "tags": [ "Databases" ], "summary": "Delete a database and everything in it", "description": "Any member deletes databases; a narrowed key never does. The answer is 200 once the database is deleted (`state` is `deleted`) and 202 while it is still being deleted. Its name is free again once it is deleted; its usage this month stays in `/usage/databases`. Repeating the request answers the database being deleted. A Machine's database is deleted with its Machine and answers 409 `managed_by_machine` (contracts/streams-databases/v1.json `kinds.managed_refusal`).", "x-tonbo-status": "enforced", "x-tonbo-capability": "databases.write", "x-tonbo-cli": "tonbo database delete", "security": [ { "MemberBearer": [] } ], "responses": { "200": { "description": "The database, deleted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Database" } } } } } }, "202": { "description": "The database, being deleted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Database" } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/usage/databases": { "get": { "operationId": "listDatabaseUsage", "tags": [ "Usage", "Databases" ], "summary": "Read each database's usage of one month at list price", "description": "One row per listed database version (name, stream creation time and counting history) metered in the month, rolled up by contracts/streams-databases/v1.json `kinds.values..usage`: a Machine's logs and inbox streams are added into its database's row, and a Volume's ledger into `other`; in every region the account reaches, including databases deleted during the month, plus `other` for metered usage outside the account's databases (its streams, which `/usage/streams` lists, session processing and anything unattributed), so the rows and `other` add up to the account's metered total. Values are at list price, before the monthly allowance and credit; Usage & billing (`/usage`) shows what is charged.", "x-tonbo-status": "enforced", "x-tonbo-capability": "usage.read", "x-tonbo-cli": "tonbo database usage", "security": [ { "MemberBearer": [] } ], "parameters": [ { "name": "period", "in": "query", "description": "The calendar month in UTC; the current month when omitted.", "schema": { "type": "string", "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])$" } }, { "name": "sort", "in": "query", "description": "By list value, highest first (the default), or by name.", "schema": { "type": "string", "enum": [ "-list_value", "name" ], "default": "-list_value" } }, { "name": "prefix", "in": "query", "description": "Only databases whose name starts with this prefix.", "schema": { "$ref": "#/components/schemas/DatabasePrefix" } }, { "name": "names", "in": "query", "description": "Only these databases, 1 to 100 listed names, comma-separated (a database name or a Machine's database).", "schema": { "type": "string", "minLength": 1 } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Per-database usage", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatabaseUsagePage" } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/machines": { "get": { "operationId": "listMachines", "tags": [ "Machines" ], "summary": "List the account's Machines", "description": "The account's Machines by name, except those being deleted: managed Machines and, in a personal account, its devices (kind `byoc`, which `PUT /machines/self` registers) from every region, whatever `machines.open` says; `unavailable_regions` names the regions whose Machines on the page could not be read. A device answers `id`, `name`, `kind`, `region`, `byoc` (with its `key_state`, derived from its current login key), `created_at` and `updated_at`; its `byoc.hostname` and `byoc.device_id` are answered to the device's person only, never to an Agent key. A narrowed key never reaches a Machine. An organization holds managed Machines only (contracts/machines/machine-v2.json `kinds_by_account_kind`), so its list never answers a `byoc` Machine or its fields, and its pages and cursors are those of its managed Machines alone.", "x-tonbo-status": "enforced", "x-tonbo-capability": "account.read", "x-tonbo-cli": "tonbo machine list", "security": [ { "MemberBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Machines", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "next_cursor", "unavailable_regions" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Machine" } }, "next_cursor": { "$ref": "#/components/schemas/NextCursor" }, "unavailable_regions": { "type": "array", "items": { "$ref": "#/components/schemas/RegionId" } } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/MachineRefused" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "createMachine", "tags": [ "Machines" ], "summary": "Create a Machine", "description": "Any member creates Machines (`machines.write`); a public port also needs `machines.public`, and a narrowed key never does. The image is the reserved platform reference `tonbo.dev/platform` (machine-v2.schema.json `$defs.platform_image_reference`), which resolves nothing, is stored with `repository` and `digest` null and reads as `state` `ready`, or a public registry reference, which resolves to its canonical `repository` and linux/arm64 `digest`, stored with the reference, and reads as `state` `pulling` until a node has pulled it (`state` is computed, never stored; see getMachine); a registry reference is refused before anything is written, with 422 `image_platform_unsupported` when it has no linux/arm64 manifest and `validation_error` when it is not a public reference the resolver can fetch under machine-v2.json `image.distribution` (a malformed reference, an unknown or unavailable image, a redirected manifest or an oversized document). The name, the HTTPS label `-` and the SSH username are then reserved for the account, and the Machine is recorded in its region, which is fixed for its life; without `region` it goes to the account's default creation region. A region where Machines are not offered (`machines.open` in contracts/regions/cells-v1.json) answers the shared 422 `region_not_offered`, and a shape that is not offered 422 `shape_not_offered`, before anything is written. The answer is 202 while the Machine is being created and 201 in every other state (machine-v2.json `creation.create_status`). Both carry `Location`, the Machine's URL, and the 202 also `Retry-After`, the seconds to wait before reading the Machine there again (machine-v2.json `creation.poll_after_seconds`), until its `state` is `active` or `failed`. A replay with the same Idempotency-Key answers the same Machine as it is now, so a replay of a Machine whose creation failed answers 201 with its `failure`; the key reused for another request answers 409 `idempotency_conflict`. Refusals carry the codes and statuses of contracts/machines/machine-v2.json `errors`.", "x-tonbo-status": "enforced", "x-tonbo-capability": "machines.write", "x-tonbo-cli": "tonbo machine create", "security": [ { "MemberBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "../machines/machine-v2.schema.json#/$defs/create" } } } }, "responses": { "201": { "description": "The Machine, no longer being created (a replay of a failed create carries its `failure`)", "headers": { "ETag": { "$ref": "#/components/headers/MachineETag" }, "Location": { "$ref": "#/components/headers/MachineLocation" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineEnvelope" } } } }, "202": { "description": "The Machine, still being created", "headers": { "ETag": { "$ref": "#/components/headers/MachineETag" }, "Location": { "$ref": "#/components/headers/MachineLocation" }, "Retry-After": { "description": "The seconds to wait before reading the Machine at `Location` again (machine-v2.json `creation.poll_after_seconds`).", "required": true, "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineEnvelope" } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/MachineRefused" }, "409": { "$ref": "#/components/responses/MachineRefused" }, "422": { "$ref": "#/components/responses/MachineRefused" }, "429": { "$ref": "#/components/responses/MachineRefused" } } } }, "/machines/self": { "put": { "operationId": "registerMachineSelf", "tags": [ "Machines" ], "summary": "Register this computer as a device", "description": "Registers the computer whose CLI login key signs the request as a Machine of kind `byoc` in the person's personal account, or reports it again (contracts/machines/machine-v2.json `actions` `register` and `kinds.byoc`). Only the key `yield login` or `tonbo login` issued, presented directly and unnarrowed, registers; any other key, an exchanged token or the console answers 403 `self_requires_login_key`, then an organization's login answers 403 `self_requires_personal_account`, then a new device past `limits.byoc_per_person` answers 403 `device_limit_reached`, each before anything is written. The server decides the kind; the body names none. A device is keyed on (person, `device_id`) and keeps its Machine id, name and region across logins; `name` is read only when the device is new (the default is `-`, never the hostname, and a taken name answers 409 `name_taken`). A report within `limits.byoc_last_seen_min_interval_seconds` whose facts changed answers 429 `device_report_throttled` with Retry-After; 409 `device_registration_conflict` is retryable. `hostname` and `device_id` are answered to the device's person only. Served whatever `machines.open` says: a device runs nothing Tonbo operates. A device whose cell, or a new device whose default cell, this server does not bind answers 503 `region_unavailable`. The answer is 201 for a new device and 200 otherwise.", "x-tonbo-status": "enforced", "x-tonbo-capability": "machines.write", "x-yield-cli": "yield login", "security": [ { "MemberBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "../machines/machine-v2.schema.json#/$defs/register" } } } }, "responses": { "200": { "description": "The device, reported again", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineEnvelope" } } } }, "201": { "description": "The device, registered", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineEnvelope" } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/MachineRefused" }, "409": { "$ref": "#/components/responses/MachineRefused" }, "422": { "$ref": "#/components/responses/MachineRefused" }, "429": { "$ref": "#/components/responses/MachineRefused" }, "503": { "$ref": "#/components/responses/RegionUnavailable" } } } }, "/machines/{name}": { "parameters": [ { "name": "name", "in": "path", "required": true, "description": "The Machine's name.", "schema": { "$ref": "../machines/machine-v2.schema.json#/$defs/name" } } ], "get": { "operationId": "getMachine", "tags": [ "Machines" ], "summary": "Read a Machine", "description": "A Machine of the account. A device (kind `byoc`, in a personal account only) is served whatever `machines.open` says and answers its `byoc` facts, `hostname` and `device_id` to its person only, with its id as its ETag (`\"\"`), which a delete may name in If-Match. A managed Machine's ETag is `\".\"` (contracts/machines/machine-v2.json `etag`), opaque to clients: an update names it in If-Match, and a delete or a sleep may, so a tag read from one Machine never matches another that later takes its name. A Machine is read whatever `machines.open` says, so a closure never hides it; a region this server cannot reach answers 503 `region_unavailable`. Its `image` names the canonical `repository` a registry image is pulled from and a `state` computed from the pull: `pulling` until a node has pulled the digest while the Machine is creating or active, `ready` once one has (always for the platform reference `tonbo.dev/platform`, which is never pulled), `failed` with a `failure` whose code is one of contracts/machines/machine-v2.json `image.failures`, and `not_pulled` on a failed or deleting Machine that no node pulled, since nothing will. While the image is not ready, a request that would wake the Machine answers 503 `image_pulling`, or 409 `image_failed` once the pull failed. `status.conditions` says why a Machine is not doing what it should: `wake_blocked` when its last wake was refused and none has succeeded since, with the `reason`, `since` and, for a crash backoff, `retry_at`; `creation_delayed` once it has been creating for longer than contracts/machines/machine-v2.json `creation.alert_after_seconds`; `egress_blocked` while its outbound access is blocked; and `volume_purged` when the Volume its spec names was purged (in practice after 30 days of suspension past the owners' notice), so it boots without it until the spec names another Volume or none. `activation.revision` is the spec revision the live activation was admitted with. Every spec change advances the Machine's `revision`, but ports and `sleep_after_seconds` apply at once, so a lower `activation.revision` means a sleep is needed only when image, command, shape or env changed; `GET /machines/{name}/activations` says how each earlier activation ended. A managed Machine names its creator in `created_by`.", "x-tonbo-status": "enforced", "x-tonbo-capability": "account.read", "x-tonbo-cli": "tonbo machine show", "security": [ { "MemberBearer": [] } ], "responses": { "200": { "description": "The Machine, with its ETag", "headers": { "ETag": { "$ref": "#/components/headers/MachineETag" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineEnvelope" } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RegionUnavailable" } } }, "patch": { "operationId": "updateMachine", "tags": [ "Machines" ], "summary": "Change a Machine's spec", "description": "A managed Machine only: a device answers 409 `machine_kind_mismatch`, whatever `machines.open` says. If-Match is required, because `env` and `ports` are replaced whole: the change is written only at the revision it names, so a missing one answers 428 `precondition_required`, a stale one 412 `precondition_failed`, and a concurrent change is never lost; an If-Match that is not this Machine's ETag, another Machine's that had the name included, also answers 412 `precondition_failed`, and so does a bare revision (`\"\"`), whose `detail` says to upgrade @tonbo/cli to 0.9.0 or later (machine-v2.json `etag.bare_revision`). A Machine whose creation failed answers 409 `machine_failed` and does not change. A region where Machines are not offered answers 422 `region_not_offered`. A change to image, command, shape or env applies at the next activation; ports and `sleep_after_seconds` apply at once. A changed image follows the create's rule: the platform reference `tonbo.dev/platform` resolves nothing, and any other reference resolves to its canonical repository and linux/arm64 digest, or is refused before anything is written as the create refuses it (422 `image_platform_unsupported` or `validation_error`). Naming an image, the same one included, resolves it again and returns its `state` to `pulling`, so a failed pull is retried. Making a port public also needs `machines.public`. Refusals carry the codes and statuses of contracts/machines/machine-v2.json `errors`.", "x-tonbo-status": "enforced", "x-tonbo-capability": "machines.write", "x-tonbo-cli": "tonbo machine update", "security": [ { "MemberBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/MachineIfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "../machines/machine-v2.schema.json#/$defs/update" } } } }, "responses": { "200": { "description": "The Machine", "headers": { "ETag": { "$ref": "#/components/headers/MachineETag" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineEnvelope" } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/MachineRefused" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/MachineRefused" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RegionUnavailable" } } }, "delete": { "operationId": "deleteMachine", "tags": [ "Machines" ], "summary": "Delete a Machine", "description": "A managed Machine stops and is purged with its database and logs; its name is free at once for the account's next Machine, while its hostnames stay reserved to the account. The answer is 202 with the Machine being deleted, after which it is absent from the API, or 204 with no body when the name's create never reached its region and only the name was released. A region where Machines are not offered answers 422 `region_not_offered`, and one this server cannot reach 503 `region_unavailable`. A device (kind `byoc`) is forgotten instead, whatever `machines.open` says (contracts/machines/machine-v2.json `kinds.byoc.forget`): it is hidden and leaves the per-person cap at once, and its name is free once the forget drains; the answer is 202 with the device as it was, or 204 when its region held no row for it; a 204 names the kind in `X-Tonbo-Machine-Kind`. Forgetting a device that is not the caller's own (an Agent key's) also needs `api_keys.others` (`actions` `delete` `byoc_requires_also`), 403 otherwise. A device's key is not revoked: a device whose key is still active registers again at its next start. If-Match is optional; when sent it must be the Machine's current ETag (a device's is its id), or the answer is 412 `precondition_failed` and nothing is deleted, so a delete retried after the name was reused never deletes the new Machine. A name whose create never reached its region has no ETag to match.", "x-tonbo-status": "enforced", "x-tonbo-capability": "machines.write", "x-tonbo-cli": "tonbo machine delete", "security": [ { "MemberBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/MachineIfMatchOptional" } ], "responses": { "202": { "description": "The Machine, being deleted, or the device, forgotten", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineEnvelope" } } } }, "204": { "description": "The name was released, no Machine having been recorded under it, or the device was forgotten, its region holding no row for it", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Tonbo-Machine-Kind": { "description": "The kind of the Machine the name held, so that a client words a released name (`managed`) and a forgotten device (`byoc`) apart.", "required": true, "schema": { "$ref": "../machines/machine-v2.schema.json#/$defs/machine_kind" } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/MachineRefused" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RegionUnavailable" } } } }, "/machines/{name}/sleep": { "parameters": [ { "name": "name", "in": "path", "required": true, "description": "The Machine's name.", "schema": { "$ref": "../machines/machine-v2.schema.json#/$defs/name" } } ], "post": { "operationId": "sleepMachine", "tags": [ "Machines" ], "summary": "Put a Machine to sleep now", "description": "machine-controller applies the Machine's effective idle action (`status.sleep`). An asleep Machine wakes on its next connection; there is no wake operation. The answer is 202 while an activation runs, with `Retry-After`, the seconds to wait before reading the Machine again (machine-v2.json `sleep.poll_after_seconds`), until its `status.power` is `asleep`; and 200 with the Machine unchanged when there is nothing to do: it is asleep, or still being created. A Machine whose creation failed answers 409 `machine_failed`, and a device 409 `machine_kind_mismatch`, whatever `machines.open` says. A region where Machines are not offered answers 422 `region_not_offered`. If-Match is optional; when sent it must be the Machine's current ETag, or the answer is 412 `precondition_failed` and nothing changes.", "x-tonbo-status": "enforced", "x-tonbo-capability": "machines.write", "x-tonbo-cli": "tonbo machine sleep", "x-tonbo-idempotency": "none: a repeat requests the same sleep of the same Machine", "security": [ { "MemberBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/MachineIfMatchOptional" } ], "responses": { "200": { "description": "The Machine, unchanged, with nothing to do", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineEnvelope" } } } }, "202": { "description": "The Machine, going to sleep", "headers": { "Retry-After": { "description": "The seconds to wait before reading the Machine (getMachine) again, until its `status.power` is `asleep` (machine-v2.json `sleep.poll_after_seconds`).", "required": true, "schema": { "type": "integer", "minimum": 1 } }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineEnvelope" } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/MachineRefused" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/MachineRefused" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RegionUnavailable" } } } }, "/machines/{name}/activations": { "parameters": [ { "name": "name", "in": "path", "required": true, "description": "The Machine's name.", "schema": { "$ref": "../machines/machine-v2.schema.json#/$defs/name" } } ], "get": { "operationId": "listMachineActivations", "tags": [ "Machines" ], "summary": "List a Machine's activations", "description": "A managed Machine's activations, newest first: each boot or refused wake, with what woke it, the spec `revision` and `shape` it was admitted with, when, and its `end` (machine-v2.schema.json `$defs.activation_end`), null while it is live. An end's `reason` is why it ended: a refusal such as `payment_required` or `crash_backoff`, a stop such as `idle_early`, `sleep_after`, `workload_exited` (with the `exit_code` or `signal`) or `funding_stop`, or the node's. Any member reads it (`account.read`), whatever `machines.open` says; a narrowed key never does. A device answers 409 `machine_kind_mismatch`, and a region this server cannot reach 503 `region_unavailable`. The cursor is tied to the Machine, so it never pages another Machine that later takes the name.", "x-tonbo-status": "enforced", "x-tonbo-capability": "account.read", "x-tonbo-cli": "tonbo machine activations", "security": [ { "MemberBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Activations, newest first", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "../machines/machine-v2.schema.json#/$defs/activation_entry" } }, "next_cursor": { "$ref": "#/components/schemas/NextCursor" } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/MachineRefused" }, "422": { "$ref": "#/components/responses/MachineRefused" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RegionUnavailable" } } } }, "/machine-shapes": { "get": { "operationId": "listMachineShapes", "tags": [ "Machines" ], "summary": "List the Machine shapes", "description": "Every shape of contracts/machines/shapes-v1.json, with whether a Machine may name it now and its list price for an hour at full use, and the shape a client proposes by default. Served to any member whatever `machines.open` says; a narrowed key never reaches it.", "x-tonbo-status": "enforced", "x-tonbo-capability": "account.read", "x-tonbo-cli": "tonbo machine shapes", "security": [ { "MemberBearer": [] } ], "responses": { "200": { "description": "Shapes", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "default" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MachineShape" } }, "default": { "description": "shapes-v1.json `default`.", "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/volumes": { "get": { "operationId": "listVolumes", "tags": [ "Machines" ], "summary": "List the account's Volumes", "description": "The account's Volumes (contracts/machines/volume-v1.json) from every region, by name, including those being deleted until their purge ends; `unavailable_regions` names the regions whose Volumes could not be read. An account holds at most `quotas.volumes_per_account` Volumes, so the list is not paged. Served whatever `machines.open` says; a narrowed key never reaches a Volume.", "x-tonbo-status": "enforced", "x-tonbo-capability": "account.read", "x-tonbo-cli": "tonbo volume list", "security": [ { "MemberBearer": [] } ], "responses": { "200": { "description": "Volumes", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "unavailable_regions" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Volume" } }, "unavailable_regions": { "type": "array", "items": { "$ref": "#/components/schemas/RegionId" } } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "createVolume", "tags": [ "Machines" ], "summary": "Create a Volume", "description": "A Volume of `size_gib` (1 to 100, fixed for its life) in `region`, created `available`; a Machine of the same region binds it through its spec `volumes`. It needs `machines.write`, a region where Machines are offered to the account (422 `region_not_offered` otherwise) and the account's Volumes there (contracts/machines/volume-v1.json `flag`, the same 422 otherwise). An account whose credit is exhausted answers 402 `payment_required` and nothing is written. A name another live Volume of the account holds, in any region, answers 409 `conflict`, and so does the account's `quotas.volumes_per_account`-th Volume. The answer is 201 with the new Volume, and 200 when the same Idempotency-Key replays it; the key reused for another request answers 409. Both carry `Location`, the Volume's URL. Billing counts the Volume's live bytes, never its size.", "x-tonbo-status": "enforced", "x-tonbo-capability": "machines.write", "x-tonbo-cli": "tonbo volume create", "security": [ { "MemberBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "../machines/volume-v1.schema.json#/$defs/create" } } } }, "responses": { "200": { "description": "The Volume an earlier request with this Idempotency-Key created", "headers": { "Location": { "$ref": "#/components/headers/VolumeLocation" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VolumeEnvelope" } } } }, "201": { "description": "The new Volume", "headers": { "Location": { "$ref": "#/components/headers/VolumeLocation" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VolumeEnvelope" } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RegionUnavailable" } } } }, "/volumes/{name}": { "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "$ref": "../machines/machine-v2.schema.json#/$defs/name" } } ], "get": { "operationId": "getVolume", "tags": [ "Machines" ], "summary": "Read a Volume", "description": "A Volume of the account: the live one of the name, or else the latest being deleted. `machine` names the Machine it is bound to, `live_bytes` what the chunk-store meter bills and `last_commit_at` its last committed flush. A region this server cannot reach answers 503 `region_unavailable` when the Volume is in no region it read.", "x-tonbo-status": "enforced", "x-tonbo-capability": "account.read", "x-tonbo-cli": "tonbo volume show", "security": [ { "MemberBearer": [] } ], "responses": { "200": { "description": "The Volume", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VolumeEnvelope" } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RegionUnavailable" } } }, "delete": { "operationId": "deleteVolume", "tags": [ "Machines" ], "summary": "Delete a Volume", "description": "A Volume bound to a Machine answers 409 `conflict`: remove it from the Machine first (`volumes: []`). Otherwise the Volume enters `deleting` and is purged: its data key is destroyed first, then its objects and its ledger (contracts/machines/volume-v1.json `deletion`); its name is free at once. The answer is 202 with the Volume being deleted, and again for a Volume already deleting. There are no Volume snapshots or backups, so a deleted Volume cannot be recovered.", "x-tonbo-status": "enforced", "x-tonbo-capability": "machines.write", "x-tonbo-cli": "tonbo volume delete", "security": [ { "MemberBearer": [] } ], "responses": { "202": { "description": "The Volume, being deleted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VolumeEnvelope" } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RegionUnavailable" } } } }, "/streams": { "get": { "operationId": "listStreams", "tags": [ "Streams" ], "summary": "List the account's streams", "description": "Live raw streams (contracts/streams-databases/v1.json kinds whose `api` is streams), creating, active or deleting, in every region, by name. A key narrowed to streams sees only the streams it reaches, and a key narrowed to buckets, or by name to databases alone, sees none. `last_write_at` and `stored_bytes` come from each region's meter; `unavailable_regions` names the regions whose sizes could not be read, whose streams then show null sizes.", "x-tonbo-status": "enforced", "x-tonbo-capability": "account.read", "x-tonbo-cli": "tonbo stream list", "security": [ { "MemberBearer": [] } ], "parameters": [ { "name": "prefix", "in": "query", "description": "Only streams whose name starts with this prefix.", "schema": { "$ref": "#/components/schemas/StreamPrefix" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Streams", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "next_cursor", "unavailable_regions" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Stream" } }, "next_cursor": { "$ref": "#/components/schemas/NextCursor" }, "unavailable_regions": { "type": "array", "items": { "$ref": "#/components/schemas/RegionId" } } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "createStream", "tags": [ "Streams" ], "summary": "Create a stream", "description": "Any member creates streams; a narrowed key never does. A name is unique among the account's streams across every region while a stream holds it, and is free again once that stream is deleted; a stream and a database may share a name. The region is fixed at creation; without one, the stream goes to the region whose `default` is true for databases, since a stream lives in the same account bucket. The content type is fixed at creation (`application/octet-stream` when omitted) and every append must send exactly it. An optional `expires_at`, at least 60 seconds after the creation and fixed for the stream's life, has Tonbo delete the stream within a minute after it passes, as a deletion would; a replay is not held to the 60 seconds. The answer is 201 once the stream is active and 202 while it is still being created; read it again until it is active. A replay with the same Idempotency-Key answers the same stream; the key reused for another name, region, content type or expiry answers 409. An account holds at most `limits.streams_per_account` live streams (contracts/streams-databases/v1.json), counted apart from its databases; past that the answer is 403 and names whom to contact. An account whose credit is exhausted answers 402.", "x-tonbo-status": "enforced", "x-tonbo-capability": "streams.write", "x-tonbo-cli": "tonbo stream create", "security": [ { "MemberBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateStreamRequest" } } } }, "responses": { "201": { "description": "The stream, active", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Stream" } } } } } }, "202": { "description": "The stream, still being created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Stream" } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RegionUnavailable" } } } }, "/streams/{name}": { "parameters": [ { "name": "name", "in": "path", "required": true, "description": "The stream's name, without the `s.` its URL adds.", "schema": { "$ref": "#/components/schemas/StreamName" } } ], "get": { "operationId": "getStream", "tags": [ "Streams" ], "summary": "Read a stream", "description": "A live stream of the account, with its `url`, `content_type`, `expires_at` and `state`. A key narrowed to streams reads the streams it names and those under its prefixes; a key narrowed to buckets, or by name to databases alone, reads none. Any name a key does not reach answers 404 with the same status and body as a stream that does not exist.", "x-tonbo-status": "enforced", "x-tonbo-capability": "account.read", "x-tonbo-cli": "tonbo stream show", "security": [ { "MemberBearer": [] } ], "responses": { "200": { "description": "The stream", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Stream" } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "operationId": "updateStream", "tags": [ "Streams" ], "summary": "Publish a stream for anonymous reads, or take it private", "description": "Owners and admins, on an active stream. Anonymous readers reach only the stream's current incarnation, with GET and HEAD (reads, long-poll and SSE tails); they never append.", "x-tonbo-status": "enforced", "x-tonbo-capability": "streams.publish", "x-tonbo-cli": "tonbo stream update", "security": [ { "MemberBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateStreamRequest" } } } }, "responses": { "200": { "description": "The stream", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Stream" } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "deleteStream", "tags": [ "Streams" ], "summary": "Delete a stream and everything in it", "description": "Any member deletes streams; a narrowed key never does. The answer is 200 once the stream is deleted (`state` is `deleted`) and 202 while it is still being deleted. Its name is free again once it is deleted; its usage this month stays in `/usage/streams`. Repeating the request answers the stream being deleted.", "x-tonbo-status": "enforced", "x-tonbo-capability": "streams.write", "x-tonbo-cli": "tonbo stream delete", "security": [ { "MemberBearer": [] } ], "responses": { "200": { "description": "The stream, deleted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Stream" } } } } } }, "202": { "description": "The stream, being deleted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Stream" } } } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/usage/streams": { "get": { "operationId": "listStreamUsage", "tags": [ "Usage", "Streams" ], "summary": "Read each stream's usage of one month at list price", "description": "One row per stream version (name, stream creation time and counting history) metered in the month, in every region the account reaches, including streams deleted during the month, plus `other` for metered usage outside the account's streams (its databases, session processing and anything unattributed), so the rows and `other` add up to the account's metered total, as `/usage/databases` does for databases; no stream is a row of both. Values are at list price, before the monthly allowance and credit, which databases and streams share; Usage & billing (`/usage`) shows what is charged.", "x-tonbo-status": "enforced", "x-tonbo-capability": "usage.read", "x-tonbo-cli": "tonbo stream usage", "security": [ { "MemberBearer": [] } ], "parameters": [ { "name": "period", "in": "query", "description": "The calendar month in UTC; the current month when omitted.", "schema": { "type": "string", "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])$" } }, { "name": "sort", "in": "query", "description": "By list value, highest first (the default), or by name.", "schema": { "type": "string", "enum": [ "-list_value", "name" ], "default": "-list_value" } }, { "name": "prefix", "in": "query", "description": "Only streams whose name starts with this prefix.", "schema": { "$ref": "#/components/schemas/StreamPrefix" } }, { "name": "names", "in": "query", "description": "Only these streams, 1 to 100 stream names, comma-separated.", "schema": { "type": "string", "minLength": 1 } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Per-stream usage", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamUsagePage" } } } }, "401": { "$ref": "#/components/responses/MemberUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/agents/{agent_id}": { "parameters": [ { "$ref": "#/components/parameters/AgentId" } ], "get": { "operationId": "getAgent", "tags": [ "Agents" ], "summary": "Read the bound Agent", "security": [ { "AgentBearer": [] } ], "x-tonbo-action": "agents.read", "x-tonbo-status": "enforced", "responses": { "200": { "description": "Agent metadata", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/agents/{agent_id}/source-bundles/{sha256}": { "parameters": [ { "$ref": "#/components/parameters/AgentId" }, { "name": "sha256", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } ], "put": { "operationId": "prepareAgentSourceBundle", "tags": [ "Agents" ], "summary": "Reuse or prepare direct upload of the Agent source bundle", "x-tonbo-action": "agents.source_bundles.create", "x-tonbo-status": "enforced", "security": [ { "AgentBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "format", "size_bytes" ], "properties": { "format": { "type": "string", "const": "tar-v1" }, "size_bytes": { "type": "integer", "minimum": 1, "maximum": 67108864 } } } } } }, "responses": { "200": { "description": "Existing bundle or short-lived private upload target", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrepareAgentSourceBundleResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/agents/{agent_id}/source-bundles/{sha256}/complete": { "parameters": [ { "$ref": "#/components/parameters/AgentId" }, { "name": "sha256", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } ], "post": { "operationId": "completeAgentSourceBundle", "tags": [ "Agents" ], "summary": "Verify uploaded bytes and admit the Agent source bundle", "x-tonbo-action": "agents.source_bundles.create", "x-tonbo-status": "enforced", "security": [ { "AgentBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "format", "size_bytes" ], "properties": { "format": { "type": "string", "const": "tar-v1" }, "size_bytes": { "type": "integer", "minimum": 1, "maximum": 67108864 } } } } } }, "responses": { "201": { "description": "Bundle verified for this Agent", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AgentSourceDescriptor" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/agents/{agent_id}/deployments": { "parameters": [ { "$ref": "#/components/parameters/AgentId" } ], "get": { "operationId": "listAgentDeployments", "tags": [ "Agents" ], "summary": "List immutable Agent Deployments, newest first", "x-tonbo-action": "agents.deployments.read", "x-tonbo-status": "enforced", "security": [ { "AgentBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" }, { "name": "created_by", "in": "query", "required": false, "description": "Only Deployments created by this user.", "schema": { "$ref": "#/components/schemas/Uuid" } }, { "name": "state", "in": "query", "required": false, "description": "Only Deployments in this derived Production state.", "schema": { "$ref": "#/components/schemas/DeploymentProductionState" } } ], "responses": { "200": { "description": "Agent Deployment page", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AgentDeployment" } }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "createAgentDeployment", "tags": [ "Agents" ], "summary": "Create an immutable Agent Deployment from a verified source bundle", "description": "Every call creates a new Deployment, including one whose spec digest equals an earlier Deployment's. Creating a Deployment does not move Production; use putAgentProduction for that.", "x-tonbo-action": "agents.deployments.create", "x-tonbo-status": "enforced", "security": [ { "AgentBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentDeploymentRequest" } } } }, "responses": { "201": { "description": "Agent Deployment created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AgentDeployment" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/agents/{agent_id}/deployments/{deployment_id}": { "parameters": [ { "$ref": "#/components/parameters/AgentId" }, { "$ref": "#/components/parameters/DeploymentId" } ], "get": { "operationId": "getAgentDeployment", "tags": [ "Agents" ], "summary": "Read one immutable Agent Deployment", "x-tonbo-action": "agents.deployments.read", "x-tonbo-status": "enforced", "security": [ { "AgentBearer": [] } ], "responses": { "200": { "description": "Agent Deployment", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AgentDeployment" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/agents/{agent_id}/production": { "parameters": [ { "$ref": "#/components/parameters/AgentId" } ], "get": { "operationId": "getAgentProduction", "tags": [ "Agents" ], "summary": "Read the Agent's Production target and observed runtime state", "x-tonbo-action": "agents.production.read", "x-tonbo-status": "enforced", "security": [ { "AgentBearer": [] } ], "responses": { "200": { "description": "Agent Production", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AgentProduction" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "put": { "operationId": "putAgentProduction", "tags": [ "Agents" ], "summary": "Create or compare-and-swap the Agent's Production target", "description": "The single pointer-move primitive. Deploy, promote and rollback all name a Deployment here; moving Production to a different Deployment advances the rollout generation and records a Rollout whose kind the server derives. Naming the Deployment that is already Production only applies desired_state.", "x-tonbo-action": "agents.production.update", "x-tonbo-status": "enforced", "security": [ { "AgentBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutAgentProductionRequest" } } } }, "responses": { "200": { "description": "Desired Production state accepted", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AgentProduction" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/agents/{agent_id}/production/rollouts": { "parameters": [ { "$ref": "#/components/parameters/AgentId" } ], "get": { "operationId": "listAgentRollouts", "tags": [ "Agents" ], "summary": "List Production pointer moves, newest generation first", "x-tonbo-action": "agents.production.read", "x-tonbo-status": "enforced", "security": [ { "AgentBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Agent Rollout page", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AgentRollout" } }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/agents/{agent_id}/secrets": { "parameters": [ { "$ref": "#/components/parameters/AgentId" } ], "get": { "operationId": "listAgentSecrets", "tags": [ "Agents" ], "summary": "List Agent application-secret names without returning values", "x-tonbo-action": "agents.secrets.read", "x-tonbo-status": "enforced", "security": [ { "AgentBearer": [] } ], "responses": { "200": { "description": "Agent application-secret metadata", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AgentSecret" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/agents/{agent_id}/secrets/{name}": { "parameters": [ { "$ref": "#/components/parameters/AgentId" }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Z_][A-Z0-9_]{0,127}$" } } ], "put": { "operationId": "putAgentSecret", "tags": [ "Agents" ], "summary": "Create or replace one declared Agent application secret", "x-tonbo-action": "agents.secrets.write", "x-tonbo-status": "enforced", "security": [ { "AgentBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutAgentSecretRequest" } } } }, "responses": { "201": { "description": "Secret value stored; the value is never returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSecret" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteAgentSecret", "tags": [ "Agents" ], "summary": "Delete one Agent application secret", "x-tonbo-action": "agents.secrets.write", "x-tonbo-status": "enforced", "security": [ { "AgentBearer": [] } ], "responses": { "204": { "description": "Secret deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/agents/{agent_id}/sessions": { "parameters": [ { "$ref": "#/components/parameters/AgentId" } ], "post": { "operationId": "createAgentSession", "tags": [ "Agents" ], "summary": "Create a durable Session owned by the Agent", "x-tonbo-action": "agents.sessions.create", "x-tonbo-status": "enforced", "security": [ { "AgentBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentSessionRequest" } } } }, "responses": { "201": { "description": "Durable Agent Session created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AgentSession" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/agents/{agent_id}/sessions/{session_id}/turns": { "parameters": [ { "$ref": "#/components/parameters/AgentId" }, { "name": "session_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } } ], "post": { "operationId": "createAgentSessionTurn", "tags": [ "Agents" ], "summary": "Run one prompt against an existing durable Agent Session", "description": "Admits one Turn, identified by the Idempotency-Key UUID, and waits up to five minutes for it. Authority is evaluated once, at admission. Once admitted the Turn is a durable resource that the platform runs to its end for at most 60 minutes of execution (`turn_max_seconds` in `contracts/agents/turn-execution-v1.json`), after waiting at most 70 minutes to start when earlier Turns of the Agent are still running (`turn_start_max_seconds`). The caller does not need to stay connected, keep reading, or hold a valid token after admission. A running or waiting Turn stops only when it is aborted, its account enters deletion, its Agent is retired, the key that submitted it is revoked, its funding is exhausted, or it reaches its execution or start deadline; token or key expiry, key policy changes and membership changes apply only to later admissions. The answer is 200 with the result when the Turn completed within the wait, 409 `turn_failed` with its `failure_code` when it failed, and 202 with the operation and the Turn while it is still running. 409 `agent_busy` means the Agent already has the maximum number of Turns waiting to start and this Turn was not admitted; `turn_conflict` means the Turn id already names another prompt, Session or principal.", "x-tonbo-action": "agents.sessions.turns.create", "x-tonbo-status": "enforced", "security": [ { "AgentBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentSessionTurnRequest" } } } }, "responses": { "200": { "description": "Durable Agent turn completed", "headers": { "X-Operation-Id": { "$ref": "#/components/headers/OperationId" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AgentSessionTurn" } } } } } }, "202": { "$ref": "#/components/responses/OperationAccepted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/TurnConflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/agents/{agent_id}/sessions/{session_id}/turns/{turn_id}": { "parameters": [ { "$ref": "#/components/parameters/AgentId" }, { "name": "session_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "name": "turn_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } } ], "get": { "operationId": "getAgentSessionTurn", "tags": [ "Agents" ], "summary": "Read one durable Agent turn", "description": "Any key of the Agent that holds `agents.sessions.turns.read` can read the Turn, whichever key submitted it. Reading has no effect on execution.", "x-tonbo-action": "agents.sessions.turns.read", "x-tonbo-status": "enforced", "security": [ { "AgentBearer": [] } ], "responses": { "200": { "description": "The Turn's current state", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AgentTurn" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/agents/{agent_id}/sessions/{session_id}/turns/{turn_id}/events": { "parameters": [ { "$ref": "#/components/parameters/AgentId" }, { "name": "session_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "name": "turn_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } } ], "get": { "operationId": "listAgentSessionTurnEvents", "tags": [ "Agents" ], "summary": "Read the bounded channel-facing activity for one Agent turn", "x-tonbo-action": "agents.sessions.turns.read", "x-tonbo-status": "enforced", "security": [ { "AgentBearer": [] } ], "parameters": [ { "name": "after", "in": "query", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Ordered activity after the supplied sequence", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "status", "deadline_at", "failure_code" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AgentSessionTurnEvent" } }, "status": { "type": "string", "enum": [ "pending", "completed", "failed" ] }, "deadline_at": { "description": "End of the Turn's execution window; null until it starts executing.", "oneOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ] }, "failure_code": { "description": "The public failure code of a failed Turn; null otherwise.", "oneOf": [ { "$ref": "#/components/schemas/TurnFailureCode" }, { "type": "null" } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/agents/{agent_id}/sessions/{session_id}/turns/{turn_id}/abort": { "parameters": [ { "$ref": "#/components/parameters/AgentId" }, { "name": "session_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "name": "turn_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } } ], "post": { "operationId": "abortAgentSessionTurn", "tags": [ "Agents" ], "summary": "Abort a running durable Agent Session turn", "x-tonbo-action": "agents.sessions.turns.abort", "x-tonbo-status": "enforced", "security": [ { "AgentBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "$ref": "#/components/responses/OperationAccepted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/agents/{agent_id}/operations/{operation_id}": { "parameters": [ { "$ref": "#/components/parameters/AgentId" }, { "name": "operation_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } } ], "get": { "operationId": "getManagementOperation", "tags": [ "Operations" ], "summary": "Observe or reconnect to a durable control operation", "description": "Only the key that submitted the operation can read it, with any of its tokens, while the key is not revoked and the Agent is active. A Turn submission's operation represents the Turn's admission: once it admitted the Turn, it answers with the Turn's current state (200 with the result, 409 `turn_failed` with its `failure_code`, or 202 with the Turn while it runs). Every other finished operation, including a refused admission, answers with its original status and body.", "x-tonbo-action": "agents.read", "x-tonbo-status": "enforced", "security": [ { "AgentBearer": [] } ], "responses": { "200": { "description": "Terminal operation response with its original status and body, or the completed Turn a Turn submission admitted", "headers": { "X-Operation-Id": { "$ref": "#/components/headers/OperationId" } } }, "202": { "$ref": "#/components/responses/OperationAccepted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/TurnConflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/agents/{agent_id}/turns": { "parameters": [ { "$ref": "#/components/parameters/AgentId" } ], "post": { "operationId": "createAgentTurn", "tags": [ "Agents" ], "summary": "Create or resume a Session and run one authenticated Agent turn", "description": "Creates the Session when needed, then admits and waits for the Turn exactly as `createAgentSessionTurn` does.", "x-tonbo-action": "agents.sessions.turns.create", "x-tonbo-status": "enforced", "security": [ { "AgentBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "prompt" ], "properties": { "prompt": { "type": "string", "minLength": 1 }, "session_id": { "$ref": "#/components/schemas/Uuid" } } } } } }, "responses": { "200": { "description": "Durable Agent turn and its Session", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "turn_id", "session_id", "assistant_text", "session" ], "properties": { "turn_id": { "$ref": "#/components/schemas/Uuid" }, "session_id": { "$ref": "#/components/schemas/Uuid" }, "assistant_text": { "type": "string" }, "session": { "$ref": "#/components/schemas/AgentSession" } } } } } } } }, "202": { "$ref": "#/components/responses/OperationAccepted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/TurnConflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } } }, "components": { "securitySchemes": { "AgentBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Agent-key access token with the api.tonbo.dev audience." }, "MemberBearer": { "type": "http", "scheme": "bearer", "description": "A personal key (`tbo_…`) presented directly, or an access token exchanged from any key with the https://api.tonbo.dev audience. The key acts as its member with the member's current role and the key's narrowing, re-read on every request." } }, "parameters": { "AgentId": { "name": "agent_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, "DeploymentId": { "name": "deployment_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, "Cursor": { "name": "cursor", "in": "query", "schema": { "type": "string", "minLength": 1 }, "description": "Opaque cursor tied to the original query shape." }, "Limit": { "name": "limit", "in": "query", "description": "The most items one page holds, 1 to 200; 50 when omitted. A page may hold fewer; read on with `next_cursor` until it is null.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "A value you choose for this one creation, 1 to 255 characters, such as a new UUID. Send a new one for each resource you create, and the same one only to retry that request after a timeout or a lost answer: the retry answers what the first request created, in its current state, and never creates a second. A key reused for a different database, stream or Machine answers 409.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } }, "IfMatch": { "name": "If-Match", "in": "header", "required": false, "description": "Optional conditional update; omitted requests use last-write-wins.", "schema": { "type": "string", "maxLength": 500 } }, "MachineIfMatch": { "name": "If-Match", "in": "header", "required": true, "description": "The Machine's ETag as read, `\".\"` (contracts/machines/machine-v2.json `etag`); a Machine update is written only to that Machine at that revision. Required, because `env` and `ports` are replaced whole; a missing one answers 428 `precondition_required`.", "schema": { "type": "string", "maxLength": 500 } }, "MachineIfMatchOptional": { "name": "If-Match", "in": "header", "required": false, "description": "The Machine's ETag as read (contracts/machines/machine-v2.json `etag`); when sent, the request acts only on that Machine at that revision, and otherwise answers 412 `precondition_failed`.", "schema": { "type": "string", "maxLength": 500 } } }, "headers": { "RequestId": { "description": "Stable identifier for this request.", "schema": { "type": "string" } }, "ETag": { "description": "Current resource version for optional conditional updates.", "schema": { "type": "string" } }, "MachineETag": { "description": "The Machine's ETag, `\".\"` for a managed Machine and `\"\"` for a device (contracts/machines/machine-v2.json `etag`), opaque to clients. An update names it in If-Match, and a delete or a sleep may.", "schema": { "type": "string" } }, "VolumeLocation": { "description": "The Volume's URL, `https://api.tonbo.dev/v1/volumes/{name}`.", "required": true, "schema": { "type": "string", "format": "uri" } }, "MachineLocation": { "description": "The Machine's URL, `GET /v1/machines/{name}`.", "required": true, "schema": { "type": "string", "format": "uri" } }, "RetryAfter": { "description": "Seconds before the client should retry.", "schema": { "type": "integer", "minimum": 1 } }, "OperationId": { "description": "Durable operation identity used for reconnect and support correlation.", "schema": { "$ref": "#/components/schemas/Uuid" } } }, "responses": { "MemberUnauthorized": { "description": "Missing or invalid credentials (`unauthenticated`), or an Agent key presented directly (`exchange_required`): exchange it at `token_endpoint` and present the access token.", "headers": { "WWW-Authenticate": { "description": "Authentication scheme required by this API.", "schema": { "type": "string", "const": "Bearer" } }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://docs.tonbo.io/problems/exchange-required", "title": "Exchange required", "status": 401, "code": "exchange_required", "detail": "Agent keys are not accepted directly. Exchange the key for an access token at POST https://tonbo.dev/api/iam/token and present that token.", "token_endpoint": "https://tonbo.dev/api/iam/token", "request_id": "req_01K4K7N0JQD9M6V3YTZ2FKX0XW" } } } }, "OperationAccepted": { "description": "The durable operation remains pending or claimed, or it admitted a Turn that is still running (the body then carries `turn`); reconnect at Location.", "headers": { "Location": { "description": "Agent-scoped operation observation resource.", "schema": { "type": "string" } }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-Operation-Id": { "$ref": "#/components/headers/OperationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementOperationEnvelope" } } } }, "InsufficientCredit": { "description": "The Agent organization cannot reserve the full runtime lease", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "PaymentRequired": { "description": "The account's credit is exhausted (`payment_required`)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://docs.tonbo.io/problems/payment-required", "title": "Payment required", "status": 402, "code": "payment_required", "request_id": "req_01K4K7N0JQD9M6V3YTZ2FKX0XW" } } } }, "RegionUnavailable": { "description": "The region could not be reached or read; retry after `Retry-After` (`region_unavailable`). A region where the resource is not offered answers 422 `region_not_offered` instead.", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://docs.tonbo.io/problems/region-unavailable", "title": "The region is unavailable", "status": 503, "code": "region_unavailable", "request_id": "req_01K4K7N0JQD9M6V3YTZ2FKX0XW" } } } }, "MachineRefused": { "description": "A refusal whose `code` and status are one of contracts/machines/machine-v2.json `errors` (such as `name_taken`, `shape_not_offered`, `machine_failed` or `create_rate_limited`), or a shared one such as `region_not_offered` (422, Machines are not offered in the region named or defaulted), `forbidden`, `validation_error` or `rate_limited`. A 429 (`device_report_throttled`, `create_rate_limited`, `rate_limited`) carries Retry-After.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://docs.tonbo.io/problems/region-not-offered", "title": "Not offered in the region", "status": 422, "code": "region_not_offered", "detail": "Machines are not offered in any region yet.", "request_id": "req_01K4K7N0JQD9M6V3YTZ2FKX0XW", "errors": [ { "field": "region", "code": "invalid" } ] } } } }, "Unauthorized": { "description": "Missing or invalid bearer credentials", "headers": { "WWW-Authenticate": { "description": "Authentication scheme required by this API.", "schema": { "type": "string", "const": "Bearer" } }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://docs.tonbo.io/problems/unauthenticated", "title": "Authentication required", "status": 401, "code": "unauthenticated", "request_id": "req_01K4K7N0JQD9M6V3YTZ2FKX0XW" } } } }, "Forbidden": { "description": "The authenticated principal lacks the exact action", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://docs.tonbo.io/problems/forbidden", "title": "Permission denied", "status": 403, "code": "forbidden", "request_id": "req_01K4K7N0JQD9M6V3YTZ2FKX0XW" } } } }, "NotFound": { "description": "Resource not found or outside the principal's Agent", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://docs.tonbo.io/problems/not-found", "title": "Resource not found", "status": 404, "code": "not_found", "request_id": "req_01K4K7N0JQD9M6V3YTZ2FKX0XW" } } } }, "Conflict": { "description": "Resource or idempotency conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "TurnConflict": { "description": "The Turn failed (`turn_failed`, with `failure_code` and `detail`), was not admitted because the Agent has the maximum number of Turns waiting to start (`agent_busy`), or its id already names another prompt, Session or principal (`turn_conflict`); or an idempotency conflict.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Operation-Id": { "$ref": "#/components/headers/OperationId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://docs.tonbo.io/problems/turn-failed", "title": "Turn failed", "status": 409, "code": "turn_failed", "request_id": "req_01K4K7N0JQD9M6V3YTZ2FKX0XW", "failure_code": "deadline_exceeded", "detail": "Turn reached its execution deadline" } } } }, "PreconditionRequired": { "description": "The operation requires If-Match and the request has none (`precondition_required`, RFC 6585)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://docs.tonbo.io/problems/precondition-required", "title": "Precondition required", "status": 428, "code": "precondition_required", "detail": "An update needs If-Match with the Machine's ETag from GET /v1/machines/web.", "request_id": "req_01K4K7N0JQD9M6V3YTZ2FKX0XW" } } } }, "PreconditionFailed": { "description": "The supplied If-Match value is stale (`precondition_failed`)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://docs.tonbo.io/problems/precondition-failed", "title": "Resource version is stale", "status": 412, "code": "precondition_failed", "request_id": "req_01K4K7N0JQD9M6V3YTZ2FKX0XW" } } } }, "ValidationError": { "description": "Request validation failed", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://docs.tonbo.io/problems/validation-error", "title": "Request validation failed", "status": 422, "code": "validation_error", "request_id": "req_01K4K7N0JQD9M6V3YTZ2FKX0XW", "errors": [ { "field": "slug", "code": "invalid_format" } ] } } } }, "RateLimited": { "description": "Request rate limit exceeded", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "InternalError": { "description": "An unexpected internal error with no implementation detail", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://docs.tonbo.io/problems/internal-error", "title": "Internal server error", "status": 500, "code": "internal_error", "request_id": "req_01K4K7N0JQD9M6V3YTZ2FKX0XW" } } } } }, "schemas": { "BucketName": { "description": "Lowercase letters, digits and single hyphens, starting with a letter; it is the bucket's storage identity and appears in its URL.", "type": "string", "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$", "minLength": 4, "maxLength": 40 }, "Bucket": { "type": "object", "additionalProperties": false, "required": [ "name", "region", "url", "state", "public_read", "created_at" ], "properties": { "name": { "$ref": "#/components/schemas/BucketName" }, "region": { "type": "string" }, "url": { "description": "The bucket's data-plane address; a stream is at `{url}/{stream}`.", "type": "string", "format": "uri" }, "state": { "type": "string", "enum": [ "active", "deleting" ] }, "public_read": { "description": "Whether anonymous reads are served.", "type": "boolean" }, "created_at": { "$ref": "#/components/schemas/Timestamp" } } }, "CreateBucketRequest": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "$ref": "#/components/schemas/BucketName" }, "region": { "description": "The bucket's region; the account's default database region when omitted.", "type": "string" } } }, "UpdateBucketRequest": { "type": "object", "additionalProperties": false, "required": [ "public_read" ], "properties": { "public_read": { "type": "boolean" } } }, "DatabaseName": { "description": "A database's name (contracts/streams-databases/v1.json `name`): 1 to 85 lowercase letters, digits, dots, underscores and hyphens, starting and ending with a letter or digit, without `..`; `m.`, `vol.`, `s.`, `session.` and `proc.` are reserved, and `streams` and `new` (the console's create page) are not names. It appears unencoded in the database's URL and in key narrowing.", "type": "string", "minLength": 1, "maxLength": 85, "pattern": "^(?!m\\.)(?!vol\\.)(?!s\\.)(?!session\\.)(?!proc\\.)(?!(?:streams|new)$)(?!.*\\.\\.)[a-z0-9](?:[a-z0-9._-]{0,83}[a-z0-9])?$" }, "DatabasePrefix": { "description": "A database name prefix (contracts/streams-databases/v1.json `prefix`); it selects every name that starts with it.", "type": "string", "minLength": 1, "maxLength": 85, "pattern": "^(?!m\\.)(?!vol\\.)(?!s\\.)(?!session\\.)(?!proc\\.)[a-z0-9][a-z0-9._-]{0,84}$" }, "MachineDatabaseName": { "description": "A Machine's database, `m.` (contracts/streams-databases/v1.json `kinds.values.machine.name_pattern`). Control creates and deletes it with its Machine.", "type": "string", "pattern": "^m\\.([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$" }, "ListedDatabaseName": { "description": "The name of a row the databases API lists (contracts/streams-databases/v1.json kinds whose `api` is databases): a member's database or a Machine's.", "anyOf": [ { "$ref": "#/components/schemas/DatabaseName" }, { "$ref": "#/components/schemas/MachineDatabaseName" } ] }, "DatabaseKind": { "description": "The registry kind of a listed row (contracts/streams-databases/v1.json `kinds`). A `machine` row is managed by its Machine; deleting it or changing its visibility answers 409 `managed_by_machine`.", "type": "string", "enum": [ "database", "machine" ] }, "RegionId": { "description": "A region's id; `GET /v1/regions` lists the regions open to new resources.", "type": "string", "pattern": "^[a-z]{2}-[a-z]+-[0-9]$" }, "Database": { "type": "object", "additionalProperties": false, "required": [ "name", "kind", "owner_id", "region", "url", "expires_at", "incarnation", "state", "public_read", "created_at", "created_by", "last_write_at", "stored_bytes" ], "properties": { "name": { "description": "The database's name; a Machine's database is `m.`.", "$ref": "#/components/schemas/ListedDatabaseName" }, "kind": { "description": "`database` for one a member created, `machine` for a Machine's own, which its Machine creates and deletes.", "$ref": "#/components/schemas/DatabaseKind" }, "owner_id": { "description": "The Machine that owns a `machine` row; null for a member's database.", "oneOf": [ { "$ref": "#/components/schemas/Uuid" }, { "type": "null" } ] }, "region": { "description": "The region the database lives in, fixed for its life.", "$ref": "#/components/schemas/RegionId" }, "url": { "description": "The database's data-plane address, `{region's database origin}/{account id}/{name}`; open it with the SQLite on Ursula client.", "type": "string", "format": "uri" }, "expires_at": { "description": "When the database expires, fixed at creation; null when it never expires, and always for a Machine's database. Once it has passed, Tonbo deletes the database within a minute, as a deletion would, and its name is free again.", "oneOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ] }, "incarnation": { "description": "Ursula's Stream-Incarnation as a decimal; null while creating. A client that cached the URL resolves the database again when it changes.", "type": [ "string", "null" ], "pattern": "^(0|[1-9][0-9]{0,19})$" }, "state": { "description": "`deleted` appears only in the answer to the deletion that completed it.", "type": "string", "enum": [ "creating", "active", "deleting", "deleted" ] }, "public_read": { "description": "Whether anonymous reads are served.", "type": "boolean" }, "created_at": { "description": "When the database was created.", "$ref": "#/components/schemas/Timestamp" }, "created_by": { "description": "The member who created it, or for a Machine's database the member who created the Machine.", "$ref": "#/components/schemas/MemberSubject" }, "last_write_at": { "description": "The last write the region's meter saw, up to a minute behind; null until a host first opens it (an open writes; the create does not), and when its region is unavailable.", "oneOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ] }, "stored_bytes": { "description": "What the region's meter last saw stored; null when not yet reported or unavailable.", "type": "object", "additionalProperties": false, "required": [ "log", "snapshot" ], "properties": { "log": { "description": "Bytes of the database's retained log, as Tonbo stores it; null when not reported.", "type": [ "integer", "null" ], "minimum": 0 }, "snapshot": { "description": "Bytes of its snapshots; null when not reported.", "type": [ "integer", "null" ], "minimum": 0 } } }, "measured_at": { "description": "When the region's meter last read `last_write_at` and `stored_bytes` (every minute while it is healthy); null when the database is not yet metered or its region is unavailable. Optional; absent from older answers.", "oneOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ] }, "writes": { "description": "Whether Tonbo accepts writes to the database now. `suspended` while the account has no credit left, when writes answer 402 PAYMENT_REQUIRED and reads continue; writes resume shortly after a top-up. It is the account's state, the same for each of its databases and streams. Only in the answer for one database (show and update), never in a list; null when it could not be read.", "type": [ "string", "null" ], "enum": [ "accepting", "suspended", null ] } } }, "CreateDatabaseRequest": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "description": "The new database's name. 409 when a live database of the account in any region has it; a deleted database's name is free again.", "$ref": "#/components/schemas/DatabaseName", "examples": [ "notes" ] }, "region": { "description": "The database's region, fixed for its life; the region whose `default` is true when omitted. A region closed to databases answers 503.", "allOf": [ { "$ref": "#/components/schemas/RegionId" } ] }, "expires_at": { "description": "When the database expires, an RFC 3339 time, fixed for its life; it never expires when omitted. A new database's expiry must be at least 60 seconds after its creation by the registry's clock (422 on `expires_at` otherwise); a replay of the Idempotency-Key must name the same time and is answered however near or past that time is. Once it has passed, Tonbo deletes the database within a minute, as a deletion would.", "allOf": [ { "$ref": "#/components/schemas/Timestamp" } ] } } }, "UpdateDatabaseRequest": { "type": "object", "additionalProperties": false, "required": [ "public_read" ], "properties": { "public_read": { "description": "`true` publishes the database: anyone with its URL reads it without a key, and writes still need one. `false` makes it private again.", "type": "boolean" } } }, "DatabaseUsageAmounts": { "type": "object", "required": [ "write_units", "retention_gib_months", "snapshot_gib_months", "list_value_micros" ], "properties": { "write_units": { "description": "Write units, an integer as text.", "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "retention_gib_months": { "description": "The retained log in GiB-months (GiB = 1024^3 bytes, month = retention_month_seconds), a decimal as text.", "type": "string" }, "snapshot_gib_months": { "description": "Snapshots in GiB-months, a decimal as text; null when never reported.", "type": [ "string", "null" ] }, "list_value_micros": { "description": "The value at list price in micro-dollars, before allowance and credit.", "type": "integer", "minimum": 0 } } }, "DatabaseUsage": { "allOf": [ { "$ref": "#/components/schemas/DatabaseUsageAmounts" }, { "type": "object", "required": [ "name", "kind", "owner_id", "region", "stream_created_at", "counted_since", "state", "created_at", "deleted_at" ], "properties": { "name": { "description": "The database's name; a Machine's database is `m.`.", "$ref": "#/components/schemas/ListedDatabaseName" }, "kind": { "description": "`database` for one a member created, `machine` for a Machine's own.", "$ref": "#/components/schemas/DatabaseKind" }, "owner_id": { "description": "The Machine that owns a `machine` row, whose logs and inbox streams are added into it; null for a member's database.", "oneOf": [ { "$ref": "#/components/schemas/Uuid" }, { "type": "null" } ] }, "region": { "description": "The database's region.", "$ref": "#/components/schemas/RegionId" }, "stream_created_at": { "description": "When Ursula created the stream version; with `counted_since`, the version the row is.", "$ref": "#/components/schemas/Timestamp" }, "counted_since": { "description": "The Ursula usage history the version began counting in, 16 hex digits.", "type": "string", "pattern": "^[0-9a-f]{16}$" }, "state": { "description": "`active` while this version of the database exists, `deleted` once it was deleted; a deleted version's usage in the month still counts.", "type": "string", "enum": [ "active", "deleted" ] }, "created_at": { "description": "Null for a metered version the registry does not know.", "oneOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ] }, "deleted_at": { "description": "When this version was deleted; null while it is active.", "oneOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ] } } } ] }, "DatabaseUsagePage": { "type": "object", "additionalProperties": false, "required": [ "period", "as_of", "currency", "basis", "pricing", "data", "other", "next_cursor", "unavailable_regions" ], "properties": { "period": { "description": "The calendar month counted, in UTC; the `period` asked for, or the current month.", "type": "string", "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])$", "examples": [ "2026-11" ] }, "as_of": { "description": "The oldest meter checkpoint among the regions read; usage after it is not yet counted. Null before a region's first.", "oneOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ] }, "currency": { "description": "`usd`: every `_micros` value is in millionths of a US dollar.", "type": "string", "const": "usd" }, "basis": { "description": "Values are at list price, before the monthly allowance and credit apply; `GET /v1/usage` answers what the account is charged.", "type": "string", "const": "at_list_price_before_allowance_and_credit" }, "pricing": { "description": "The list prices of contracts/billing/streams-prices-v1.json the values use.", "type": "object", "additionalProperties": false, "required": [ "write_unit_bytes", "write_micros_per_million_units", "retention_micros_per_gib_month", "retention_unit_bytes", "retention_month_seconds" ], "properties": { "write_unit_bytes": { "description": "The bytes of one write unit. A write counts one unit for each started unit of its bytes, and at least one.", "type": "integer" }, "write_micros_per_million_units": { "description": "The price of a million write units, in micro-dollars.", "type": "integer" }, "retention_micros_per_gib_month": { "description": "The price of keeping one GiB for one month, in micro-dollars.", "type": "integer" }, "retention_unit_bytes": { "description": "The bytes of the GiB that price is quoted for, 1024^3.", "type": "integer" }, "retention_month_seconds": { "description": "The seconds of the month that price is quoted for, 30 days.", "type": "integer" } } }, "data": { "description": "One row per database version metered in the month, in the order `sort` names.", "type": "array", "items": { "$ref": "#/components/schemas/DatabaseUsage" } }, "other": { "description": "Metered usage outside the account's databases (its streams, session processing and anything unattributed), in every region read.", "$ref": "#/components/schemas/DatabaseUsageAmounts" }, "next_cursor": { "description": "The `cursor` of the next page, sent with the same other parameters; null on the last page.", "$ref": "#/components/schemas/NextCursor" }, "unavailable_regions": { "description": "Regions whose usage could not be read; their databases and `other` are missing from this answer.", "type": "array", "items": { "$ref": "#/components/schemas/RegionId" } } } }, "Machine": { "description": "A Machine as contracts/machines/machine-v2.schema.json defines it.", "$ref": "../machines/machine-v2.schema.json" }, "MemberDevice": { "description": "A member's device as an organization sees it (contracts/machines/machine-v2.json `kinds.byoc.projection.fields`).", "type": "object", "additionalProperties": false, "required": [ "member", "handle", "name", "harnesses", "online" ], "properties": { "member": { "type": "string", "format": "uuid", "description": "The person's subject." }, "handle": { "description": "The device's handle in this organization, or null when it has none.", "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "name": { "$ref": "../machines/machine-v2.schema.json#/$defs/name" }, "harnesses": { "$ref": "../machines/machine-v2.schema.json#/$defs/byoc_harnesses" }, "online": { "type": "boolean" } } }, "MachineEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "description": "The Machine.", "$ref": "#/components/schemas/Machine" } } }, "Volume": { "description": "A Volume as contracts/machines/volume-v1.schema.json `$defs.volume` defines it.", "$ref": "../machines/volume-v1.schema.json#/$defs/volume" }, "VolumeEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Volume" } } }, "MachineShape": { "description": "A shape of contracts/machines/shapes-v1.json `shapes`, whether a Machine may name it now, and its list price.", "type": "object", "additionalProperties": false, "required": [ "shape", "vcpus", "memory_gib", "scratch_gib", "offered", "suspendable", "ceiling_usd_micros_per_hour" ], "properties": { "shape": { "description": "The shape's name, which a Machine's `shape` names.", "$ref": "../machines/machine-v2.schema.json#/$defs/shape", "examples": [ "m-8" ] }, "vcpus": { "description": "The most vCPUs a Machine of this shape uses.", "type": "integer", "minimum": 1 }, "memory_gib": { "description": "The most memory a Machine of this shape uses, in GiB.", "type": "number", "exclusiveMinimum": 0 }, "scratch_gib": { "description": "The most scratch disk a Machine of this shape uses, in GiB.", "type": "number", "exclusiveMinimum": 0 }, "offered": { "description": "Whether a Machine may name this shape now; a shape not offered answers 422 `shape_not_offered`.", "type": "boolean" }, "suspendable": { "description": "Whether an idle Machine of this shape can suspend, keeping its memory to resume from. False while suspend is not offered, when an idle Machine is released instead.", "type": "boolean" }, "ceiling_usd_micros_per_hour": { "description": "The shape's list price for an hour at full use, in micros of USD: its vCPUs, memory and scratch disk at contracts/billing/machine-prices-v1.json's hourly prices. Billing charges what a Machine uses, never more than this.", "type": "integer", "minimum": 0 } } }, "StreamName": { "description": "A stream's name (contracts/streams-databases/v1.json `kinds.values.stream.name_pattern`'s capture group): the database name rule with at most 83 bytes, since its stream id is `s.` and the name. 1 to 83 lowercase letters, digits, dots, underscores and hyphens, starting and ending with a letter or digit, without `..`; `m.`, `vol.`, `s.`, `session.` and `proc.` are reserved, and `streams` and `new` are not names. It appears unencoded in the stream's URL after `s.`.", "type": "string", "minLength": 1, "maxLength": 83, "pattern": "^(?!m\\.)(?!vol\\.)(?!s\\.)(?!session\\.)(?!proc\\.)(?!(?:streams|new)$)(?!.*\\.\\.)[a-z0-9](?:[a-z0-9._-]{0,81}[a-z0-9])?$" }, "StreamPrefix": { "description": "A stream name prefix, under the name prefix rule (contracts/streams-databases/v1.json `prefix`); it selects every stream whose name starts with it.", "type": "string", "minLength": 1, "maxLength": 85, "pattern": "^(?!m\\.)(?!vol\\.)(?!s\\.)(?!session\\.)(?!proc\\.)[a-z0-9][a-z0-9._-]{0,84}$" }, "ContentType": { "description": "A stream's content type (contracts/streams-databases/v1.json `content_type`): one lowercase media type `type/subtype` without parameters, at most 127 bytes, never under `application/vnd.ursula.` (the formats Tonbo manages). It is the form Ursula normalizes a content type to, so every append sends exactly it; `application/json` streams are in JSON mode.", "type": "string", "minLength": 3, "maxLength": 127, "pattern": "^[a-z0-9][a-z0-9!#$&^_.+-]{0,62}/[a-z0-9][a-z0-9!#$&^_.+-]{0,62}$" }, "Stream": { "type": "object", "additionalProperties": false, "required": [ "name", "region", "url", "content_type", "expires_at", "incarnation", "state", "public_read", "created_at", "created_by", "last_write_at", "stored_bytes" ], "properties": { "name": { "description": "The stream's name, without the `s.` its URL adds.", "$ref": "#/components/schemas/StreamName" }, "region": { "description": "The region the stream lives in, fixed for its life.", "$ref": "#/components/schemas/RegionId" }, "url": { "description": "The stream's data-plane address, `{region's Streams origin}/{account id}/s.{name}` (contracts/streams-databases/v1.json `stream_url`); append, read, tail and close it with any Durable Streams client.", "type": "string", "format": "uri" }, "content_type": { "description": "The stream's content type, fixed at creation; every append sends exactly it.", "$ref": "#/components/schemas/ContentType" }, "expires_at": { "description": "When the stream expires, fixed at creation; null when it never expires. Once it has passed, Tonbo deletes the stream within a minute, as a deletion would, and its name is free again.", "oneOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ] }, "incarnation": { "description": "Ursula's Stream-Incarnation as a decimal; null while creating. It changes when a stream of the same name is deleted and created again.", "type": [ "string", "null" ], "pattern": "^(0|[1-9][0-9]{0,19})$" }, "state": { "description": "`deleted` appears only in the answer to the deletion that completed it.", "type": "string", "enum": [ "creating", "active", "deleting", "deleted" ] }, "public_read": { "description": "Whether anonymous reads are served.", "type": "boolean" }, "created_at": { "description": "When the stream was created.", "$ref": "#/components/schemas/Timestamp" }, "created_by": { "description": "The member who created it.", "$ref": "#/components/schemas/MemberSubject" }, "last_write_at": { "description": "The last write the region's meter saw, up to a minute behind; null before the first append (the create is not one), and when its region is unavailable.", "oneOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ] }, "stored_bytes": { "description": "What the region's meter last saw stored; null when not yet reported or unavailable.", "type": "object", "additionalProperties": false, "required": [ "log", "snapshot" ], "properties": { "log": { "description": "Bytes of the stream's retained messages, as Tonbo stores them; null when not reported.", "type": [ "integer", "null" ], "minimum": 0 }, "snapshot": { "description": "Bytes of its snapshots; null when not reported.", "type": [ "integer", "null" ], "minimum": 0 } } }, "measured_at": { "description": "When the region's meter last read `last_write_at` and `stored_bytes` (every minute while it is healthy); null when the stream is not yet metered or its region is unavailable. Optional; absent from older answers.", "oneOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ] }, "writes": { "description": "Whether Tonbo accepts writes to the stream now. `suspended` while the account has no credit left, when writes answer 402 PAYMENT_REQUIRED and reads continue; writes resume shortly after a top-up. It is the account's state, the same for each of its databases and streams. Only in the answer for one stream (show and update), never in a list; null when it could not be read.", "type": [ "string", "null" ], "enum": [ "accepting", "suspended", null ] } } }, "CreateStreamRequest": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "description": "The new stream's name, which its URL shows after `s.`. 409 when a live stream of the account in any region has it; a deleted stream's name is free again.", "$ref": "#/components/schemas/StreamName", "examples": [ "events" ] }, "region": { "description": "The stream's region, fixed for its life; the region whose `default` is true when omitted. A region closed to databases, and so to streams, answers 503.", "allOf": [ { "$ref": "#/components/schemas/RegionId" } ] }, "content_type": { "description": "The stream's content type, fixed for its life; `application/octet-stream` when omitted.", "allOf": [ { "$ref": "#/components/schemas/ContentType" } ] }, "expires_at": { "description": "When the stream expires, an RFC 3339 time, fixed for its life; it never expires when omitted. A new stream's expiry must be at least 60 seconds after its creation by the registry's clock (422 on `expires_at` otherwise); a replay of the Idempotency-Key must name the same time and is answered however near or past that time is. Once it has passed, Tonbo deletes the stream within a minute, as a deletion would.", "allOf": [ { "$ref": "#/components/schemas/Timestamp" } ] } } }, "UpdateStreamRequest": { "type": "object", "additionalProperties": false, "required": [ "public_read" ], "properties": { "public_read": { "description": "`true` publishes the stream: anyone with its URL reads and tails it without a key, and appends still need one. `false` makes it private again.", "type": "boolean" } } }, "StreamUsage": { "allOf": [ { "$ref": "#/components/schemas/DatabaseUsageAmounts" }, { "type": "object", "required": [ "name", "region", "stream_created_at", "counted_since", "state", "created_at", "deleted_at" ], "properties": { "name": { "description": "The stream's name, without `s.`.", "$ref": "#/components/schemas/StreamName" }, "region": { "description": "The stream's region.", "$ref": "#/components/schemas/RegionId" }, "stream_created_at": { "description": "When Ursula created the stream version; with `counted_since`, the version the row is.", "$ref": "#/components/schemas/Timestamp" }, "counted_since": { "description": "The Ursula usage history the version began counting in, 16 hex digits.", "type": "string", "pattern": "^[0-9a-f]{16}$" }, "state": { "description": "`active` while this version of the stream exists, `deleted` once it was deleted; a deleted version's usage in the month still counts.", "type": "string", "enum": [ "active", "deleted" ] }, "created_at": { "description": "Null for a metered version the registry does not know.", "oneOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ] }, "deleted_at": { "description": "When this version was deleted; null while it is active.", "oneOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ] } } } ] }, "StreamUsagePage": { "type": "object", "additionalProperties": false, "required": [ "period", "as_of", "currency", "basis", "pricing", "data", "other", "next_cursor", "unavailable_regions" ], "properties": { "period": { "description": "The calendar month counted, in UTC; the `period` asked for, or the current month.", "type": "string", "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])$", "examples": [ "2026-11" ] }, "as_of": { "description": "The oldest meter checkpoint among the regions read; usage after it is not yet counted. Null before a region's first.", "oneOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ] }, "currency": { "description": "`usd`: every `_micros` value is in millionths of a US dollar.", "type": "string", "const": "usd" }, "basis": { "description": "Values are at list price, before the monthly allowance and credit apply; `GET /v1/usage` answers what the account is charged.", "type": "string", "const": "at_list_price_before_allowance_and_credit" }, "pricing": { "description": "The list prices of contracts/billing/streams-prices-v1.json the values use.", "type": "object", "additionalProperties": false, "required": [ "write_unit_bytes", "write_micros_per_million_units", "retention_micros_per_gib_month", "retention_unit_bytes", "retention_month_seconds" ], "properties": { "write_unit_bytes": { "description": "The bytes of one write unit. A write counts one unit for each started unit of its bytes, and at least one.", "type": "integer" }, "write_micros_per_million_units": { "description": "The price of a million write units, in micro-dollars.", "type": "integer" }, "retention_micros_per_gib_month": { "description": "The price of keeping one GiB for one month, in micro-dollars.", "type": "integer" }, "retention_unit_bytes": { "description": "The bytes of the GiB that price is quoted for, 1024^3.", "type": "integer" }, "retention_month_seconds": { "description": "The seconds of the month that price is quoted for, 30 days.", "type": "integer" } } }, "data": { "description": "One row per stream version metered in the month, in the order `sort` names.", "type": "array", "items": { "$ref": "#/components/schemas/StreamUsage" } }, "other": { "description": "Metered usage outside the account's streams (its databases, session processing and anything unattributed), in every region read.", "$ref": "#/components/schemas/DatabaseUsageAmounts" }, "next_cursor": { "description": "The `cursor` of the next page, sent with the same other parameters; null on the last page.", "$ref": "#/components/schemas/NextCursor" }, "unavailable_regions": { "description": "Regions whose usage could not be read; their streams and `other` are missing from this answer.", "type": "array", "items": { "$ref": "#/components/schemas/RegionId" } } } }, "AccountRole": { "description": "A member's role in the account. A `member` reads the account, creates and deletes databases, streams and Machines, and manages their own keys. An `admin` also publishes databases and streams, changes members, creates Agents and their keys, revokes others' keys and reads usage. An `owner` also buys credit and grants `owner`. contracts/iam/account-roles-v1.json is the full table.", "type": "string", "enum": [ "owner", "admin", "member" ] }, "MemberSubject": { "description": "A person's user id, or `agent.` for an Agent; the `sub` of its access tokens.", "type": "string", "pattern": "^[a-z0-9._-]{1,64}$", "examples": [ "agent.3f1c2a9e-5b7d-4c8e-9f10-2a3b4c5d6e7f" ] }, "NextCursor": { "description": "Opaque cursor of the next page; null on the last page.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "Account": { "type": "object", "additionalProperties": false, "required": [ "id", "kind", "name", "member", "limits" ], "properties": { "id": { "description": "The account's id; a database's and a stream's URL name it after the region's origin.", "$ref": "#/components/schemas/Uuid" }, "kind": { "description": "`user` for a person's own account, `organization` for an organization's.", "type": "string", "enum": [ "user", "organization" ] }, "name": { "description": "The account's name as the console shows it.", "type": "string" }, "member": { "description": "The caller's own membership.", "type": "object", "additionalProperties": false, "required": [ "kind", "subject", "role" ], "properties": { "kind": { "description": "`user` when the key acts as a person, `agent` when it acts as an Agent.", "type": "string", "enum": [ "user", "agent" ] }, "subject": { "description": "Who the key acts as, a user id or `agent.`.", "$ref": "#/components/schemas/MemberSubject" }, "role": { "description": "The caller's current role, which decides what the key may do.", "$ref": "#/components/schemas/AccountRole" } } }, "limits": { "description": "How much of each resource the account may hold.", "type": "object", "additionalProperties": false, "required": [ "buckets" ], "properties": { "buckets": { "description": "Live buckets the account may hold.", "type": "integer", "minimum": 0 } } } } }, "Region": { "type": "object", "additionalProperties": false, "required": [ "id", "url", "default" ], "properties": { "id": { "description": "The region's id, which a creation names as `region`.", "$ref": "#/components/schemas/RegionId" }, "url": { "description": "The origin of the data plane in this region; a database's URL is this origin, the account id and the database name, and a bucket's is this origin and the bucket name.", "type": "string", "format": "uri" }, "default": { "description": "Whether a database goes to this region when its creation names none.", "type": "boolean" } } }, "SessionsStore": { "type": "object", "additionalProperties": false, "required": [ "bucket", "region", "url", "workspace_id", "agent_id" ], "properties": { "bucket": { "description": "The account's database bucket, named by the account id, which holds the account's session store (docs/design/session-store-fold.md).", "type": "string", "format": "uuid" }, "region": { "description": "The store's cell, recorded once at the account's first discovery and never moved.", "type": "string" }, "url": { "description": "That cell's Streams origin; a stream is at `{url}/{bucket}/{stream}`.", "type": "string", "format": "uri" }, "workspace_id": { "description": "The account's default git workspace, where the capture client's snapshots and recall live; its id without hyphens is the `` of their URLs, and the git token the client exchanges without naming a workspace is bound to it.", "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[47][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" }, "agent_id": { "description": "Deprecated, the same id as `workspace_id`, for `@tonbo/yield` 0.1.0, which reads its git workspace from this field; removed with ADR-0016 PR 6.", "deprecated": true, "type": "string", "format": "uuid" } } }, "Member": { "type": "object", "additionalProperties": false, "required": [ "kind", "subject", "role", "name", "display_name", "created_at" ], "properties": { "kind": { "description": "`user` for a person, `agent` for an Agent.", "type": "string", "enum": [ "user", "agent" ] }, "subject": { "description": "The member's id in the account, which `PATCH /v1/members/{subject}` names.", "$ref": "#/components/schemas/MemberSubject" }, "role": { "description": "The member's role.", "$ref": "#/components/schemas/AccountRole" }, "name": { "description": "A person's username, or the Agent's name; null when the person has none.", "type": [ "string", "null" ] }, "display_name": { "description": "A person's display name, or the Agent's name; null when the person has none.", "type": [ "string", "null" ] }, "created_at": { "description": "When the person or Agent joined the account.", "$ref": "#/components/schemas/Timestamp" } } }, "GitWorkspace": { "type": "object", "additionalProperties": false, "required": [ "id", "ws_hex", "name", "default", "region", "git_origin", "state", "created_at" ], "properties": { "id": { "description": "The workspace id, a lowercase hyphenated UUID of version 4 (a default backfilled from a designated git Agent's id) or 7.", "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[47][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" }, "ws_hex": { "description": "The id without hyphens, the `` of git resources and of gitd's paths.", "type": "string", "pattern": "^[0-9a-f]{32}$" }, "name": { "description": "The member-chosen name; null for an account's default.", "type": [ "string", "null" ] }, "default": { "description": "Whether this is the account's default workspace.", "type": "boolean" }, "region": { "description": "The workspace's git cell, recorded once and never changed.", "type": "string" }, "git_origin": { "description": "That cell's git origin; a repository is at `{git_origin}/{ws_hex}/{repo}.git`.", "type": "string", "format": "uri" }, "state": { "description": "live, or purging while its account's deletion purges it.", "type": "string", "enum": [ "live", "purging" ] }, "created_at": { "$ref": "#/components/schemas/Timestamp" } } }, "SessionProject": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "git_origin", "snapshot_repo", "workspace_id" ], "properties": { "id": { "$ref": "#/components/schemas/Uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "git_origin": { "description": "The origin key the Project groups clones by (@tonbo/project-naming); null for a Project the person named.", "type": [ "string", "null" ] }, "snapshot_repo": { "description": "The repository in the Project's workspace its snapshots go to, fixed at its creation.", "type": "string", "pattern": "^snap-[A-Za-z0-9._-]{1,100}$" }, "workspace_id": { "$ref": "#/components/schemas/Uuid" } } }, "SessionProjectBinding": { "type": "object", "additionalProperties": false, "required": [ "id", "folder_id", "project", "device_handle", "bound_at" ], "properties": { "id": { "description": "The binding id, a random UUIDv4 that names the folder in snapshot refs and published records.", "allOf": [ { "$ref": "#/components/schemas/Uuid" } ] }, "folder_id": { "description": "The random id the daemon keeps for the folder.", "type": "string", "pattern": "^[0-9a-f]{32}$" }, "project": { "$ref": "#/components/schemas/SessionProject" }, "device_handle": { "description": "The device's handle in the Project's organization; null for a personal Project.", "oneOf": [ { "$ref": "#/components/schemas/Uuid" }, { "type": "null" } ] }, "bound_at": { "$ref": "#/components/schemas/Timestamp" } } }, "CreatePersonalHandoffRequest": { "description": "A person target names target_sub, a current member, in a team Project; omitted, or in a personal account, it is the author. A machine target dispatches the handoff to one of the author's own devices (a byoc Machine of their personal account), from a personal Project only, and names its harness; that device's daemon alone takes it. The server fixes the pin lease to 30 days.", "type": "object", "additionalProperties": false, "required": [ "device_id", "binding_id", "session_id", "task", "snapshot_sha", "pin_id", "target_kind" ], "properties": { "device_id": { "$ref": "#/components/schemas/Uuid" }, "binding_id": { "$ref": "#/components/schemas/Uuid" }, "session_id": { "$ref": "#/components/schemas/Uuid" }, "task": { "type": "string", "minLength": 1, "maxLength": 10000 }, "snapshot_sha": { "type": "string", "pattern": "^[0-9a-f]{40}$" }, "base_sha": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{40}$" }, "pin_id": { "$ref": "#/components/schemas/Uuid" }, "target_kind": { "type": "string", "enum": [ "open", "person", "agent", "machine" ] }, "target_sub": { "description": "A person target's member id; only with target_kind person.", "oneOf": [ { "$ref": "#/components/schemas/Uuid" }, { "type": "null" } ] }, "target_harness": { "type": [ "string", "null" ], "enum": [ "claude-code", "codex", null ] }, "target_machine_id": { "description": "A machine target's Machine, one of the author's own devices; only with target_kind machine.", "oneOf": [ { "$ref": "#/components/schemas/Uuid" }, { "type": "null" } ] }, "context_excerpt": { "description": "A team handoff's excerpt of its session's recent turns, secret-filtered by the author's client (ADR-0017's metadata-only amendment, M-3). Only the author and the claimant receive it back, from take. Refused on a personal handoff.", "type": [ "string", "null" ], "minLength": 1, "maxLength": 65536 } }, "allOf": [ { "if": { "properties": { "target_kind": { "enum": [ "agent", "machine" ] } } }, "then": { "required": [ "target_harness" ], "properties": { "target_harness": { "type": "string", "enum": [ "claude-code", "codex" ] } } }, "else": { "properties": { "target_harness": { "type": "null" } } } }, { "if": { "properties": { "target_kind": { "const": "machine" } } }, "then": { "required": [ "target_machine_id" ], "properties": { "target_machine_id": { "$ref": "#/components/schemas/Uuid" } } }, "else": { "properties": { "target_machine_id": { "type": "null" } } } } ] }, "PersonalHandoffCreated": { "type": "object", "additionalProperties": false, "required": [ "id", "state", "link", "snapshot_pin_id", "snapshot_pin_expires_at" ], "properties": { "id": { "$ref": "#/components/schemas/Uuid" }, "state": { "type": "string", "enum": [ "created", "claimed", "running", "done", "need_human", "failed", "cancelled" ] }, "link": { "type": "string", "format": "uri" }, "snapshot_pin_id": { "$ref": "#/components/schemas/Uuid" }, "snapshot_pin_expires_at": { "$ref": "#/components/schemas/Timestamp" } } }, "HandoffListItem": { "type": "object", "additionalProperties": false, "required": [ "id", "link", "account_id", "state", "task", "session_id", "author_sub", "target_kind", "target_sub", "target_machine_id", "target_harness", "claimed_by_sub", "updated_at" ], "properties": { "id": { "$ref": "#/components/schemas/Uuid" }, "link": { "type": "string", "format": "uri" }, "account_id": { "$ref": "#/components/schemas/Uuid" }, "state": { "type": "string", "enum": [ "created", "claimed", "running", "need_human" ] }, "task": { "type": "string" }, "session_id": { "$ref": "#/components/schemas/Uuid" }, "author_sub": { "$ref": "#/components/schemas/Uuid" }, "target_kind": { "type": "string", "enum": [ "open", "person", "agent", "machine" ] }, "target_machine_id": { "oneOf": [ { "$ref": "#/components/schemas/Uuid" }, { "type": "null" } ] }, "target_sub": { "oneOf": [ { "$ref": "#/components/schemas/Uuid" }, { "type": "null" } ] }, "target_harness": { "oneOf": [ { "type": "string", "enum": [ "claude-code", "codex" ] }, { "type": "null" } ] }, "claimed_by_sub": { "oneOf": [ { "$ref": "#/components/schemas/Uuid" }, { "type": "null" } ] }, "updated_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } }, "HandoffEvent": { "type": "object", "additionalProperties": false, "required": [ "seq", "handoff_id", "link", "account_id", "kind", "actor_sub", "at", "task", "state", "author_sub", "target_kind", "target_sub", "target_machine_id", "claimed_by_sub" ], "properties": { "seq": { "type": "integer", "minimum": 1 }, "handoff_id": { "$ref": "#/components/schemas/Uuid" }, "link": { "type": "string", "format": "uri" }, "account_id": { "$ref": "#/components/schemas/Uuid" }, "kind": { "type": "string", "enum": [ "created", "claimed", "running", "done", "need_human", "failed", "returned", "cancelled" ] }, "actor_sub": { "oneOf": [ { "$ref": "#/components/schemas/Uuid" }, { "type": "null" } ] }, "at": { "type": "string", "format": "date-time" }, "task": { "type": "string" }, "state": { "type": "string", "enum": [ "created", "claimed", "running", "done", "need_human", "failed", "cancelled" ] }, "author_sub": { "$ref": "#/components/schemas/Uuid" }, "target_kind": { "type": "string", "enum": [ "open", "person", "agent", "machine" ] }, "target_machine_id": { "oneOf": [ { "$ref": "#/components/schemas/Uuid" }, { "type": "null" } ] }, "target_sub": { "oneOf": [ { "$ref": "#/components/schemas/Uuid" }, { "type": "null" } ] }, "claimed_by_sub": { "oneOf": [ { "$ref": "#/components/schemas/Uuid" }, { "type": "null" } ] } } }, "PersonalHandoffView": { "type": "object", "additionalProperties": false, "required": [ "id", "state", "link", "author_sub", "target_kind", "target_sub", "target_machine_id", "claimed_by_sub", "session_id", "task", "snapshot_repo", "snapshot_workspace_id", "snapshot_sha", "snapshot_ref", "snapshot_pin_expires_at", "base_sha", "restored_at", "result", "result_snapshot_sha", "result_snapshot_pin_expires_at", "result_pulled_at" ], "properties": { "id": { "$ref": "#/components/schemas/Uuid" }, "state": { "type": "string", "enum": [ "created", "claimed", "running", "done", "need_human", "failed", "cancelled" ] }, "link": { "type": "string", "format": "uri" }, "author_sub": { "$ref": "#/components/schemas/Uuid" }, "target_kind": { "type": "string", "enum": [ "open", "person", "agent", "machine" ] }, "target_machine_id": { "oneOf": [ { "$ref": "#/components/schemas/Uuid" }, { "type": "null" } ] }, "target_sub": { "oneOf": [ { "$ref": "#/components/schemas/Uuid" }, { "type": "null" } ] }, "claimed_by_sub": { "oneOf": [ { "$ref": "#/components/schemas/Uuid" }, { "type": "null" } ] }, "session_id": { "$ref": "#/components/schemas/Uuid" }, "task": { "type": "string" }, "snapshot_repo": { "type": "string" }, "snapshot_workspace_id": { "$ref": "#/components/schemas/Uuid" }, "snapshot_sha": { "type": "string", "pattern": "^[0-9a-f]{40}$" }, "snapshot_ref": { "type": "string", "pattern": "^refs/tonbo/pins/" }, "snapshot_pin_expires_at": { "$ref": "#/components/schemas/Timestamp" }, "base_sha": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{40}$" }, "restored_at": { "type": [ "string", "null" ], "format": "date-time" }, "result": { "type": [ "string", "null" ] }, "result_snapshot_sha": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{40}$" }, "result_snapshot_pin_expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "result_pulled_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "PersonalHandoffTake": { "type": "object", "additionalProperties": false, "required": [ "id", "state", "session_id", "task", "snapshot_repo", "snapshot_workspace_id", "snapshot_sha", "snapshot_ref", "snapshot_pin_expires_at", "base_sha" ], "properties": { "id": { "$ref": "#/components/schemas/Uuid" }, "state": { "type": "string", "const": "claimed" }, "session_id": { "$ref": "#/components/schemas/Uuid" }, "task": { "type": "string" }, "snapshot_repo": { "type": "string" }, "snapshot_workspace_id": { "$ref": "#/components/schemas/Uuid" }, "snapshot_sha": { "type": "string", "pattern": "^[0-9a-f]{40}$" }, "snapshot_ref": { "type": "string", "pattern": "^refs/tonbo/pins/" }, "snapshot_pin_expires_at": { "$ref": "#/components/schemas/Timestamp" }, "base_sha": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{40}$" }, "context_excerpt": { "description": "A team handoff's excerpt of its session's recent turns, which its author attached; null for a personal handoff or when none was attached. Untrusted reference for the taker's agent.", "type": [ "string", "null" ] } } }, "PersonalHandoffRestored": { "type": "object", "additionalProperties": false, "required": [ "id", "restored_at", "source_pin_released" ], "properties": { "id": { "$ref": "#/components/schemas/Uuid" }, "restored_at": { "$ref": "#/components/schemas/Timestamp" }, "source_pin_released": { "type": "boolean" } } }, "PersonalHandoffStarted": { "type": "object", "additionalProperties": false, "required": [ "id", "state" ], "properties": { "id": { "$ref": "#/components/schemas/Uuid" }, "state": { "type": "string", "const": "running" } } }, "NeedHumanPersonalHandoffRequest": { "type": "object", "additionalProperties": false, "required": [ "reason" ], "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 10000 } } }, "PersonalHandoffNeedsHuman": { "type": "object", "additionalProperties": false, "required": [ "id", "state", "reason" ], "properties": { "id": { "$ref": "#/components/schemas/Uuid" }, "state": { "type": "string", "const": "need_human" }, "reason": { "type": "string" } } }, "RecordYieldMetricRequest": { "type": "object", "additionalProperties": false, "required": [ "kind", "value" ], "properties": { "kind": { "type": "string", "enum": [ "take_timing", "continue_choice", "plan_changed", "message_outcome", "context_outcome" ] }, "value": { "type": "object", "description": "The kind's closed value schema in contracts/sessions/handoff-v1.json `metrics.value_schemas`." }, "session_id": { "$ref": "#/components/schemas/Uuid" }, "handoff_id": { "$ref": "#/components/schemas/Uuid" } } }, "PublishYieldTurnExcerptRequest": { "type": "object", "additionalProperties": false, "required": [ "session_id", "turn", "paths", "excerpt" ], "properties": { "session_id": { "$ref": "#/components/schemas/Uuid" }, "turn": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "paths": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "minLength": 1, "maxLength": 4096 } }, "excerpt": { "type": "string", "minLength": 1, "maxLength": 16384 } } }, "YieldMetricRecorded": { "type": "object", "additionalProperties": false, "required": [ "id", "kind" ], "properties": { "id": { "$ref": "#/components/schemas/Uuid" }, "kind": { "type": "string" } } }, "PersonalHandoffCancelled": { "type": "object", "additionalProperties": false, "required": [ "id", "state", "source_pin_released" ], "properties": { "id": { "$ref": "#/components/schemas/Uuid" }, "state": { "type": "string", "const": "cancelled" }, "source_pin_released": { "type": "boolean", "const": true } } }, "PersonalHandoffSourceRenewed": { "type": "object", "additionalProperties": false, "required": [ "snapshot_pin_id", "snapshot_pin_expires_at" ], "properties": { "snapshot_pin_id": { "$ref": "#/components/schemas/Uuid" }, "snapshot_pin_expires_at": { "$ref": "#/components/schemas/Timestamp" } } }, "FinishPersonalHandoffRequest": { "type": "object", "additionalProperties": false, "required": [ "result", "snapshot_sha", "pin_id" ], "properties": { "result": { "type": "string", "minLength": 1, "maxLength": 10000 }, "snapshot_sha": { "type": "string", "pattern": "^[0-9a-f]{40}$" }, "pin_id": { "$ref": "#/components/schemas/Uuid" } } }, "PersonalHandoffDone": { "type": "object", "additionalProperties": false, "required": [ "id", "state", "result_snapshot_pin_id", "result_snapshot_pin_expires_at" ], "properties": { "id": { "$ref": "#/components/schemas/Uuid" }, "state": { "type": "string", "const": "done" }, "result_snapshot_pin_id": { "$ref": "#/components/schemas/Uuid" }, "result_snapshot_pin_expires_at": { "$ref": "#/components/schemas/Timestamp" } } }, "PersonalHandoffResult": { "type": "object", "additionalProperties": false, "required": [ "id", "result", "snapshot_repo", "snapshot_workspace_id", "source_snapshot_sha", "result_snapshot_sha", "result_snapshot_ref", "result_snapshot_pin_expires_at" ], "properties": { "id": { "$ref": "#/components/schemas/Uuid" }, "result": { "type": "string" }, "snapshot_repo": { "type": "string" }, "snapshot_workspace_id": { "$ref": "#/components/schemas/Uuid" }, "source_snapshot_sha": { "type": "string", "pattern": "^[0-9a-f]{40}$" }, "result_snapshot_sha": { "type": "string", "pattern": "^[0-9a-f]{40}$" }, "result_snapshot_ref": { "type": "string", "pattern": "^refs/tonbo/pins/" }, "result_snapshot_pin_expires_at": { "$ref": "#/components/schemas/Timestamp" } } }, "PersonalHandoffPulled": { "type": "object", "additionalProperties": false, "required": [ "id", "result_pulled_at", "result_pin_released" ], "properties": { "id": { "$ref": "#/components/schemas/Uuid" }, "result_pulled_at": { "$ref": "#/components/schemas/Timestamp" }, "result_pin_released": { "type": "boolean" } } }, "PersonalHandoffResultRenewed": { "type": "object", "additionalProperties": false, "required": [ "result_snapshot_pin_id", "result_snapshot_pin_expires_at" ], "properties": { "result_snapshot_pin_id": { "$ref": "#/components/schemas/Uuid" }, "result_snapshot_pin_expires_at": { "$ref": "#/components/schemas/Timestamp" } } }, "ConnectProjectFolderRequest": { "description": "Exactly one of `origin` (with an optional `name`), `project_id`, or `name`.", "type": "object", "additionalProperties": false, "required": [ "device_id", "folder_id" ], "properties": { "device_id": { "$ref": "#/components/schemas/Uuid" }, "folder_id": { "type": "string", "pattern": "^[0-9a-f]{32}$" }, "origin": { "type": "string", "minLength": 1, "maxLength": 2048 }, "project_id": { "$ref": "#/components/schemas/Uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 } } }, "UpdateMemberRequest": { "description": "At least one field.", "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "role": { "description": "The member's new role. Only an owner grants `owner`, and an account always keeps at least one person as owner.", "$ref": "#/components/schemas/AccountRole" }, "name": { "description": "The Agent's new name; refused for a person.", "allOf": [ { "$ref": "#/components/schemas/AgentName" } ] } } }, "CreateAccountAgentRequest": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "description": "The Agent's name; 409 when an active Agent of the account has it.", "$ref": "#/components/schemas/AgentName" }, "role": { "description": "The Agent's role; `member` when omitted. Only an owner grants `owner`.", "allOf": [ { "$ref": "#/components/schemas/AccountRole" } ], "default": "member" }, "region": { "description": "The Agent's home region; the only open region when omitted.", "type": "string" } } }, "AccountAgent": { "type": "object", "additionalProperties": false, "required": [ "id", "subject", "name", "role", "region", "created_at" ], "properties": { "id": { "description": "The Agent's id.", "$ref": "#/components/schemas/Uuid" }, "subject": { "description": "`agent.`, the Agent as a member: name it as `member` to create a key for the Agent, and in `PATCH /v1/members/{subject}`.", "$ref": "#/components/schemas/MemberSubject" }, "name": { "description": "The Agent's name.", "type": "string" }, "role": { "description": "The Agent's role.", "$ref": "#/components/schemas/AccountRole" }, "region": { "description": "The Agent's home region, fixed at creation.", "type": "string" }, "created_at": { "description": "When the Agent was created.", "$ref": "#/components/schemas/Timestamp" } } }, "ApiKeyExpiration": { "description": "How long a new key lives from its creation; `1_month` is 30 days, `6_months` 183 days and `1_year` 365 days, and `never` keeps it until it is revoked.", "type": "string", "enum": [ "15_days", "1_month", "6_months", "1_year", "never" ] }, "CreateApiKeyRequest": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "description": "A name to tell the key apart, 1 to 80 characters once spaces are trimmed; unique, ignoring case, among the member's live keys, so a second live key with the name answers 409.", "type": "string", "minLength": 1, "maxLength": 80, "examples": [ "laptop" ] }, "member": { "description": "Omit for your own personal key; `agent.` for an Agent key.", "$ref": "#/components/schemas/MemberSubject" }, "read_only": { "description": "Narrow the key to read-only actions, for its whole life.", "type": "boolean", "default": false }, "buckets": { "description": "Narrow the key to these registered buckets of the account, for its whole life. Never with databases, database_prefixes, streams or stream_prefixes.", "type": "array", "maxItems": 20, "uniqueItems": true, "items": { "type": "string" } }, "databases": { "description": "Narrow the key to these databases, for its whole life; a name need not exist yet. Never with buckets.", "type": "array", "maxItems": 20, "uniqueItems": true, "items": { "$ref": "#/components/schemas/DatabaseName" } }, "database_prefixes": { "description": "Narrow the key to the databases whose name starts with one of these, for its whole life. Never with buckets.", "type": "array", "maxItems": 20, "uniqueItems": true, "items": { "$ref": "#/components/schemas/DatabasePrefix" } }, "streams": { "description": "Narrow the key to these raw streams, by the name the streams API shows, for its whole life; a name need not exist yet. Never with buckets. A key narrowed to both databases and streams reaches both.", "type": "array", "maxItems": 20, "uniqueItems": true, "items": { "$ref": "#/components/schemas/StreamName" } }, "stream_prefixes": { "description": "Narrow the key to the raw streams whose name starts with one of these, for its whole life; each at most 83 bytes, the longest stream name. Never with buckets.", "type": "array", "maxItems": 20, "uniqueItems": true, "items": { "allOf": [ { "$ref": "#/components/schemas/StreamPrefix" } ], "maxLength": 83 } }, "expires_in": { "description": "How long the key lives from now; it never expires when omitted.", "allOf": [ { "$ref": "#/components/schemas/ApiKeyExpiration" } ], "default": "never" } } }, "ApiKey": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "member", "member_kind", "last4", "read_only", "buckets", "databases", "database_prefixes", "streams", "stream_prefixes", "expires_at", "last_used_at", "created_at" ], "properties": { "id": { "description": "The key's id, which `GET` and `DELETE /v1/api-keys/{key_id}` name.", "$ref": "#/components/schemas/Uuid" }, "name": { "description": "The key's name, unique, ignoring case, among its member's live keys.", "type": "string" }, "member": { "description": "Who the key acts as, with that member's current role: a person's user id, or `agent.` for an Agent key.", "$ref": "#/components/schemas/MemberSubject" }, "member_kind": { "description": "`user` for a person's key, `agent` for an Agent key.", "type": "string", "enum": [ "user", "agent" ] }, "last4": { "description": "The secret's last four characters, to tell keys apart; the secret itself is shown only when the key is created.", "type": "string", "minLength": 4, "maxLength": 4 }, "read_only": { "description": "Whether the key is narrowed to read-only actions.", "type": "boolean" }, "buckets": { "description": "The buckets the key is narrowed to; empty when it is not narrowed by bucket.", "type": "array", "items": { "type": "string" } }, "databases": { "description": "The database names the key is narrowed to. A key whose five narrowing lists are all empty reaches everything its member does; otherwise it reaches only what the lists name.", "type": "array", "items": { "$ref": "#/components/schemas/DatabaseName" } }, "database_prefixes": { "description": "The database name prefixes the key is narrowed to.", "type": "array", "items": { "$ref": "#/components/schemas/DatabasePrefix" } }, "streams": { "description": "The stream names the key is narrowed to, without `s.`.", "type": "array", "items": { "$ref": "#/components/schemas/StreamName" } }, "stream_prefixes": { "description": "The stream name prefixes the key is narrowed to.", "type": "array", "items": { "$ref": "#/components/schemas/StreamPrefix" } }, "expires_at": { "description": "When the key stops working; null when it never expires.", "oneOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ] }, "last_used_at": { "description": "Recorded at most once a minute.", "oneOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ] }, "created_at": { "description": "When the key was created.", "$ref": "#/components/schemas/Timestamp" } } }, "ApiKeyWithSecret": { "allOf": [ { "$ref": "#/components/schemas/ApiKey" }, { "type": "object", "required": [ "key" ], "properties": { "key": { "description": "The secret, shown once. `tbo_` followed by 50 base-58 characters, the last six a checksum.", "type": "string", "pattern": "^tbo_[1-9A-HJ-NP-Za-km-z]{50}$" } } } ] }, "Usage": { "type": "object", "additionalProperties": false, "required": [ "period", "currency", "total_micros", "lines" ], "properties": { "period": { "description": "The calendar month counted, in UTC; the `period` asked for, or the current month.", "type": "string", "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])$", "examples": [ "2026-11" ] }, "currency": { "description": "`usd`: every `_micros` amount is in millionths of a US dollar.", "type": "string", "const": "usd" }, "total_micros": { "description": "The month's total, the sum of every line's `amount_micros`.", "type": "integer" }, "lines": { "description": "One line for each product, region, dimension and model charged in the month, in that order.", "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "product", "region", "dimension", "model", "quantity", "amount_micros" ], "properties": { "product": { "description": "The product charged, such as `streams` for databases and streams, or `machines`.", "type": "string" }, "region": { "description": "The region the usage was in.", "type": "string" }, "dimension": { "description": "What was measured, such as `write_units` or `retention_byte_seconds`.", "type": "string" }, "model": { "description": "The model the line was priced for, for a product priced by model; null otherwise.", "type": [ "string", "null" ] }, "quantity": { "description": "Decimal quantity, as text.", "type": "string" }, "amount_micros": { "description": "The line's charge, in micro-dollars.", "type": "integer" } } } } } }, "Uuid": { "description": "A UUID in lowercase hex with hyphens.", "type": "string", "format": "uuid", "examples": [ "3f1c2a9e-5b7d-4c8e-9f10-2a3b4c5d6e7f" ] }, "Timestamp": { "description": "An RFC 3339 time; answers give it in UTC.", "type": "string", "format": "date-time", "examples": [ "2026-11-02T09:30:00.000Z" ] }, "ManagementOperation": { "type": "object", "additionalProperties": false, "required": [ "id", "state", "target_generation" ], "properties": { "id": { "$ref": "#/components/schemas/Uuid" }, "state": { "type": "string", "enum": [ "pending", "claimed", "succeeded", "failed" ] }, "target_generation": { "$ref": "#/components/schemas/Uuid" }, "claim_fence": { "type": "integer", "minimum": 0 }, "attempt_count": { "type": "integer", "minimum": 0 }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "terminal_at": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ] } } }, "ManagementOperationEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ManagementOperation" }, "turn": { "description": "Present when the operation admitted a Turn that is still running. `data.id` is the operation that admitted it.", "$ref": "#/components/schemas/AgentTurn" } } }, "AgentName": { "description": "The Agent's one name, defined by contracts/agents/agent-name-v1.json. It is unique among active Agents within its account and an owner or admin may change it (updateMember); there is no separate display name or slug.", "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$", "not": { "enum": [ "api", "artifacts", "auth", "inference", "lb-check", "network-health", "sandbox-control", "status", "streams", "www" ] } }, "Agent": { "type": "object", "additionalProperties": false, "required": [ "id", "organization_id", "name", "public_hostname", "region", "status", "created_at", "updated_at" ], "properties": { "id": { "$ref": "#/components/schemas/Uuid" }, "organization_id": { "$ref": "#/components/schemas/Uuid" }, "name": { "$ref": "#/components/schemas/AgentName" }, "region": { "description": "Immutable home region chosen when the Agent was created: the region that holds its Deployments, Sessions, Workspace and other regional state. The public hostname does not depend on it.", "type": "string", "pattern": "^[a-z]{2}-[a-z]+-[0-9]$" }, "public_hostname": { "description": "Immutable globally unique agent-organization-word-word.tonbo.sh identity assigned by the server. Deleted addresses are never reused. Existing published legacy addresses remain unchanged. The Organization portion is the permanently reserved username in effect when the Agent is created.", "type": "string", "minLength": 16, "maxLength": 72, "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)+\\.tonbo\\.sh$", "not": { "enum": [ "api.tonbo.sh", "artifacts.tonbo.sh", "auth.tonbo.sh", "inference.tonbo.sh", "lb-check.tonbo.sh", "network-health.tonbo.sh", "sandbox-control.tonbo.sh", "status.tonbo.sh", "streams.tonbo.sh", "www.tonbo.sh" ] } }, "status": { "type": "string", "enum": [ "active" ] }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" } } }, "DeploymentProductionState": { "description": "A Deployment's derived relationship to Production. current means Production names it and the active generation has converged; promoting means Production names it but convergence is pending; failed and stopped mean Production names it with a failed observation or a stopped desired state; previous means an earlier Rollout named it; none means it was never Production.", "type": "string", "enum": [ "current", "promoting", "failed", "stopped", "previous", "none" ] }, "DeploymentGitProvenance": { "type": "object", "additionalProperties": false, "required": [ "commit_sha", "ref", "subject", "author", "dirty" ], "properties": { "repository_url": { "description": "Canonical credential-free GitHub repository URL, when known. Omitted for deployments captured without repository provenance.", "type": [ "string", "null" ], "maxLength": 160, "pattern": "^https://github\\.com/[A-Za-z0-9][A-Za-z0-9-]{0,38}/[A-Za-z0-9._-]{1,100}$" }, "commit_sha": { "type": "string", "pattern": "^[0-9a-f]{40}$" }, "ref": { "description": "The checked-out branch, or null for a detached HEAD.", "type": [ "string", "null" ], "maxLength": 255 }, "subject": { "description": "First line of the commit message.", "type": [ "string", "null" ], "maxLength": 512 }, "author": { "type": [ "string", "null" ], "maxLength": 255 }, "dirty": { "description": "Whether the uploaded source tree differed from the commit.", "type": "boolean" } } }, "DeploymentOrigin": { "type": "object", "additionalProperties": false, "required": [ "actor", "git" ], "properties": { "actor": { "$ref": "../agents/deployment-origin-actor-v1.schema.json" }, "git": { "oneOf": [ { "$ref": "#/components/schemas/DeploymentGitProvenance" }, { "type": "null" } ] } } }, "DeploymentProduction": { "type": "object", "additionalProperties": false, "required": [ "state", "generation" ], "properties": { "state": { "$ref": "#/components/schemas/DeploymentProductionState" }, "generation": { "description": "The latest rollout generation at which this Deployment became Production, or null when it never was.", "type": [ "integer", "null" ], "minimum": 1 } } }, "AgentDeployment": { "type": "object", "additionalProperties": false, "required": [ "id", "agent_id", "spec", "spec_sha256", "origin", "created_by_user_id", "created_at", "production" ], "properties": { "id": { "$ref": "#/components/schemas/Uuid" }, "agent_id": { "$ref": "#/components/schemas/Uuid" }, "spec": { "type": "object", "additionalProperties": true }, "spec_sha256": { "description": "Digest of the canonical spec. Content identity only; several Deployments may share it.", "type": "string", "pattern": "^[0-9a-f]{64}$" }, "origin": { "$ref": "#/components/schemas/DeploymentOrigin" }, "created_by_user_id": { "oneOf": [ { "$ref": "#/components/schemas/Uuid" }, { "type": "null" } ] }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "production": { "$ref": "#/components/schemas/DeploymentProduction" } } }, "AgentProduction": { "type": "object", "additionalProperties": false, "required": [ "id", "agent_id", "deployment_id", "generation", "active_generation", "desired_state", "observed_state", "runtime", "updated_at" ], "properties": { "id": { "$ref": "#/components/schemas/Uuid" }, "agent_id": { "$ref": "#/components/schemas/Uuid" }, "deployment_id": { "description": "The Deployment Production currently names.", "$ref": "#/components/schemas/Uuid" }, "generation": { "description": "Rollout generation; advances when Production moves to a different Deployment.", "type": "integer", "minimum": 1 }, "active_generation": { "type": [ "integer", "null" ], "minimum": 1 }, "desired_state": { "type": "string", "enum": [ "running", "stopped" ] }, "observed_state": { "type": "string", "enum": [ "provisioning", "running", "stopping", "stopped", "failed", "deleting", "deleted" ] }, "last_error": { "type": [ "string", "null" ] }, "runtime": { "oneOf": [ { "type": "object", "additionalProperties": false, "description": "Machine runtime generation identity. Hidden residency activations remain private.", "required": [ "id", "machine_id" ], "properties": { "id": { "$ref": "#/components/schemas/Uuid" }, "machine_id": { "$ref": "#/components/schemas/Uuid" } } }, { "type": "null" } ] }, "updated_at": { "$ref": "#/components/schemas/Timestamp" } } }, "AgentRollout": { "type": "object", "additionalProperties": false, "required": [ "agent_id", "generation", "deployment_id", "previous_deployment_id", "kind", "created_by_user_id", "created_at" ], "properties": { "agent_id": { "$ref": "#/components/schemas/Uuid" }, "generation": { "type": "integer", "minimum": 1 }, "deployment_id": { "$ref": "#/components/schemas/Uuid" }, "previous_deployment_id": { "oneOf": [ { "$ref": "#/components/schemas/Uuid" }, { "type": "null" } ] }, "kind": { "description": "rollback when the target was Production at an earlier generation; promote otherwise.", "type": "string", "enum": [ "promote", "rollback" ] }, "created_by_user_id": { "oneOf": [ { "$ref": "#/components/schemas/Uuid" }, { "type": "null" } ] }, "created_at": { "$ref": "#/components/schemas/Timestamp" } } }, "AgentSession": { "type": "object", "additionalProperties": false, "required": [ "id", "agent_id", "streams_bucket", "created_deployment_id", "created_at", "last_used_at" ], "properties": { "id": { "$ref": "#/components/schemas/Uuid" }, "agent_id": { "$ref": "#/components/schemas/Uuid" }, "streams_bucket": { "type": "string" }, "created_deployment_id": { "$ref": "#/components/schemas/Uuid" }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "last_used_at": { "$ref": "#/components/schemas/Timestamp" } } }, "CreateAgentSessionTurnRequest": { "type": "object", "additionalProperties": false, "required": [ "prompt" ], "properties": { "prompt": { "type": "string", "description": "Non-whitespace prompt containing at most 256 KiB of UTF-8 bytes" } } }, "AgentSessionTurn": { "type": "object", "additionalProperties": false, "required": [ "turn_id", "session_id", "assistant_text" ], "properties": { "turn_id": { "$ref": "#/components/schemas/Uuid" }, "session_id": { "$ref": "#/components/schemas/Uuid" }, "assistant_text": { "type": "string" } } }, "AgentTurn": { "description": "A durable Turn. It executes for at most 60 minutes from `started_at` and waits at most 70 minutes from `accepted_at` to start; neither deadline is ever extended. The admission fields are null for a Turn created before admission records existed.", "type": "object", "additionalProperties": false, "required": [ "id", "session_id", "status", "assistant_text", "failure_code", "failure", "accepted_at", "start_deadline_at", "started_at", "deadline_at", "created_at", "completed_at" ], "properties": { "id": { "$ref": "#/components/schemas/Uuid" }, "session_id": { "$ref": "#/components/schemas/Uuid" }, "status": { "type": "string", "enum": [ "pending", "completed", "failed" ] }, "assistant_text": { "description": "The final assistant text of a completed Turn.", "type": [ "string", "null" ] }, "failure_code": { "description": "The public failure code of a failed Turn; null otherwise, and null for a failure recorded without one.", "oneOf": [ { "$ref": "#/components/schemas/TurnFailureCode" }, { "type": "null" } ] }, "failure": { "description": "Human-readable failure of a failed Turn.", "type": [ "string", "null" ] }, "accepted_at": { "description": "When the Turn was admitted.", "oneOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ] }, "start_deadline_at": { "description": "A Turn that has not started executing by then fails with start_timeout.", "oneOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ] }, "started_at": { "description": "When the Turn started executing; null while it waits.", "oneOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ] }, "deadline_at": { "description": "End of the execution window; a Turn still running then fails with deadline_exceeded.", "oneOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ] }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "completed_at": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ] } } }, "TurnFailureCode": { "description": "Why a Turn failed. deadline_exceeded: it ran for the full execution window. start_timeout: it could not start before its start deadline. aborted: it was aborted. agent_retired: its Agent was deleted or retired. account_deleted: its account entered deletion. key_revoked: the key that submitted it was revoked. funding_exhausted: its account could not fund the runtime or inference. usage_store_unavailable: runtime usage could not be recorded, so the runtime was stopped. runtime_retired: its runtime stopped before the Turn ended. runtime_uncertain: the platform could not establish whether the prompt ran, so it was not replayed. pi_failed: the agent itself failed the Turn. legacy_operation_ended: a Turn created before admission records whose operation ended without it; only during the migration.", "type": "string", "enum": [ "deadline_exceeded", "start_timeout", "aborted", "agent_retired", "account_deleted", "key_revoked", "funding_exhausted", "usage_store_unavailable", "runtime_retired", "runtime_uncertain", "pi_failed", "legacy_operation_ended" ] }, "AgentSessionTurnEvent": { "type": "object", "additionalProperties": false, "required": [ "sequence", "event_type", "payload", "created_at" ], "properties": { "sequence": { "type": "integer", "minimum": 1 }, "event_type": { "type": "string", "enum": [ "run.started", "assistant.delta", "assistant.completed", "tool.started", "tool.completed", "run.completed", "run.failed" ] }, "payload": { "type": "object", "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" } } }, "CreateAgentDeploymentRequest": { "type": "object", "additionalProperties": false, "required": [ "spec" ], "properties": { "spec": { "description": "Must conform to contracts/agents/managed-deployment-v1.schema.json and declare a PI Agent driver.", "type": "object", "required": [ "agent" ], "properties": { "agent": { "type": "object", "required": [ "runtime", "driver" ], "properties": { "runtime": { "type": "string", "const": "pi" }, "driver": { "type": "object" } } } } }, "origin": { "description": "Provenance recorded on the Deployment. Defaults to a CLI Deployment without git metadata.", "$ref": "#/components/schemas/DeploymentOrigin" } } }, "AgentSourceDescriptor": { "type": "object", "additionalProperties": false, "required": [ "format", "sha256", "size_bytes" ], "properties": { "format": { "type": "string", "const": "tar-v1" }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "size_bytes": { "type": "integer", "minimum": 1, "maximum": 67108864 } } }, "PrepareAgentSourceBundleResponse": { "type": "object", "additionalProperties": false, "required": [ "status", "descriptor" ], "properties": { "status": { "type": "string", "enum": [ "ready", "upload" ] }, "descriptor": { "$ref": "#/components/schemas/AgentSourceDescriptor" }, "upload_url": { "type": "string", "format": "uri" }, "upload_headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Exact S3 request headers required for the signed immutable upload." }, "content_type": { "type": "string", "const": "application/vnd.tonbo.source+tar" } } }, "PutAgentProductionRequest": { "type": "object", "additionalProperties": false, "required": [ "deployment_id", "desired_state", "expected_generation" ], "properties": { "deployment_id": { "$ref": "#/components/schemas/Uuid" }, "desired_state": { "type": "string", "enum": [ "running", "stopped" ] }, "expected_generation": { "description": "Null creates; an integer compare-and-swaps the existing Production generation.", "type": [ "integer", "null" ], "minimum": 1 } } }, "AgentSecret": { "type": "object", "additionalProperties": false, "required": [ "name", "updated_at" ], "properties": { "name": { "type": "string", "pattern": "^[A-Z_][A-Z0-9_]{0,127}$" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" } } }, "PutAgentSecretRequest": { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 65536 } } }, "CreateAgentSessionRequest": { "type": "object", "additionalProperties": false, "required": [ "deployment_id" ], "properties": { "deployment_id": { "description": "The Deployment the Session starts from, normally the current Production Deployment.", "$ref": "#/components/schemas/Uuid" } } }, "ValidationIssue": { "type": "object", "additionalProperties": false, "required": [ "field", "code" ], "properties": { "field": { "description": "The refused input, by its name in the request: a body field, a query parameter or a header such as `Idempotency-Key`.", "type": "string", "examples": [ "name" ] }, "code": { "description": "Why it was refused, such as `invalid`; `detail` says how to correct it.", "type": "string", "examples": [ "invalid" ] } } }, "Problem": { "type": "object", "additionalProperties": false, "required": [ "type", "title", "status", "code", "request_id" ], "properties": { "type": { "description": "A URI naming the kind of refusal, the same for every occurrence (RFC 9457); `code` names the same kind.", "type": "string", "format": "uri", "examples": [ "https://docs.tonbo.io/problems/validation-error" ] }, "title": { "description": "A short summary of the kind of refusal, the same for every occurrence.", "type": "string" }, "status": { "description": "The HTTP status of the answer.", "type": "integer", "minimum": 400, "maximum": 599 }, "code": { "description": "The kind of refusal, such as `validation_error` or `not_found`; a client acts on it, never on `title` or `detail`.", "type": "string", "pattern": "^[a-z][a-z0-9_]*$", "examples": [ "validation_error" ] }, "request_id": { "description": "The answer's `X-Request-Id`; quote it when you ask Tonbo about the request.", "type": "string" }, "detail": { "description": "Explanation specific to this occurrence, when one exists.", "type": "string" }, "failure_code": { "description": "Present only on `turn_failed`; null for a failure recorded without a code.", "oneOf": [ { "$ref": "#/components/schemas/TurnFailureCode" }, { "type": "null" } ] }, "token_endpoint": { "description": "Present only on `exchange_required`; where to exchange the key.", "type": "string", "format": "uri" }, "errors": { "description": "The inputs the refusal is about, when it names any.", "type": "array", "items": { "$ref": "#/components/schemas/ValidationIssue" } } } }, "AgentResponse": { "$ref": "#/components/schemas/AgentEnvelope" }, "AgentEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Agent" } } } } } }