{ "openapi": "3.0.3", "info": { "title": "Completion identity API", "version": "0.1.0", "description": "Completion identity, resource, filesystem, Vault metadata and native transport contracts. Explicitly configured services own native execution and encrypted values. Source registration does not qualify installation or runtime behavior. Missing services return 503." }, "servers": [ { "url": "https://api.withcompletion.com" } ], "security": [ { "BearerAuth": [] }, { "BrowserSession": [] } ], "paths": { "/sign-ins": { "post": { "operationId": "StartSignIn", "tags": [ "Foundation" ], "security": [], "description": "Start sign-in using the existing WorkOS configuration. Configured company domains continue through SSO; WorkOS sends email codes for other addresses. Email code issuance has a sixty-second cooldown. Requires the configured browser Origin.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartSignInInput" } } } }, "responses": { "200": { "description": "Sign-in step. Session credentials are set only in HttpOnly cookies.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignInStep" } } }, "headers": { "Set-Cookie": { "description": "Host-only HttpOnly sign-in cookies. Multiple Set-Cookie fields may be returned.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/sign-ins/code-verifications": { "post": { "operationId": "VerifyCode", "tags": [ "Foundation" ], "security": [], "description": "Verify an email code with WorkOS, then admit the User and create a thirty-day Completion browser session. WorkOS owns code expiry and attempts. Provider calls finish before the database transaction. Requires the configured browser Origin.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyCodeInput" } } } }, "responses": { "200": { "description": "Sign-in step. Session credentials are set only in HttpOnly cookies.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignInStep" } } }, "headers": { "Set-Cookie": { "description": "Host-only HttpOnly sign-in cookies. Multiple Set-Cookie fields may be returned.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/sign-ins/continuations": { "post": { "operationId": "ContinueSignIn", "tags": [ "Foundation" ], "security": [], "description": "Continue WorkOS email verification using the pending authentication token sealed in an HttpOnly cookie. Requires the configured browser Origin.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContinueSignInInput" } } } }, "responses": { "200": { "description": "Sign-in step. Session credentials are set only in HttpOnly cookies.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignInStep" } } }, "headers": { "Set-Cookie": { "description": "Host-only HttpOnly sign-in cookies. Multiple Set-Cookie fields may be returned.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/sign-ins/authorizations": { "get": { "operationId": "AuthorizeSignIn", "tags": [ "Foundation" ], "security": [], "description": "Start Google or configured company SSO through WorkOS, with state bound to a short-lived HttpOnly cookie. The callback returns to /login. Application continuation belongs to the browser tab.", "parameters": [ { "name": "provider", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "google", "sso" ] } }, { "name": "email", "in": "query", "required": false, "description": "Email address required for company SSO; normalized to lowercase.", "schema": { "type": "string", "format": "email", "maxLength": 254 } }, { "name": "connection_id", "in": "query", "required": false, "description": "WorkOS connection returned by an SSO-required continuation.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "302": { "description": "Continue in the browser.", "headers": { "Location": { "schema": { "type": "string", "format": "uri" } }, "Set-Cookie": { "description": "Host-only HttpOnly sign-in cookies. Multiple Set-Cookie fields may be returned.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/sign-ins/callbacks": { "get": { "operationId": "SignInCallback", "tags": [ "Foundation" ], "security": [], "description": "Exchange the state-bound callback with WorkOS. Continue company SSO or email verification when required; otherwise create the Completion session. Provider calls finish before the identity/session database transaction.", "parameters": [ { "name": "code", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 8192 } }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 8192 } }, { "name": "error", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 8192 } } ], "responses": { "302": { "description": "Continue in the browser.", "headers": { "Location": { "schema": { "type": "string", "format": "uri" } }, "Set-Cookie": { "description": "Host-only HttpOnly sign-in cookies. Multiple Set-Cookie fields may be returned.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/sign-ins/current": { "delete": { "operationId": "Logout", "tags": [ "Foundation" ], "security": [], "description": "Expire the Completion browser session before revoking its WorkOS session. The exact opaque browser cookie can retry this operation after expiry if the provider is unavailable. Delete the session and clear its cookie after upstream revocation succeeds. API credentials cannot log out a browser session. Requires the configured browser Origin.", "responses": { "204": { "description": "Browser session revoked." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/account": { "get": { "operationId": "Account", "tags": [ "Foundation" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } }, "description": "Native result." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "parameters": [] }, "put": { "operationId": "UpdateAccount", "tags": [ "Foundation" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountSettingsResult" } } }, "description": "Native result." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "name": { "type": "string" } }, "required": [ "name" ] } } } }, "parameters": [], "description": "Set only the supplied top-level writable fields to their absolute values. Omitted fields retain their saved values. Supplied arrays and objects replace that field's value; this is not a recursive merge or JSON Patch operation. Explicit null is valid only where the field schema permits it. Validate the resulting effective resource, including coupled scope and policy fields, before committing. Repeating the same update has the same resource-state effect; never interpret values as increment, toggle or append commands. This identity server supports only the fields declared here." } }, "/organizations": { "get": { "operationId": "ListOrganizations", "tags": [ "Foundation" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationListItemPage" } } }, "description": "Native result." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 50, "maximum": 2147483646 }, "description": "Requested upper bound on this page. The owner may return fewer items to satisfy its native response/transport bounds. Use the returned cursor to continue." } ] }, "post": { "operationId": "CreateOrganization", "tags": [ "Foundation" ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationCreated" } } }, "description": "Native result." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrganizationInput" } } } }, "parameters": [], "description": "Requires a user session. request_id binds an immutable creation receipt; equal retries return the original result and do not restore removed membership." } }, "/organization": { "get": { "operationId": "ReadOrganization", "tags": [ "Foundation" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" } } }, "description": "Native result." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "description": "Required with a session cookie. Bearer API keys select their bound organization.", "schema": { "type": "string", "format": "uuid" } } ] }, "put": { "operationId": "UpdateOrganization", "tags": [ "Foundation" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" } } }, "description": "Native result." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrganizationInput" } } } }, "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "description": "Required with a session cookie. Bearer API keys select their bound organization.", "schema": { "type": "string", "format": "uuid" } } ], "description": "Requires organization.update. Update the selected Organization name, Computer VPN or private-network attachment. Omitted fields stay unchanged. An explicit network_control_enabled value, including an equal value, saves metadata then awaits native confirmation of routing on running Computers and gateway configuration. Paused Computers adopt the saved configuration before subsequent work. Partial application returns an error and retains saved metadata and completed applications. Authorized Vault substitution remains available in both VPN modes. Protected routing currently requires a supported managed Linux Computer; Windows, attached and Vercel Computers cannot confirm this VPN and return an application error when enabling it. No fleet rollback or background retry is promised." } }, "/organization/members": { "get": { "operationId": "ListMembers", "tags": [ "Foundation" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberPage" } } }, "description": "Native result." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 50, "maximum": 2147483646 }, "description": "Requested upper bound on this page. The owner may return fewer items to satisfy its native response/transport bounds. Use the returned cursor to continue." }, { "name": "X-Organization-ID", "in": "header", "required": false, "description": "Required with a session cookie. Bearer API keys select their bound organization.", "schema": { "type": "string", "format": "uuid" } } ] }, "post": { "operationId": "AddOrganizationMember", "description": "Local extension: add an existing user. Requires member-management authority; assigning owner also requires owner-management authority. Provision users with the CLI.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "user_id", "role" ], "properties": { "user_id": { "type": "string", "format": "uuid" }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ] } } } } } }, "responses": { "201": { "description": "Membership created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "user_id", "role" ], "properties": { "id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" }, "role": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" } } } }, "/organization/members/{member_id}": { "put": { "operationId": "ChangeMemberRole", "tags": [ "Foundation" ], "responses": { "204": { "description": "Native result." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberRoleInput" } } } }, "parameters": [ { "name": "member_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Organization-ID", "in": "header", "required": false, "description": "Required with a session cookie. Bearer API keys select their bound organization.", "schema": { "type": "string", "format": "uuid" } } ], "description": "Set only the supplied top-level writable fields to their absolute values. Omitted fields retain their saved values. Supplied arrays and objects replace that field's value; this is not a recursive merge or JSON Patch operation. Explicit null is valid only where the field schema permits it. Validate the resulting effective resource, including coupled scope and policy fields, before committing. Repeating the same update has the same resource-state effect; never interpret values as increment, toggle or append commands. This identity server supports only the fields declared here." }, "delete": { "operationId": "RemoveOrganizationMember", "tags": [ "Foundation" ], "responses": { "204": { "description": "Native result." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "member_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Organization-ID", "in": "header", "required": false, "description": "Required with a session cookie. Bearer API keys select their bound organization.", "schema": { "type": "string", "format": "uuid" } } ] } }, "/organization/ownership": { "post": { "operationId": "TransferOrganizationOwnership", "tags": [ "Foundation" ], "responses": { "204": { "description": "Native result." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferOrganizationOwnershipInput" } } } }, "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "description": "Required with a session cookie. Bearer API keys select their bound organization.", "schema": { "type": "string", "format": "uuid" } } ], "description": " This identity server supports only the fields declared here." } }, "/organization/leave": { "post": { "operationId": "LeaveOrganization", "tags": [ "Foundation" ], "responses": { "204": { "description": "Native result." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "description": "Required with a session cookie. Bearer API keys select their bound organization.", "schema": { "type": "string", "format": "uuid" } } ], "description": "Leave the selected organization and revoke its keys owned by this user. Primary owners must transfer ownership first." } }, "/api-keys": { "get": { "operationId": "ListAPIKeys", "tags": [ "Foundation" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIKeyPage" } } }, "description": "Native result." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 50, "maximum": 2147483646 }, "description": "Requested upper bound on this page. The owner may return fewer items to satisfy its native response/transport bounds. Use the returned cursor to continue." }, { "name": "X-Organization-ID", "in": "header", "required": false, "description": "Required with a session cookie. Bearer API keys select their bound organization.", "schema": { "type": "string", "format": "uuid" } } ] }, "post": { "operationId": "CreateAPIKey", "tags": [ "Foundation" ], "description": "New registration requires organization.keys.manage and the issuer and owner scope ceilings. The authenticated Organization, principal and supplied input bind the immutable request. Equal replay returns the original receipt before current creation permission or owner availability is checked, including after role loss, scope narrowing or target-key revocation. Changed reuse returns 409. Authentication still applies; an expired, revoked or disabled caller credential cannot replay a request. This identity server supports only the fields declared here.", "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIKeyCreated" } } }, "description": "Native result." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterAPIKey" } } } }, "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "description": "Required with a session cookie. Bearer API keys select their bound organization.", "schema": { "type": "string", "format": "uuid" } } ] } }, "/api-keys/{id}": { "put": { "operationId": "UpdateAPIKey", "tags": [ "Foundation" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAPIKeyInput" } } } }, "responses": { "204": { "description": "Native result." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Organization-ID", "in": "header", "required": false, "description": "Required with a session cookie. Bearer API keys select their bound organization.", "schema": { "type": "string", "format": "uuid" } } ], "description": "Set only the supplied top-level writable fields to their absolute values. Omitted fields retain their saved values. Supplied arrays and objects replace that field's value; this is not a recursive merge or JSON Patch operation. Explicit null is valid only where the field schema permits it. Validate the resulting effective resource, including coupled scope and policy fields, before committing. Repeating the same update has the same resource-state effect; never interpret values as increment, toggle or append commands. Replace native_scope using the same resource/operation allowlist shape as key registration. No access role or compatibility alias is accepted. Key-management authority and caller permissions bound the replacement; a scoped key cannot expand itself. Key identity, secret hash, ownership and expiry remain unchanged. New requests use the saved scope; accepted turns retain their admitted authority. This identity server supports only the fields declared here." }, "delete": { "operationId": "RevokeAPIKey", "tags": [ "Foundation" ], "responses": { "204": { "description": "Native result." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Organization-ID", "in": "header", "required": false, "description": "Required with a session cookie. Bearer API keys select their bound organization.", "schema": { "type": "string", "format": "uuid" } } ] } }, "/healthz": { "get": { "operationId": "Health", "security": [], "responses": { "204": { "description": "Database is reachable." }, "503": { "$ref": "#/components/responses/Error" } } } }, "/agents": { "get": { "operationId": "ListAgents", "tags": [ "Resources" ], "description": "List current Agent metadata within current membership, grants and credential scope.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Select an organization for session credentials. Bearer keys remain bound to their organization." }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Literal case-insensitive name/title substring; empty means no search filter." }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 2147483646, "default": 50 } } ], "responses": { "200": { "description": "Resource result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentPage" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "CreateAgent", "tags": [ "Resources" ], "description": "Admit the Agent identity and capture its original source on Archil. A preparing creation receipt guarantees the original source is durable. Capture failure returns the original terminal failed Agent receipt instead. Editable files and the namespace runtime initialize eagerly. Actual file and message consumers finish their required initialization; Session metadata creation does not wait for it. Creation starts no Session or model work. Equal creation replay returns its original admission receipt without changing files, grants or runtime state. Read the Agent for current status. Selected unconfigured Template provisioning returns 503.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Select an organization for session credentials. Bearer keys remain bound to their organization." } ], "responses": { "201": { "description": "Resource result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" }, "200": { "description": "Matching creation replay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentInput" } } } } } }, "/agents/{id}": { "get": { "operationId": "ReadAgent", "tags": [ "Resources" ], "description": "Read current authorized Agent metadata and native filesystem program references.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Select an organization for session credentials. Bearer keys remain bound to their organization." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Resource result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "put": { "operationId": "UpdateAgent", "tags": [ "Resources" ], "description": "Set supplied Agent metadata and default selections. Omitted fields remain unchanged; selected existing resources require current authority.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Select an organization for session credentials. Bearer keys remain bound to their organization." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Resource result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAgentInput" } } } } } }, "/agent-templates": { "get": { "operationId": "ListAgentTemplates", "tags": [ "Resources" ], "description": "Typed service boundary. No metadata/business or external-service implementation is installed; returns 503 until the relevant service is injected.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Select an organization for session credentials. Bearer keys remain bound to their organization." }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Literal case-insensitive name/title substring; empty means no search filter." }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 2147483646, "default": 50 } } ], "responses": { "200": { "description": "Resource result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTemplatePage" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "CreateAgentTemplate", "tags": [ "Resources" ], "description": "Typed service boundary. No metadata/business or external-service implementation is installed; returns 503 until the relevant service is injected.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Select an organization for session credentials. Bearer keys remain bound to their organization." } ], "responses": { "201": { "description": "Resource result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTemplate" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" }, "200": { "description": "Matching creation replay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTemplate" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentTemplateInput" } } } } } }, "/agent-templates/{id}": { "get": { "operationId": "ReadAgentTemplate", "tags": [ "Resources" ], "description": "Typed service boundary. No metadata/business or external-service implementation is installed; returns 503 until the relevant service is injected.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Select an organization for session credentials. Bearer keys remain bound to their organization." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Resource result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTemplate" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "put": { "operationId": "UpdateAgentTemplate", "tags": [ "Resources" ], "description": "Typed service boundary. No metadata/business or external-service implementation is installed; returns 503 until the relevant service is injected.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Select an organization for session credentials. Bearer keys remain bound to their organization." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Resource result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTemplate" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAgentTemplateInput" } } } } } }, "/computers": { "get": { "operationId": "ListComputers", "tags": [ "Resources" ], "description": "List authorized Computers with literal, case-insensitive name substring search. An empty q applies no search filter. Reads do not resume or install software.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Select an organization for session credentials. Bearer keys remain bound to their organization." }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Literal case-insensitive name/title substring; empty means no search filter." }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 2147483646, "default": 50 } }, { "name": "agent_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "permission", "in": "query", "schema": { "type": "string", "enum": [ "viewer", "writer" ] } } ], "responses": { "200": { "description": "Resource result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComputerPage" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "CreateComputer", "tags": [ "Resources" ], "description": "Allocate and prepare a managed Computer from exactly one provider source, Template, or authorized Computer. No Agent work is submitted. Completed immutable requests replay their original result; unresolved requests conflict without repeating native effects.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Select an organization for session credentials. Bearer keys remain bound to their organization." } ], "responses": { "201": { "description": "Resource result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Computer" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" }, "200": { "description": "Matching creation replay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Computer" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateComputerInput" } } } } } }, "/computers/{id}": { "get": { "operationId": "ReadComputer", "tags": [ "Resources" ], "description": "Read authorized resource metadata and attached connection observations without resuming the Computer or installing software.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Select an organization for session credentials. Bearer keys remain bound to their organization." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Resource result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Computer" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "put": { "operationId": "UpdateComputer", "tags": [ "Resources" ], "description": "Assign the supplied name and preserve omitted fields.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Select an organization for session credentials. Bearer keys remain bound to their organization." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Resource result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Computer" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateComputerInput" } } } } }, "delete": { "operationId": "DeleteComputer", "tags": [ "Foundation" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" }, "204": { "description": "Deleted" } } } }, "/computer-templates": { "get": { "operationId": "ListComputerTemplates", "tags": [ "Resources" ], "description": "List authorized Templates with literal, case-insensitive name substring search. An empty q applies no search filter.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Select an organization for session credentials. Bearer keys remain bound to their organization." }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Literal case-insensitive name/title substring; empty means no search filter." }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 2147483646, "default": 50 } } ], "responses": { "200": { "description": "Resource result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComputerTemplatePage" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "CreateComputerTemplate", "tags": [ "Resources" ], "description": "Capture a managed Computer and publish its state as a new Template. Capture automatically selects supported memory state, otherwise disk state. A native failure is returned without retrying another capture mode.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Select an organization for session credentials. Bearer keys remain bound to their organization." } ], "responses": { "201": { "description": "Resource result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComputerTemplate" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" }, "200": { "description": "Matching creation replay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComputerTemplate" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateComputerTemplateInput" } } } } } }, "/computer-templates/{id}": { "get": { "operationId": "ReadComputerTemplate", "tags": [ "Resources" ], "description": "Read authorized Template metadata and its selected capture.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Select an organization for session credentials. Bearer keys remain bound to their organization." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Resource result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComputerTemplate" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "put": { "operationId": "UpdateComputerTemplate", "tags": [ "Resources" ], "description": "Assign the supplied name and preserve omitted fields.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Select an organization for session credentials. Bearer keys remain bound to their organization." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Resource result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComputerTemplate" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateComputerTemplateInput" } } } } }, "delete": { "operationId": "DeleteComputerTemplate", "tags": [ "Foundation" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" }, "204": { "description": "Deleted" } } } }, "/browsers": { "get": { "operationId": "ListBrowsers", "tags": [ "Resources" ], "description": "List Browser metadata within current owner or organization administrator authority and credential scope. Uses opaque cursor pagination ordered by Browser ID. Browser use permission is required to include a row. No live Browser is opened.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Select an organization for session credentials. Bearer keys remain bound to their organization." }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Literal case-insensitive substring of name, ID, provider or status. Empty means no search filter." }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 2147483646, "default": 50 } } ], "responses": { "200": { "description": "Resource result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserPage" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "CreateBrowser", "tags": [ "Resources" ], "description": "Allocate an independent durable Kernel profile without opening a live Browser. Use provider=\"kernel\" without source or browser_template_id. Native source import, Template instantiation and other providers return 422. Replays require the same immutable request and original creation authority.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Select an organization for session credentials. Bearer keys remain bound to their organization." } ], "responses": { "201": { "description": "Resource result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Browser" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" }, "200": { "description": "Matching creation replay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Browser" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBrowserInput" } } } } } }, "/browsers/{id}": { "get": { "operationId": "ReadBrowser", "tags": [ "Resources" ], "description": "Read Browser metadata within current owner or organization administrator authority and credential scope. Browser use permission is required. No live Browser is opened.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Select an organization for session credentials. Bearer keys remain bound to their organization." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Resource result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Browser" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "put": { "operationId": "UpdateBrowser", "tags": [ "Resources" ], "description": "Assign each supplied writable field and preserve omitted fields. Null clears start_url. Validate the effective resource under current owner or organization administrator authority and credential scope. No live Browser is opened.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Select an organization for session credentials. Bearer keys remain bound to their organization." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Resource result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Browser" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBrowserInput" } } } } } }, "/browser-templates": { "get": { "operationId": "ListBrowserTemplates", "tags": [ "Resources" ], "description": "Typed service boundary. No metadata/business or external-service implementation is installed; returns 503 until the relevant service is injected.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Select an organization for session credentials. Bearer keys remain bound to their organization." }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Literal case-insensitive name/title substring; empty means no search filter." }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 2147483646, "default": 50 } } ], "responses": { "200": { "description": "Resource result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserTemplatePage" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "CreateBrowserTemplate", "tags": [ "Resources" ], "description": "Typed service boundary. No metadata/business or external-service implementation is installed; returns 503 until the relevant service is injected.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Select an organization for session credentials. Bearer keys remain bound to their organization." } ], "responses": { "201": { "description": "Resource result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserTemplate" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" }, "200": { "description": "Matching creation replay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserTemplate" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBrowserTemplateInput" } } } } } }, "/browser-templates/{id}": { "get": { "operationId": "ReadBrowserTemplate", "tags": [ "Resources" ], "description": "Typed service boundary. No metadata/business or external-service implementation is installed; returns 503 until the relevant service is injected.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Select an organization for session credentials. Bearer keys remain bound to their organization." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Resource result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserTemplate" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "put": { "operationId": "UpdateBrowserTemplate", "tags": [ "Resources" ], "description": "Typed service boundary. No metadata/business or external-service implementation is installed; returns 503 until the relevant service is injected.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Select an organization for session credentials. Bearer keys remain bound to their organization." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Resource result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserTemplate" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBrowserTemplateInput" } } } } } }, "/agents/{id}/sessions": { "get": { "operationId": "ListAgentSessions", "tags": [ "Resources" ], "description": "List persisted Session metadata within current Agent and namespace authority and each Session original credential ceiling. Listing starts no runtime or model work.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Select an organization for session credentials. Bearer keys remain bound to their organization." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Literal case-insensitive name/title substring; empty means no search filter." }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 2147483646, "default": 50 } } ], "responses": { "200": { "description": "Resource result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSessionPage" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "CreateAgentSession", "tags": [ "Resources" ], "description": "Persist Session metadata, an immutable program reference, selections and behavior overrides under current authority. Omitted selections inherit from the Agent or parent Session. Creation starts no runtime or model work and does not wait for editable files or runtime readiness. The original source must already be admitted. Equal immutable creation returns its original receipt.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Select an organization for session credentials. Bearer keys remain bound to their organization." }, { "name": "id", "in": "path", "x-sdk-name": "agent_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Resource result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSession" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentSessionInput" } } } } } }, "/agents/{id}/sessions/{session_id}": { "get": { "operationId": "ReadAgentSession", "tags": [ "Resources" ], "description": "Read persisted Session metadata under current Agent and namespace authority and the original Session credential ceiling. This read starts no runtime or model work.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Select an organization for session credentials. Bearer keys remain bound to their organization." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Resource result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSession" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/agents/{id}/settings": { "get": { "operationId": "ReadAgentSettings", "tags": [ "Resources" ], "description": "Resolve current Agent configuration from its authoritative native definition files on Archil under current Agent read authority.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Select an organization for session credentials. Bearer keys remain bound to their organization." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Resource result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentConfiguration" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "put": { "operationId": "UpdateAgentSettings", "tags": [ "Resources" ], "description": "Set supplied Agent configuration fields through caller-authorized filesystem operations. Omitted fields and native configuration keys remain unchanged. This starts no model work.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Select an organization for session credentials. Bearer keys remain bound to their organization." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Resource result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentConfiguration" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentConfiguration" } } } } } }, "/agents/{id}/sessions/{session_id}/settings": { "get": { "operationId": "ReadAgentSessionSettings", "tags": [ "Resources" ], "description": "Resolve current Agent file defaults with saved Session behavior overrides, under current Agent and namespace authority and the original Session credential ceiling.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Select an organization for session credentials. Bearer keys remain bound to their organization." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Resource result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSettings" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "put": { "operationId": "UpdateAgentSessionSettings", "tags": [ "Resources" ], "description": "Save supplied Session behavior overrides after validating effective settings. Omitted fields remain unchanged. This starts no runtime or model work.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Select an organization for session credentials. Bearer keys remain bound to their organization." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Resource result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSettings" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSettings" } } } } } }, "/agent-templates/{id}/snapshot": { "post": { "operationId": "SaveAgentTemplateSnapshot", "tags": [ "Resources" ], "description": "Typed service boundary. No metadata/business or external-service implementation is installed; returns 503 until the relevant service is injected.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Select an organization for session credentials. Bearer keys remain bound to their organization." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Resource result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTemplateVersion" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveAgentTemplateSnapshotInput" } } } } } }, "/computer-templates/{id}/snapshot": { "post": { "operationId": "SaveComputerTemplateSnapshot", "tags": [ "Resources" ], "description": "Capture and publish the completed native result inside this request. Exact request replay returns its original result; no background job is created.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Select an organization for session credentials. Bearer keys remain bound to their organization." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" }, "200": { "description": "Resource result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComputerTemplateCapture" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveComputerTemplateSnapshotInput" } } } } } }, "/browser-templates/{id}/snapshot": { "post": { "operationId": "SaveBrowserTemplateSnapshot", "tags": [ "Resources" ], "description": "Typed service boundary. No metadata/business or external-service implementation is installed; returns 503 until the relevant service is injected.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Select an organization for session credentials. Bearer keys remain bound to their organization." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Resource result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserTemplateCapture" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveBrowserTemplateSnapshotInput" } } } } } }, "/agent-templates/{id}/versions/{version_id}": { "get": { "operationId": "ReadAgentTemplateVersion", "tags": [ "Resources" ], "description": "Typed service boundary. No metadata/business or external-service implementation is installed; returns 503 until the relevant service is injected.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Select an organization for session credentials. Bearer keys remain bound to their organization." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "version_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Resource result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTemplateVersion" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/agents/{id}/sessions/{session_id}/events": { "get": { "operationId": "ListAgentSessionEvents", "tags": [ "Resources" ], "description": "Read committed native Pi EntryRecord JSON in ascending native entry ID order. Current Agent and namespace authority and the Session's original credential ceiling apply. This observer does not allocate a runtime, initialize a Session, open a Harness or wake a Durable Object. A Session without a ready runtime has an empty page. Poll next_cursor for later entries; a nonempty page supplies a continuation even when has_more is false, and an empty page retains the supplied cursor. Native history remains the sole event store.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Select an organization for session credentials. Bearer keys remain bound to their organization." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 2147483646, "default": 50 } } ], "responses": { "200": { "description": "Committed native entries and a polling continuation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSessionEventPage" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/agents/{id}/sessions/{session_id}/stream": { "get": { "operationId": "StreamAgentSession", "tags": [ "Resources" ], "description": "Observe live native Pi AgentEvent JSON as newline-delimited JSON after a message has been accepted. The native initial snapshot and subsequent deltas are forwarded unchanged. A Session without admitted input returns 409. Current Agent and namespace authority and the Session's original credential ceiling are checked before exposing each chunk. This observer does not allocate a native conversation or submit work. Closing it stops observation and does not cancel accepted work. Events are live only; read committed history through ListAgentSessionEvents.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Select an organization for session credentials. Bearer keys remain bound to their organization." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Live native Pi AgentEvent records, one JSON object per line.", "content": { "application/x-ndjson": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/agents/{id}/sessions/{session_id}/messages": { "post": { "operationId": "CreateAgentMessage", "tags": [ "Resources" ], "description": "Authorize the current Agent and Session namespace within the saved Session ceiling, resolve current file defaults and Session overrides, and submit to the existing native CF runtime. The receipt confirms native durable admission; live output is observed through StreamAgentSession and committed reply entries through ListAgentSessionEvents. mode selects queue (the default), steer after the current tool round, or restart the active run with this input while preserving history. Restart retains the targeted run across retries and preserves unrelated queued inputs in their native order. A run handover that wins cancellation returns 409 before this input is submitted; retry the same message ID. If idle, every mode starts work normally. Resubmitting a message ID replaces its content without rerunning completed work or applying the mode again.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Select an organization for session credentials. Bearer keys remain bound to their organization." }, { "name": "id", "in": "path", "x-sdk-name": "agent_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Resource result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentInputReceipt" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentMessageInput" } } } } } }, "/agents/{id}/owner": { "put": { "operationId": "UpdateAgentOwner", "tags": [ "Resources" ], "description": "Set resource ownership to the supplied current organization membership, or clear it with null. The current resource owner or an organization administrator (primary_owner, owner, admin) may change ownership; administrators do not need permission from the existing owner or resource grants. Current organization membership and any credential scope ceiling still apply. Cross-organization and deleted target memberships are invalid. Changing ownership does not replace sharing grants or creation provenance. Repeating the same assignment is a no-op. Core authorization and mutation are not implemented; returns 503 until the service is injected.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Select an organization for session credentials. Bearer keys remain bound to their organization." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Resource result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateResourceOwnerInput" } } } } } }, "/agent-templates/{id}/owner": { "put": { "operationId": "UpdateAgentTemplateOwner", "tags": [ "Resources" ], "description": "Set resource ownership to the supplied current organization membership, or clear it with null. The current resource owner or an organization administrator (primary_owner, owner, admin) may change ownership; administrators do not need permission from the existing owner or resource grants. Current organization membership and any credential scope ceiling still apply. Cross-organization and deleted target memberships are invalid. Changing ownership does not replace sharing grants or creation provenance. Repeating the same assignment is a no-op. Core authorization and mutation are not implemented; returns 503 until the service is injected.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Select an organization for session credentials. Bearer keys remain bound to their organization." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Resource result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTemplate" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateResourceOwnerInput" } } } } } }, "/computers/{id}/owner": { "put": { "operationId": "UpdateComputerOwner", "tags": [ "Resources" ], "description": "Assign the resource owner under current ownership and scope authority.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Select an organization for session credentials. Bearer keys remain bound to their organization." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Resource result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Computer" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateResourceOwnerInput" } } } } } }, "/computer-templates/{id}/owner": { "put": { "operationId": "UpdateComputerTemplateOwner", "tags": [ "Resources" ], "description": "Assign the resource owner under current ownership and scope authority.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Select an organization for session credentials. Bearer keys remain bound to their organization." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Resource result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComputerTemplate" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateResourceOwnerInput" } } } } } }, "/browsers/{id}/owner": { "put": { "operationId": "UpdateBrowserOwner", "tags": [ "Resources" ], "description": "Set resource ownership to the supplied current organization membership, or clear it with null. The current resource owner or an organization administrator (primary_owner, owner, admin) may change ownership; administrators do not need permission from the existing owner or resource grants. Current organization membership and any credential scope ceiling still apply. Cross-organization and deleted target memberships are invalid. Changing ownership does not replace creation provenance. Repeating the same assignment is a no-op. Browser sharing grants are not supported.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Select an organization for session credentials. Bearer keys remain bound to their organization." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Resource result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Browser" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateResourceOwnerInput" } } } } } }, "/browser-templates/{id}/owner": { "put": { "operationId": "UpdateBrowserTemplateOwner", "tags": [ "Resources" ], "description": "Set resource ownership to the supplied current organization membership, or clear it with null. The current resource owner or an organization administrator (primary_owner, owner, admin) may change ownership; administrators do not need permission from the existing owner or resource grants. Current organization membership and any credential scope ceiling still apply. Cross-organization and deleted target memberships are invalid. Changing ownership does not replace sharing grants or creation provenance. Repeating the same assignment is a no-op. Core authorization and mutation are not implemented; returns 503 until the service is injected.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Select an organization for session credentials. Bearer keys remain bound to their organization." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Resource result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserTemplate" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateResourceOwnerInput" } } } } } }, "/filesystem/nodes/{node_id}/permissions": { "get": { "operationId": "ListFilesystemPermissions", "tags": [ "Filesystem" ], "description": "List direct grants in stable permission-ID order. Requires filesystem.share and current credential/Session ceilings. Authorization and pagination run in PostgreSQL. Node IDs are available from the read-only user.completion.node_id FUSE attribute.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Organization selection for session credentials. Bearer keys remain bound to their organization." }, { "name": "node_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 2147483646, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" }, "200": { "description": "Committed result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilesystemPermissionPage" } } } } } }, "post": { "operationId": "CreateFilesystemPermission", "tags": [ "Filesystem" ], "description": "Create one direct reader/writer grant. Requires filesystem.share. Members must belong to this organization. Null member_id grants organization-wide access. Duplicate subjects conflict. Grants never authorize Agent execution or configuration, immutable writes, or escape from admitted boundaries.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Organization selection for session credentials. Bearer keys remain bound to their organization." }, { "name": "node_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" }, "201": { "description": "Committed result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilesystemPermission" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFilesystemPermissionInput" } } } } } }, "/filesystem/nodes/{node_id}/permissions/{permission_id}": { "put": { "operationId": "UpdateFilesystemPermission", "tags": [ "Filesystem" ], "description": "Set supplied grant fields, retaining omitted fields. Explicit null expiry clears expiration. Grant identity, node and member are immutable. Equal updates preserve node revision.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Organization selection for session credentials. Bearer keys remain bound to their organization." }, { "name": "node_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "permission_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" }, "200": { "description": "Committed result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilesystemPermission" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateFilesystemPermissionInput" } } } } }, "delete": { "operationId": "DeleteFilesystemPermission", "tags": [ "Filesystem" ], "description": "Remove a direct grant under current filesystem.share authority. Equal repeats return 204. Other direct and inherited grants remain. Existing mounts and open handles check current authority on subsequent operations.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Organization selection for session credentials. Bearer keys remain bound to their organization." }, { "name": "node_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "permission_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" }, "204": { "description": "Committed result." } } } }, "/filesystem/commands": { "post": { "operationId": "ExecuteFilesystemCommand", "tags": [ "Filesystem" ], "description": "Execute one offline Bash command in the selected Agent's persistent Archil sandbox, against a freshly admitted authenticated caller FUSE view at /workspace. Current Agent write authority and credential scope are required to select the sandbox; the selection grants no filesystem or Session authority. Combined stdout/stderr is limited to 1 MiB; excess output returns 413. Request cancellation or deadline terminates the command. Nonzero Bash exit is a successful HTTP 200 with exit_code. Failed or timed-out commands retain earlier file effects and are never retried. The body supplies no actor or scope assertions.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Organization selection for session credentials. Bearer keys remain bound to their organization." } ], "responses": { "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" }, "200": { "description": "Committed result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BashResult" } } } }, "504": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilesystemCommand" } } } } } }, "/filesystem/mount": { "get": { "operationId": "ConnectFilesystemMount", "tags": [ "Filesystem" ], "description": "Upgrade with WebSocket subprotocol sftp. Exchange SFTP v3 bytes through binary messages. Paths resolve inside the authenticated organization view. The required agent_id selects the Agent's persistent Archil sandbox and requires current Agent writer authority and credential scope. Placement does not assert an acting Agent or widen filesystem access. Other query parameters are rejected. A supplied Origin must match the configured browser origin. Current grants and credential ceilings govern each file operation. Connection close, credential expiry and shutdown release the view. Native FUSE operations are internal, not separate HTTP endpoints.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Organization selection for session credentials. Bearer keys remain bound to their organization." }, { "name": "agent_id", "in": "query", "required": true, "description": "Agent whose persistent Archil sandbox hosts this caller view.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" }, "101": { "description": "Authenticated SFTP v3 stream over binary WebSocket messages.", "headers": { "Sec-WebSocket-Protocol": { "schema": { "type": "string", "enum": [ "sftp" ] } } } }, "426": { "$ref": "#/components/responses/Error" } }, "x-native-transports": { "websocket": { "subprotocol": "sftp", "payload": "SFTP v3 binary byte stream" } } } }, "/agents/{agent_id}/permissions": { "get": { "operationId": "ListAgentPermissions", "tags": [ "Agent" ], "description": "Manage direct resource grants under current resource owner or organization administrator authority and the caller credential ceiling. These grants authorize the canonical resource files without copied filesystem grants.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "schema": { "type": "string", "format": "uuid" } }, { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 2147483646, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "200": { "description": "Committed result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentPermissionPage" } } } } } }, "post": { "operationId": "CreateAgentPermission", "tags": [ "Agent" ], "description": "Manage direct resource grants under current resource owner or organization administrator authority and the caller credential ceiling. These grants authorize the canonical resource files without copied filesystem grants.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "schema": { "type": "string", "format": "uuid" } }, { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "201": { "description": "Committed result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentPermission" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentPermissionInput" } } } } } }, "/agents/{agent_id}/permissions/{permission_id}": { "put": { "operationId": "UpdateAgentPermission", "tags": [ "Agent" ], "description": "Manage direct resource grants under current resource owner or organization administrator authority and the caller credential ceiling. These grants authorize the canonical resource files without copied filesystem grants.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "schema": { "type": "string", "format": "uuid" } }, { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "permission_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "200": { "description": "Committed result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentPermission" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAgentPermissionInput" } } } } }, "delete": { "operationId": "DeleteAgentPermission", "tags": [ "Agent" ], "description": "Manage direct resource grants under current resource owner or organization administrator authority and the caller credential ceiling. These grants authorize the canonical resource files without copied filesystem grants.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "schema": { "type": "string", "format": "uuid" } }, { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "permission_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "204": { "description": "Committed result." } } } }, "/namespaces/{namespace_id}/permissions": { "get": { "operationId": "ListNamespacePermissions", "tags": [ "Namespace" ], "description": "Manage direct resource grants under current resource owner or organization administrator authority and the caller credential ceiling. These grants authorize the canonical resource files without copied filesystem grants.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "schema": { "type": "string", "format": "uuid" } }, { "name": "namespace_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 2147483646, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "200": { "description": "Committed result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NamespacePermissionPage" } } } } } }, "post": { "operationId": "CreateNamespacePermission", "tags": [ "Namespace" ], "description": "Manage direct resource grants under current resource owner or organization administrator authority and the caller credential ceiling. These grants authorize the canonical resource files without copied filesystem grants.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "schema": { "type": "string", "format": "uuid" } }, { "name": "namespace_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "201": { "description": "Committed result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NamespacePermission" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNamespacePermissionInput" } } } } } }, "/namespaces/{namespace_id}/permissions/{permission_id}": { "put": { "operationId": "UpdateNamespacePermission", "tags": [ "Namespace" ], "description": "Manage direct resource grants under current resource owner or organization administrator authority and the caller credential ceiling. These grants authorize the canonical resource files without copied filesystem grants.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "schema": { "type": "string", "format": "uuid" } }, { "name": "namespace_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "permission_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "200": { "description": "Committed result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NamespacePermission" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateNamespacePermissionInput" } } } } }, "delete": { "operationId": "DeleteNamespacePermission", "tags": [ "Namespace" ], "description": "Manage direct resource grants under current resource owner or organization administrator authority and the caller credential ceiling. These grants authorize the canonical resource files without copied filesystem grants.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "schema": { "type": "string", "format": "uuid" } }, { "name": "namespace_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "permission_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "204": { "description": "Committed result." } } } }, "/computers/{id}/pause": { "post": { "operationId": "PauseComputer", "tags": [ "Foundation" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" }, "200": { "description": "Completed native result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Computer" } } } } } } }, "/computers/{id}/sharing": { "get": { "operationId": "ListComputerPermissions", "tags": [ "Foundation" ], "parameters": [ { "name": "X-Organization-ID", "in": "header", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 2147483646, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Committed result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourcePermissionPage" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } } } }, "/computers/{id}/sharing/members/{member_id}": { "put": { "operationId": "SetComputerMemberPermission", "tags": [ "Foundation" ], "parameters": [ { "name": "X-Organization-ID", "in": "header", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "member_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Committed result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourcePermission" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetResourcePermissionInput" } } } } }, "delete": { "operationId": "DeleteComputerMemberPermission", "tags": [ "Foundation" ], "parameters": [ { "name": "X-Organization-ID", "in": "header", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "member_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Committed result." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } } } }, "/computers/{id}/sharing/organization": { "put": { "operationId": "SetComputerOrganizationPermission", "tags": [ "Foundation" ], "parameters": [ { "name": "X-Organization-ID", "in": "header", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Committed result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourcePermission" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetResourcePermissionInput" } } } } }, "delete": { "operationId": "DeleteComputerOrganizationPermission", "tags": [ "Foundation" ], "parameters": [ { "name": "X-Organization-ID", "in": "header", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Committed result." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } } } }, "/computer-templates/{id}/sharing": { "get": { "operationId": "ListComputerTemplatePermissions", "tags": [ "Foundation" ], "parameters": [ { "name": "X-Organization-ID", "in": "header", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 2147483646, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Committed result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourcePermissionPage" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } } } }, "/computer-templates/{id}/sharing/members/{member_id}": { "put": { "operationId": "SetComputerTemplateMemberPermission", "tags": [ "Foundation" ], "parameters": [ { "name": "X-Organization-ID", "in": "header", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "member_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Committed result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourcePermission" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetResourcePermissionInput" } } } } }, "delete": { "operationId": "DeleteComputerTemplateMemberPermission", "tags": [ "Foundation" ], "parameters": [ { "name": "X-Organization-ID", "in": "header", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "member_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Committed result." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } } } }, "/computer-templates/{id}/sharing/organization": { "put": { "operationId": "SetComputerTemplateOrganizationPermission", "tags": [ "Foundation" ], "parameters": [ { "name": "X-Organization-ID", "in": "header", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Committed result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourcePermission" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetResourcePermissionInput" } } } } }, "delete": { "operationId": "DeleteComputerTemplateOrganizationPermission", "tags": [ "Foundation" ], "parameters": [ { "name": "X-Organization-ID", "in": "header", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Committed result." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } } } }, "/ssh-keys": { "get": { "operationId": "ListSSHKeys", "tags": [ "Foundation" ], "parameters": [ { "name": "X-Organization-ID", "in": "header", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 2147483646, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Committed result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SSHKeyPage" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "AddSSHKey", "tags": [ "Foundation" ], "description": "Register a key for native Computer shell and file access. Supported SSH shells and exec sessions receive connection-owned HTTP(S) proxy and CA defaults for caller-authorized Vault substitution. Clients that bypass those settings receive no automatic substitution. SFTP and SCP retain their native protocols; public port forwarding is unsupported.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Committed result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SSHKey" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SSHKeyInput" } } } } } }, "/ssh-keys/{id}": { "delete": { "operationId": "DeleteSSHKey", "tags": [ "Foundation" ], "parameters": [ { "name": "X-Organization-ID", "in": "header", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Committed result." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } } } }, "/computer-pairings": { "post": { "operationId": "CreateComputerPairing", "tags": [ "Foundation" ], "security": [], "responses": { "201": { "description": "Native result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComputerPairing" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "410": { "$ref": "#/components/responses/Error" }, "426": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateComputerPairingInput" } } } } } }, "/computer-pairings/{id}": { "get": { "operationId": "ReadComputerPairing", "tags": [ "Foundation" ], "security": [ { "ComputerDeviceCredential": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Native result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComputerPairing" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "410": { "$ref": "#/components/responses/Error" }, "426": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/computer-pairings/lookup": { "post": { "operationId": "LookupComputerPairing", "tags": [ "Foundation" ], "parameters": [ { "name": "X-Organization-ID", "in": "header", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Native result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComputerPairing" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "410": { "$ref": "#/components/responses/Error" }, "426": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComputerPairingCodeInput" } } } } } }, "/computer-pairings/approve": { "post": { "operationId": "ApproveComputerPairing", "tags": [ "Foundation" ], "parameters": [ { "name": "X-Organization-ID", "in": "header", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Native result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComputerPairingApproval" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "410": { "$ref": "#/components/responses/Error" }, "426": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComputerPairingCodeInput" } } } } } }, "/computer-pairings/{id}/connection": { "get": { "operationId": "ConnectComputerPairing", "tags": [ "Foundation" ], "security": [ { "ComputerDeviceCredential": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "101": { "description": "Native connector WebSocket protocol." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "410": { "$ref": "#/components/responses/Error" }, "426": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "x-native-transports": { "websocket": { "payload": "Pibo native connector JSON/frame/credit protocol" } } } }, "/computers/{id}/connection": { "get": { "operationId": "ConnectComputer", "tags": [ "Foundation" ], "security": [ { "ComputerDeviceCredential": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "101": { "description": "Native connector WebSocket protocol." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "410": { "$ref": "#/components/responses/Error" }, "426": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "x-native-transports": { "websocket": { "payload": "Pibo native connector JSON/frame/credit protocol" } } } }, "/computers/{id}/desktop": { "post": { "operationId": "StartComputerDesktop", "tags": [ "Resources" ], "description": "Open the Computer's native desktop. A managed Computer resumes and starts its existing unprivileged desktop service. Attached uses its current OS desktop. view_only requires read authority and returns an endpoint-bound browser grant with no input or clipboard. Ordinary access requires control. No application is installed by this operation.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Select an organization for session credentials. Bearer keys remain bound to their organization." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "view_only", "in": "query", "schema": { "type": "string", "enum": [ "0", "1" ] } } ], "responses": { "200": { "description": "Native desktop transport access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopAccess" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "426": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" }, "504": { "$ref": "#/components/responses/Error" } } } }, "/computers/{id}/desktop/stream": { "get": { "operationId": "ComputerDesktopStream", "tags": [ "Resources" ], "description": "Native RFB bytes for managed Computers, or PNG metadata and binary image frames for attached Computers. A read-only browser grant admits pixels only; both RFB directions are filtered and attached input is rejected. Each new operation checks current authority.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Select an organization for session credentials. Bearer keys remain bound to their organization." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "organization_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "view_token", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 8192 } } ], "responses": { "101": { "description": "Native desktop WebSocket." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "426": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" }, "504": { "$ref": "#/components/responses/Error" } }, "x-native-transports": { "websocket": { "payload": "Native managed RFB bytes or attached PNG metadata and binary frames." } } } }, "/computers/{id}/updates": { "get": { "operationId": "GetComputerSoftwareUpdate", "tags": [ "Resources" ], "description": "Read the observed installed and selected available builds without allocation, installation or resume.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Observed installed and available software.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComputerSoftwareUpdateStatus" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" }, "504": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "ApplyComputerUpdates", "tags": [ "Resources" ], "description": "Apply one desired release. Repeating a completed installation observes the selected build and skips it. Native errors and unconfirmed handoff remain failures; this operation has no historical update receipt or automatic retry.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComputerSoftwareUpdateInput" } } } }, "responses": { "200": { "description": "Native confirmed completed update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComputerSoftwareUpdateStatus" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" }, "504": { "$ref": "#/components/responses/Error" } } } }, "/computer-templates/{id}/updates": { "get": { "operationId": "GetComputerTemplateSoftwareUpdate", "tags": [ "Resources" ], "description": "Read the observed installed and selected available builds without allocation, installation or resume.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Observed installed and available software.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComputerSoftwareUpdateStatus" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" }, "504": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "ApplyComputerTemplateUpdates", "tags": [ "Resources" ], "description": "Install into an owned temporary native clone, capture, delete the clone and publish with compare-and-set. The existing capture receipt owns exact immutable request replay. No public temporary Computer or background job is created.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComputerSoftwareUpdateInput" } } } }, "responses": { "200": { "description": "Native confirmed completed update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComputerTemplateCapture" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" }, "504": { "$ref": "#/components/responses/Error" } } } }, "/computers/{id}/commands": { "post": { "operationId": "ExecuteComputerCommand", "tags": [ "Resources" ], "description": "Execute one shell command with current Computer control permission. A paused managed Computer resumes before execution. Returns native stdout, stderr and exit code; a nonzero exit is a completed command. Combined output is at most8 MiB. Commands are never retried or replayed. An operation-owned HTTP proxy substitutes authorized Organization-name Vault references in HTTPS requests and redacts returned values. Attached commands run as the signed-in user through the native connector. Windows uses Git Bash, installed for the current user when absent, and an operation-owned loopback SSH carrier for the HTTP proxy without a host SSH service. HTTP(S) clients receive proxy and CA defaults; clients that bypass those settings receive no automatic Vault substitution. Provider credentials stay in the API.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Select an organization for session credentials. Bearer keys remain bound to their organization." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComputerCommandInput" } } } }, "responses": { "200": { "description": "Native command result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComputerCommandResult" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" }, "504": { "$ref": "#/components/responses/Error" } } } }, "/computers/{id}/terminal": { "get": { "operationId": "ComputerTerminal", "tags": [ "Resources" ], "description": "Open an interactive shell with current Computer control permission. The first text message must be {\"type\":\"resize\",\"cols\":80,\"rows\":24}. Later text messages resize the terminal. Dimensions are integers from 1 to 1000. Wait for {\"type\":\"ready\"} before sending binary keyboard input. Binary server messages carry terminal output; {\"type\":\"exit\",\"code\":0} reports shell exit, with an optional message on failure. Client messages are at most64 KiB. Closing the socket closes the shell. A managed Computer resumes if paused. An attached Computer must be online. An admitted connection retains its permission through closure; each new connection checks current authority. A terminal is never replayed. The shell receives connection-owned HTTP(S) proxy and CA defaults. Vault substitution checks current Vault authority for the original caller; clients that bypass the proxy receive no automatic substitution.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Select an organization for session credentials. Bearer keys remain bound to their organization." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "organization_id", "in": "query", "description": "Organization selection for browser WebSockets. Must match an API credential's Organization and the header when both are supplied. Current membership is checked.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "101": { "description": "Native terminal WebSocket." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "426": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "x-native-transports": { "websocket": { "payload": "Pibo terminal text resize/ready/exit and binary stdin/output protocol" } } } }, "/vault-secrets": { "get": { "operationId": "ListVaultSecrets", "tags": [ "Foundation" ], "description": "List current authorized metadata, including revoked or pending entries when visible. Values and native secret identities remain private.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int64", "minimum": 1, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Case-insensitive literal substring of name; empty matches every authorized name." }, { "name": "name", "in": "query", "schema": { "type": "string" }, "description": "Case-insensitive exact name; empty disables this filter." }, { "name": "active", "in": "query", "schema": { "type": "boolean" }, "description": "Filter by revocation only; a pending entry has no usable version." }, { "name": "scope", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/VaultScope" } } }, { "name": "scope_id", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } } } ], "responses": { "200": { "description": "Authorized result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaultSecretPage" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "CreateVaultSecret", "tags": [ "Foundation" ], "description": "Create a private native value under an explicit authorized scope. Return the original immutable entry/version reference, including equal replay after rotation or revocation. A reserved creation without a completed native binding returns conflict and performs no automatic recovery.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Authorized result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaultSecretReference" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterVaultSecret" } } } } } }, "/vault-secrets/{id}": { "get": { "operationId": "ReadVaultSecret", "tags": [ "Foundation" ], "description": "Read current authorized metadata and selected version identity. Secret values, fingerprints and native secret references are never returned.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Authorized result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaultSecret" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "put": { "operationId": "UpdateVaultSecret", "tags": [ "Foundation" ], "description": "Update absolute supplied fields. Native immutable rotation runs outside SQL; concurrent different version publication conflicts. Existing Computer bindings retain their exact version.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Authorized result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaultSecret" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaultSecretInput" } } } } }, "delete": { "operationId": "RevokeVaultSecret", "tags": [ "Foundation" ], "description": "Revoke future native consumer admissions. Repetition preserves the first revoke timestamp and all original references. This does not rotate credentials at their issuer or retract already admitted values.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Authorized result." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/network-rules": { "get": { "operationId": "ListNetworkRules", "tags": [ "Foundation" ], "description": "Requires organization.read. Ordinary readers see Organization rules and currently readable Agent/Template scopes within credential ceilings.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int64", "minimum": 1, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Case-insensitive literal substring of rule or scope name. Empty matches all visible rules." }, { "name": "scope", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkRuleScope" } } }, { "name": "scope_id", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } } } ], "responses": { "200": { "description": "Authorized result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkRulePage" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" }, "504": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "CreateNetworkRule", "tags": [ "Foundation" ], "description": "Requires organization.update. Save metadata and its revision, commit, then await affected gateways confirming the current database revision when the Computer VPN is enabled. Disabled Organizations retain rule definitions without enforcing them. Application failures return an error and retain saved metadata and completed applications; read the resource before changing it again. No fleet rollback or background retry is promised.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkRuleInput" } } } }, "responses": { "201": { "description": "Authorized result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkRule" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" }, "504": { "$ref": "#/components/responses/Error" } } } }, "/network-rules/{id}": { "get": { "operationId": "ReadNetworkRule", "tags": [ "Foundation" ], "description": "Requires organization.read. Ordinary readers see Organization rules and currently readable Agent/Template scopes within credential ceilings.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Authorized result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkRule" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" }, "504": { "$ref": "#/components/responses/Error" } } }, "put": { "operationId": "UpdateNetworkRule", "tags": [ "Foundation" ], "description": "Requires organization.update. Save metadata and its revision, commit, then await affected gateways confirming the current database revision when the Computer VPN is enabled. Disabled Organizations retain rule definitions without enforcing them. Application failures return an error and retain saved metadata and completed applications; read the resource before changing it again. No fleet rollback or background retry is promised.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateNetworkRuleInput" } } } }, "responses": { "200": { "description": "Authorized result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkRule" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" }, "504": { "$ref": "#/components/responses/Error" } } }, "delete": { "operationId": "DeleteNetworkRule", "tags": [ "Foundation" ], "description": "Requires organization.update. Save metadata and its revision, commit, then await affected gateways confirming the current database revision when the Computer VPN is enabled. Disabled Organizations retain rule definitions without enforcing them. Application failures return an error and retain saved metadata and completed applications; read the resource before changing it again. No fleet rollback or background retry is promised.", "parameters": [ { "name": "X-Organization-ID", "in": "header", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Authorized result." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" }, "504": { "$ref": "#/components/responses/Error" } } } }, "/computers/{id}/desktop-actions/{action_id}": { "delete": { "operationId": "CancelDesktopAction", "tags": [ "Completion" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "action_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "session_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FillAction" } } }, "description": "Native result." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/computers/{id}/desktop-actions/{action_id}/input": { "post": { "operationId": "SubmitDesktopInput", "tags": [ "Completion" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "action_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FillAction" } } }, "description": "Native result." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FillInputSubmission" } } } } } }, "/mcp-connections": { "get": { "operationId": "ListMcpConnections", "tags": [ "Completion" ], "description": "List configured remote MCP connections from this Agent, its eligible Template, the original User and Organization. Includes overridden connections for management, ordered by case-sensitive name, scope and owner ID. Requires Agent read authority; User scope belongs only to the original Organization membership. Configuration files use shared/mcp.json, users//mcp.json, agent-templates//mcp.json and agents//mcp.json.", "parameters": [ { "name": "agent_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 50 } }, { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpConnectionPage" } } }, "description": "Native result." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/mcp-connections/{connection}/authorization": { "post": { "operationId": "AuthorizeMcpConnection", "tags": [ "Completion" ], "description": "Connect the Agent's configured remote MCP server. Returns ready with its tool catalog, or authorization_required with the provider's OAuth authorization URL. Requires Agent write authority and, with computer_id, Computer use.", "parameters": [ { "name": "connection", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 8192 } }, { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpConnectionState" } } }, "description": "Native result." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "delete": { "operationId": "DisconnectMcpConnection", "tags": [ "Completion" ], "description": "Forget the connection's OAuth grant and ask the provider to revoke it. revoked reports the provider's answer. Requires Agent write authority.", "parameters": [ { "name": "connection", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 8192 } }, { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpDisconnection" } } }, "description": "Native result." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/mcp-connections/{connection}/client-metadata": { "get": { "operationId": "ReadMcpClientMetadata", "tags": [ "Completion" ], "description": "Public OAuth client metadata document for this connection. It contains fixed Completion redirect URLs and no grant data.", "security": [], "parameters": [ { "name": "connection", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 8192 } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpClientMetadata" } } }, "description": "Native result." }, "400": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } } } }, "/mcp-connections/{connection}/oauth-callbacks": { "get": { "operationId": "CompleteMcpAuthorization", "tags": [ "Completion" ], "description": "OAuth redirect target. The provider's code and state must match the saved authorization attempt.", "security": [], "parameters": [ { "name": "connection", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 8192 } }, { "name": "code", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 8192 } }, { "name": "state", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 8192 } }, { "name": "iss", "in": "query", "schema": { "type": "string", "maxLength": 8192 } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpAuthorization" } } }, "description": "Native result." }, "400": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/agents/{id}/remote-mcp-tools": { "get": { "operationId": "ListRemoteMcpTools", "tags": [ "Completion" ], "description": "Select remote MCP servers by case-insensitive name with Agent, Template, original User, Organization precedence, ordered by name, and return its state and tool catalog. A connection that fails returns state error. Requires Agent read authority and, for a connection with computer_id, Computer use.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 50 } }, { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoteMcpToolPage" } } }, "description": "Native result." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/agents/{id}/remote-mcp-tool-calls": { "post": { "operationId": "CallRemoteMcpTool", "tags": [ "Completion" ], "description": "Call one tool on this caller's selected scoped remote MCP connection and return the native MCP CallToolResult. Requires Agent read authority and, with computer_id, Computer use. Vault placeholders in configured headers use the caller's current Vault authority.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoteMcpToolCallInput" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "description": "Native MCP CallToolResult." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/agents/{id}/action-reviews": { "get": { "operationId": "ListActionReviews", "tags": [ "Completion" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "session_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 30 }, "description": "Requested upper bound on this page. The owner may return fewer items to satisfy its native response/transport bounds. Use the returned cursor to continue." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "approved", "denied", "cancelled", "consumed", "active" ] } }, { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionReviewPage" } } }, "description": "Native result." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "ReviewAgentAction", "tags": [ "Completion" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionReviewInput" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionReviewResult" } } }, "description": "Native result." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } } } }, "/agents/{id}/action-reviews/{review_id}": { "delete": { "operationId": "CancelActionReview", "tags": [ "Completion" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "review_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionReview" } } }, "description": "Native result." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } } }, "get": { "operationId": "GetActionReview", "tags": [ "Completion" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "review_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionReview" } } }, "description": "Native result." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } } } }, "/agents/{id}/action-reviews/{review_id}/decision": { "post": { "operationId": "DecideActionReview", "tags": [ "Completion" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "review_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Organization-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionReviewDecision" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionReview" } } }, "description": "Native result." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "summary": "Decide an action review" } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "User, agent, or template-scoped setup API key." }, "BrowserSession": { "type": "apiKey", "in": "cookie", "name": "completion_auth", "description": "HttpOnly browser session. Organization operations also need X-Organization-ID." }, "ComputerDeviceCredential": { "type": "http", "scheme": "bearer", "description": "The private device credential saved by the native connector." } }, "schemas": { "APIKey": { "type": "object", "additionalProperties": false, "required": [ "id", "user_id", "native_scope", "expires_at", "revoked_at", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" }, "native_scope": { "$ref": "#/components/schemas/NativeScope" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "revoked_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "APIKeyCreated": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "native_scope": { "$ref": "#/components/schemas/NativeScope" }, "revoked_at": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "id", "native_scope", "revoked_at" ] }, "APIKeyPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/APIKey" } }, "next_cursor": { "type": "string", "nullable": true }, "has_more": { "type": "boolean" } }, "required": [ "items", "next_cursor", "has_more" ] }, "Account": { "type": "object", "properties": { "deletion_id": { "type": "string", "format": "uuid", "nullable": true }, "user": { "$ref": "#/components/schemas/User" }, "organization": { "allOf": [ { "$ref": "#/components/schemas/OrganizationIdentity" } ], "nullable": true } }, "required": [ "user", "organization" ] }, "AccountSettingsResult": { "type": "object", "additionalProperties": false, "required": [ "user" ], "properties": { "user": { "$ref": "#/components/schemas/User" } } }, "ActionReview": { "type": "object", "additionalProperties": false, "required": [ "id", "session_id", "status", "created_at", "updated_at" ], "properties": { "task_id": { "type": "integer", "format": "int64", "minimum": 1 }, "input_id": { "type": "string", "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "session_id": { "type": "string", "format": "uuid", "nullable": true }, "action_id": { "type": "string" }, "status": { "$ref": "#/components/schemas/ActionReviewStatus" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "decided_by": { "type": "string", "format": "uuid", "nullable": true }, "decided_at": { "type": "string", "format": "date-time", "nullable": true } } }, "ActionReviewDecision": { "type": "object", "additionalProperties": false, "required": [ "decision" ], "properties": { "decision": { "type": "string", "enum": [ "approve", "deny" ] } } }, "ActionReviewInput": { "type": "object", "additionalProperties": false, "required": [ "session_id", "task_id" ], "properties": { "session_id": { "type": "string", "format": "uuid", "description": "Session that owns this native task. Task IDs are local to its namespace store." }, "task_id": { "type": "integer", "format": "int64", "minimum": 1 } } }, "ActionReviewPage": { "type": "object", "additionalProperties": false, "required": [ "items", "has_more" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ActionReview" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string" } } }, "ActionReviewResult": { "type": "object", "additionalProperties": false, "required": [ "decision" ], "properties": { "decision": { "$ref": "#/components/schemas/GuardrailDecision" }, "review": { "$ref": "#/components/schemas/ActionReview" } } }, "ActionReviewStatus": { "type": "string", "enum": [ "pending", "approved", "denied", "cancelled", "consumed" ] }, "Agent": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "owner_member_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Owning organization membership. Membership deletion sets this to null without deleting the resource. Organization administrators retain resource management authority regardless of ownership, subject to credential scope ceilings; access does not assign ownership." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "allowed_permissions": { "type": "array", "items": { "type": "string" } }, "title": { "type": "string" }, "archived": { "type": "boolean" }, "parent_agent_id": { "type": "string", "format": "uuid", "nullable": true }, "agent_template_id": { "type": "string", "format": "uuid", "nullable": true }, "agent_template_version_id": { "type": "string", "format": "uuid", "nullable": true }, "namespace_id": { "type": "string", "minLength": 1 }, "computer_id": { "type": "string", "format": "uuid", "nullable": true }, "browser_id": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string", "enum": [ "allocated", "preparing", "ready", "failed" ] }, "last_error": { "type": "string", "nullable": true } }, "required": [ "id", "organization_id", "owner_member_id", "created_at", "updated_at", "allowed_permissions", "title", "archived", "parent_agent_id", "agent_template_id", "agent_template_version_id", "namespace_id", "computer_id", "browser_id", "status", "last_error" ] }, "AgentConfiguration": { "type": "object", "additionalProperties": false, "properties": { "plugins": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 } }, "model": { "type": "string", "minLength": 1 }, "reasoning_effort": { "type": "string", "enum": [ "off", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "priority": { "type": "boolean" }, "instructions": { "type": "string" }, "tools": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 }, "nullable": true }, "skills": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 }, "nullable": true }, "mcp_servers": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 }, "nullable": true }, "voice": { "allOf": [ { "$ref": "#/components/schemas/VoiceSettings" } ], "nullable": true }, "max_goal_token_budget": { "type": "integer", "format": "int64", "minimum": 1 } }, "description": "Agent program settings, owned by the program store rather than copied into resource metadata." }, "AgentInputReceipt": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string", "format": "uuid" }, "session_id": { "type": "string", "format": "uuid" }, "namespace_id": { "type": "string", "minLength": 1 } }, "required": [ "id", "agent_id", "session_id", "namespace_id" ] }, "AgentPage": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Agent" } }, "next_cursor": { "type": "string", "nullable": true }, "has_more": { "type": "boolean" } }, "required": [ "items", "next_cursor", "has_more" ] }, "AgentPermission": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string", "format": "uuid" }, "member_id": { "type": "string", "format": "uuid", "nullable": true }, "grantee_agent_id": { "type": "string", "format": "uuid", "nullable": true }, "role": { "type": "string", "enum": [ "viewer", "writer" ] }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "agent_id", "member_id", "grantee_agent_id", "role", "expires_at", "created_at" ] }, "AgentPermissionPage": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AgentPermission" } }, "next_cursor": { "type": "string", "nullable": true }, "has_more": { "type": "boolean" } }, "required": [ "items", "next_cursor", "has_more" ] }, "AgentSession": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string", "format": "uuid" }, "parent_session_id": { "type": "string", "format": "uuid", "nullable": true }, "namespace_id": { "type": "string", "minLength": 1 }, "computer_id": { "type": "string", "format": "uuid", "nullable": true }, "browser_id": { "type": "string", "format": "uuid", "nullable": true }, "settings": { "$ref": "#/components/schemas/AgentSettings" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "organization_id", "agent_id", "parent_session_id", "namespace_id", "computer_id", "browser_id", "settings", "created_at" ] }, "AgentSessionEventPage": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/NativeEntry" } }, "next_cursor": { "type": "string", "nullable": true, "description": "Continuation after the last returned native entry. Retain it while polling, including when has_more is false. Empty pages preserve the supplied continuation." }, "has_more": { "type": "boolean", "description": "More entries are currently committed after this page; false does not end polling." } }, "required": [ "items", "next_cursor", "has_more" ] }, "AgentSessionPage": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AgentSession" } }, "next_cursor": { "type": "string", "nullable": true }, "has_more": { "type": "boolean" } }, "required": [ "items", "next_cursor", "has_more" ] }, "AgentSettings": { "type": "object", "additionalProperties": false, "properties": { "plugins": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 } }, "model": { "type": "string", "minLength": 1 }, "reasoning_effort": { "type": "string", "enum": [ "off", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "priority": { "type": "boolean" }, "instructions": { "type": "string" }, "tools": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 }, "nullable": true }, "skills": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 }, "nullable": true }, "mcp_servers": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 }, "nullable": true }, "voice": { "allOf": [ { "$ref": "#/components/schemas/VoiceSettings" } ], "nullable": true } }, "description": "Behavior settings. Omission preserves/inherits a field. Supplied arrays replace it. Null tool/skill/MCP selections select all eligible entries; empty arrays select none. Null voice clears voice settings. Settings do not grant authority." }, "AgentTemplate": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "owner_member_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Owning organization membership. Membership deletion sets this to null without deleting the resource. Organization administrators retain resource management authority regardless of ownership, subject to credential scope ceilings; access does not assign ownership." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "allowed_permissions": { "type": "array", "items": { "type": "string" } }, "name": { "type": "string", "minLength": 1 }, "source_agent_id": { "type": "string", "format": "uuid", "nullable": true }, "computer_template_id": { "type": "string", "format": "uuid", "nullable": true }, "browser_template_id": { "type": "string", "format": "uuid", "nullable": true }, "current_version_id": { "type": "string", "format": "uuid", "nullable": true }, "program_ref": { "allOf": [ { "$ref": "#/components/schemas/ProgramReference" } ], "nullable": true }, "status": { "type": "string", "enum": [ "draft", "publishing", "ready", "failed" ] }, "last_error": { "type": "string", "nullable": true } }, "required": [ "id", "organization_id", "owner_member_id", "created_at", "updated_at", "allowed_permissions", "name", "source_agent_id", "computer_template_id", "browser_template_id", "current_version_id", "program_ref", "status", "last_error" ] }, "AgentTemplatePage": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AgentTemplate" } }, "next_cursor": { "type": "string", "nullable": true }, "has_more": { "type": "boolean" } }, "required": [ "items", "next_cursor", "has_more" ] }, "AgentTemplateVersion": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "agent_template_id": { "type": "string", "format": "uuid" }, "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "ready", "failed" ] }, "created_at": { "type": "string", "format": "date-time" }, "last_error": { "type": "string", "nullable": true }, "program_ref": { "allOf": [ { "$ref": "#/components/schemas/ProgramReference" } ], "nullable": true } }, "required": [ "id", "agent_template_id", "request_id", "status", "created_at", "last_error", "program_ref" ] }, "BashResult": { "type": "object", "additionalProperties": false, "properties": { "stdout": { "type": "string" }, "stderr": { "type": "string" }, "exit_code": { "type": "integer" } }, "required": [ "stdout", "stderr", "exit_code" ] }, "Browser": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "owner_member_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Owning organization membership. Membership deletion sets this to null without deleting the resource. Organization administrators retain resource management authority regardless of ownership, subject to credential scope ceilings; access does not assign ownership." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "allowed_permissions": { "type": "array", "items": { "type": "string" } }, "name": { "type": "string", "minLength": 1 }, "provider": { "type": "string", "minLength": 1 }, "browser_template_id": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string", "enum": [ "allocated", "provisioning", "ready", "failed", "closed" ] }, "last_error": { "type": "string", "nullable": true }, "start_url": { "type": "string", "nullable": true } }, "required": [ "id", "organization_id", "owner_member_id", "created_at", "updated_at", "allowed_permissions", "name", "provider", "browser_template_id", "status", "last_error", "start_url" ] }, "BrowserPage": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Browser" } }, "next_cursor": { "type": "string", "nullable": true }, "has_more": { "type": "boolean" } }, "required": [ "items", "next_cursor", "has_more" ] }, "BrowserTemplate": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "owner_member_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Owning organization membership. Membership deletion sets this to null without deleting the resource. Organization administrators retain resource management authority regardless of ownership, subject to credential scope ceilings; access does not assign ownership." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "allowed_permissions": { "type": "array", "items": { "type": "string" } }, "name": { "type": "string", "minLength": 1 }, "provider": { "type": "string", "minLength": 1 }, "current_capture_id": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string", "enum": [ "pending", "ready", "failed" ] }, "last_error": { "type": "string", "nullable": true }, "source_browser_id": { "type": "string", "format": "uuid" }, "start_url": { "type": "string", "nullable": true } }, "required": [ "id", "organization_id", "owner_member_id", "created_at", "updated_at", "allowed_permissions", "name", "provider", "current_capture_id", "status", "last_error", "source_browser_id", "start_url" ] }, "BrowserTemplateCapture": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "browser_template_id": { "type": "string", "format": "uuid" }, "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "ready", "failed" ] }, "created_at": { "type": "string", "format": "date-time" }, "last_error": { "type": "string", "nullable": true } }, "required": [ "id", "browser_template_id", "request_id", "status", "created_at", "last_error" ] }, "BrowserTemplatePage": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/BrowserTemplate" } }, "next_cursor": { "type": "string", "nullable": true }, "has_more": { "type": "boolean" } }, "required": [ "items", "next_cursor", "has_more" ] }, "Computer": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "owner_member_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Owning organization membership. Membership deletion sets this to null without deleting the resource. Organization administrators retain resource management authority regardless of ownership, subject to credential scope ceilings; access does not assign ownership." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "allowed_permissions": { "type": "array", "items": { "type": "string" } }, "name": { "type": "string", "minLength": 1 }, "provider": { "type": "string", "minLength": 1 }, "computer_template_id": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string", "enum": [ "allocated", "provisioning", "running", "paused", "failed", "closed" ] }, "last_error": { "type": "string", "nullable": true }, "platform": { "type": "string", "nullable": true }, "architecture": { "type": "string", "nullable": true }, "os_user": { "type": "string", "nullable": true }, "runtime_build": { "type": "string", "nullable": true }, "installed_version": { "type": "string", "nullable": true }, "resume_expires_at": { "type": "string", "format": "date-time", "nullable": true }, "connection": { "description": "Live native relay observation for an attached Computer. Managed Computers omit this field. Relay errors fail the read instead of reporting an offline device.", "$ref": "#/components/schemas/ComputerConnection" } }, "required": [ "id", "organization_id", "owner_member_id", "created_at", "updated_at", "allowed_permissions", "name", "provider", "computer_template_id", "status", "last_error", "platform", "architecture", "os_user", "runtime_build", "installed_version", "resume_expires_at" ] }, "ComputerCommandInput": { "type": "object", "additionalProperties": false, "properties": { "command": { "type": "string", "minLength": 1, "maxLength": 32768 }, "cwd": { "type": "string", "minLength": 1, "maxLength": 4096 }, "timeout_ms": { "type": "integer", "minimum": 1, "maximum": 300000, "default": 30000 } }, "required": [ "command" ] }, "ComputerCommandResult": { "type": "object", "additionalProperties": false, "properties": { "stdout": { "type": "string" }, "stderr": { "type": "string" }, "exit_code": { "type": "integer" } }, "required": [ "stdout", "stderr", "exit_code" ] }, "ComputerConnection": { "type": "object", "additionalProperties": false, "properties": { "online": { "type": "boolean" }, "runtime_build": { "type": "string", "nullable": true }, "observations": { "type": "array", "items": { "$ref": "#/components/schemas/ComputerFeatureObservation" } } }, "required": [ "online", "runtime_build", "observations" ] }, "ComputerCredentialReference": { "type": "object", "additionalProperties": false, "required": [ "id", "version_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "version_id": { "type": "string", "minLength": 1 } } }, "ComputerFeatureObservation": { "type": "object", "additionalProperties": false, "properties": { "feature": { "type": "string", "enum": [ "terminal", "bash", "desktop", "control" ] }, "result": { "type": "string", "enum": [ "ready", "not_checked", "unavailable" ] }, "reason": { "type": "string" } }, "required": [ "feature", "result" ] }, "ComputerPage": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Computer" } }, "next_cursor": { "type": "string", "nullable": true }, "has_more": { "type": "boolean" } }, "required": [ "items", "next_cursor", "has_more" ] }, "ComputerPairing": { "type": "object", "additionalProperties": false, "required": [ "computer_id", "organization_id", "id", "user_code", "name", "platform", "architecture", "os_user", "runtime_build", "expires_at", "verification_uri" ], "properties": { "computer_id": { "type": "string", "format": "uuid", "nullable": true }, "organization_id": { "type": "string", "format": "uuid", "nullable": true }, "id": { "type": "string", "format": "uuid" }, "user_code": { "type": "string" }, "name": { "type": "string" }, "platform": { "type": "string", "enum": [ "darwin", "linux", "windows" ] }, "architecture": { "type": "string", "enum": [ "amd64", "arm64" ] }, "os_user": { "type": "string" }, "runtime_build": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "verification_uri": { "type": "string", "format": "uri" } } }, "ComputerPairingApproval": { "type": "object", "additionalProperties": false, "required": [ "id", "organization_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" } } }, "ComputerPairingCodeInput": { "type": "object", "additionalProperties": false, "required": [ "user_code" ], "properties": { "user_code": { "type": "string", "pattern": "^[A-Z2-7]{4}-?[A-Z2-7]{4}$", "maxLength": 9 } } }, "ComputerSoftwareUpdateInput": { "type": "object", "additionalProperties": false, "required": [ "request_id", "target_build" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "target_build": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } }, "ComputerSoftwareUpdateStatus": { "type": "object", "additionalProperties": false, "required": [ "can_update", "selected_build", "selected_version", "available_build", "available_version", "update_available" ], "properties": { "can_update": { "type": "boolean" }, "selected_build": { "type": "string" }, "selected_version": { "type": "string" }, "available_build": { "type": "string" }, "available_version": { "type": "string" }, "update_available": { "type": "boolean" } } }, "ComputerTemplate": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "owner_member_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Owning organization membership. Membership deletion sets this to null without deleting the resource. Organization administrators retain resource management authority regardless of ownership, subject to credential scope ceilings; access does not assign ownership." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "allowed_permissions": { "type": "array", "items": { "type": "string" } }, "name": { "type": "string", "minLength": 1 }, "provider": { "type": "string", "minLength": 1 }, "current_capture_id": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string", "enum": [ "pending", "ready", "failed", "closed" ] }, "last_error": { "type": "string", "nullable": true }, "source_computer_id": { "type": "string", "format": "uuid" } }, "required": [ "id", "organization_id", "owner_member_id", "created_at", "updated_at", "allowed_permissions", "name", "provider", "current_capture_id", "status", "last_error", "source_computer_id" ] }, "ComputerTemplateCapture": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "computer_template_id": { "type": "string", "format": "uuid" }, "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "ready", "failed" ] }, "created_at": { "type": "string", "format": "date-time" }, "last_error": { "type": "string", "nullable": true }, "interrupts_computer": { "type": "boolean" }, "retention_seconds": { "type": "integer", "format": "int64" }, "expires_at": { "type": "string", "format": "date-time" }, "source_status": { "type": "string" } }, "required": [ "id", "computer_template_id", "request_id", "status", "created_at", "last_error" ] }, "ComputerTemplatePage": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ComputerTemplate" } }, "next_cursor": { "type": "string", "nullable": true }, "has_more": { "type": "boolean" } }, "required": [ "items", "next_cursor", "has_more" ] }, "ContinueSignInInput": { "type": "object", "additionalProperties": false, "required": [ "code" ], "properties": { "code": { "type": "string", "minLength": 6, "maxLength": 6, "writeOnly": true, "description": "Six decimal digits from the delivered email. Never log this value." } } }, "CreateAgentInput": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "agent_template_id": { "type": "string", "format": "uuid" }, "computer_template_id": { "type": "string", "format": "uuid", "nullable": true }, "browser_template_id": { "type": "string", "format": "uuid", "nullable": true }, "computer_id": { "type": "string", "format": "uuid", "nullable": true }, "browser_id": { "type": "string", "format": "uuid", "nullable": true }, "parent_agent_id": { "type": "string", "format": "uuid", "nullable": true }, "title": { "type": "string" }, "settings": { "$ref": "#/components/schemas/AgentConfiguration" }, "permissions": { "type": "array", "items": { "$ref": "#/components/schemas/CreateAgentPermissionInput" } } }, "required": [ "id" ], "description": "Define an Agent allocation. Select an existing Computer/Browser or a Template for that resource, never both. No model input is submitted. Published Template selection is resolved and pinned internally.", "not": { "anyOf": [ { "required": [ "computer_id", "computer_template_id" ] }, { "required": [ "browser_id", "browser_template_id" ] } ] } }, "CreateAgentMessageInput": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "content": { "type": "string", "minLength": 1 }, "mode": { "type": "string", "enum": [ "queue", "steer", "restart" ], "default": "queue", "description": "Delivery of a new message. Queue follows the current run; steer joins it after the current tool round; restart interrupts the active run and submits this input without resetting history. Reusing a message ID changes content only and retains its original mode." } }, "required": [ "id", "content" ] }, "CreateAgentPermissionInput": { "type": "object", "additionalProperties": false, "description": "At most one subject may be non-null. Both null grant organization-wide access. Subjects must belong to this organization.", "properties": { "member_id": { "type": "string", "format": "uuid", "nullable": true }, "grantee_agent_id": { "type": "string", "format": "uuid", "nullable": true }, "role": { "type": "string", "enum": [ "viewer", "writer" ] }, "expires_at": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "role" ] }, "CreateAgentSessionInput": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "parent_session_id": { "type": "string", "format": "uuid", "nullable": true }, "namespace_id": { "type": "string", "minLength": 1, "description": "Authorized namespace node ID. Omit to inherit the Agent or parent selection; null is invalid." }, "computer_id": { "type": "string", "format": "uuid" }, "browser_id": { "type": "string", "format": "uuid" }, "settings": { "$ref": "#/components/schemas/AgentSettings" } }, "required": [ "id" ], "description": "Allocate Session metadata without submitting work. Omitted selections inherit from the Agent or parent; explicit selections require authority. Namespace binding is immutable. No fork or checkpoint input is accepted." }, "CreateAgentTemplateInput": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1 }, "source_agent_id": { "type": "string", "format": "uuid" }, "computer_template_id": { "type": "string", "format": "uuid", "nullable": true }, "browser_template_id": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "id", "name" ] }, "CreateBrowserInput": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "browser_template_id": { "type": "string", "format": "uuid" }, "provider": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "source": { "type": "object", "additionalProperties": true } }, "required": [ "id" ], "description": "Allocate a fresh independent Kernel profile without a live Browser. Set provider=\"kernel\" and omit source and browser_template_id. Existing native profile import, Template instantiation and other providers return 422 because Kernel has no profile-only clone or import operation. A raw native identifier does not establish Completion authority.", "not": { "anyOf": [ { "required": [ "browser_template_id", "provider" ] }, { "required": [ "browser_template_id", "source" ] }, { "not": { "anyOf": [ { "required": [ "browser_template_id" ] }, { "required": [ "provider" ] } ] } } ] } }, "CreateBrowserTemplateInput": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "source_browser_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1 }, "start_url": { "type": "string" } }, "required": [ "id", "source_browser_id", "name" ] }, "CreateComputerInput": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "computer_template_id": { "type": "string", "format": "uuid" }, "provider": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "source": { "type": "object", "additionalProperties": true, "description": "Native image or snapshot selection only. E2B accepts templateID; Daytona accepts snapshot or image, with an optional native target region; Modal accepts image_id or image; Boat accepts from and type; Vercel accepts snapshot_id or image; Archil accepts image_id or base_image. Vercel and Archil identifiers must be nonempty strings. An empty object selects the configured native image default. API destinations, account/app/environment settings and credentials belong to the immutable Vault connection and are rejected in source. Native source overrides require explicitly supplied authorized Vault references. Completion-default creation accepts an empty source; other copies use an authorized Computer or Template." }, "computer_id": { "type": "string", "format": "uuid" }, "credential_references": { "type": "object", "description": "Exact Vault version references keyed by E2B_SANDBOX, DAYTONA_SANDBOX, MODAL_SANDBOX, BOAT_SANDBOX, VERCEL_SANDBOX or ARCHIL_SANDBOX. Each provider takes exactly one JSON text Vault value containing its credentials and connection/account settings. E2B/Daytona use api_key and optional api_url; Modal uses token_id, token_secret and optional app_name and environment; Boat uses api_key and optional api_url and org. Vercel uses token, team_id and project_id; Archil uses api_key and api_url. Omission on a fresh provider source selects its configured Completion Vault connection with an empty source. Explicit empty references do not select a default. Derived creation retains the exact source binding.", "additionalProperties": { "$ref": "#/components/schemas/ComputerCredentialReference" } } }, "required": [ "id" ], "description": "Create an independent Computer from an explicit native provider source, current Template capture, or caller-authorized source Computer. Computer forks automatically preserve memory when the provider advertises memory capture; otherwise they use a disk snapshot clone. Template copies restore the captured state. Provider credentials are authorized Vault version references. Fresh provider sources use the configured Completion connection when references are omitted, and supplied references select the customer's connection. No model turn is started. Creation from a Computer or Template retains the source's exact provider Vault binding. If credential_references is supplied for derived creation, it must match that binding; cross-account copying is unsupported.", "oneOf": [ { "required": [ "computer_template_id" ], "not": { "anyOf": [ { "required": [ "provider" ] }, { "required": [ "source" ] }, { "required": [ "computer_id" ] } ] } }, { "required": [ "provider", "source" ], "not": { "anyOf": [ { "required": [ "computer_template_id" ] }, { "required": [ "computer_id" ] } ] } }, { "required": [ "computer_id" ], "not": { "anyOf": [ { "required": [ "provider" ] }, { "required": [ "source" ] }, { "required": [ "computer_template_id" ] } ] } } ] }, "CreateComputerPairingInput": { "type": "object", "description": "Retain the ID and private device credential for pairing renewal. An unexpired pairing also requires unchanged device details. After expiry, an unapproved pairing can renew its code, expiry and device details. Never use renewal to reset an approved Computer.", "additionalProperties": false, "required": [ "id", "credential", "name", "platform", "architecture", "os_user", "runtime_build" ], "properties": { "id": { "type": "string", "format": "uuid" }, "credential": { "type": "string", "format": "password", "writeOnly": true, "pattern": "^[A-Za-z0-9_-]{43}$", "minLength": 43, "maxLength": 43 }, "name": { "type": "string", "maxLength": 200, "minLength": 1 }, "platform": { "type": "string", "enum": [ "darwin", "linux", "windows" ] }, "architecture": { "type": "string", "enum": [ "amd64", "arm64" ] }, "os_user": { "type": "string", "maxLength": 200, "minLength": 1 }, "runtime_build": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } }, "CreateComputerTemplateInput": { "description": "Capture the source Computer automatically with memory when the provider supports it, otherwise capture disk state.", "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "computer_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1 } }, "required": [ "id", "computer_id", "name" ] }, "CreateFilesystemPermissionInput": { "type": "object", "additionalProperties": false, "properties": { "member_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Same-organization membership; null grants organization-wide access." }, "role": { "type": "string", "enum": [ "reader", "writer" ] }, "expires_at": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "member_id", "role" ] }, "CreateNamespacePermissionInput": { "type": "object", "additionalProperties": false, "description": "At most one subject may be non-null. Both null grant organization-wide access. Subjects must belong to this organization.", "properties": { "member_id": { "type": "string", "format": "uuid", "nullable": true }, "grantee_agent_id": { "type": "string", "format": "uuid", "nullable": true }, "role": { "type": "string", "enum": [ "reader", "writer" ] }, "expires_at": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "role" ] }, "CreateOrganizationInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "request_id": { "type": "string", "minLength": 1 } }, "required": [ "name", "request_id" ], "additionalProperties": false }, "DesktopAccess": { "type": "object", "additionalProperties": false, "required": [ "url", "protocol" ], "properties": { "url": { "type": "string" }, "protocol": { "type": "string", "enum": [ "rfb", "png" ] }, "password": { "type": "string" } } }, "ErrorBody": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } } }, "FilesystemCommand": { "type": "object", "additionalProperties": false, "properties": { "agent_id": { "type": "string", "format": "uuid", "description": "Agent whose persistent Archil sandbox runs the command. Selection requires current Agent write authority and does not grant filesystem access." }, "command": { "type": "string", "minLength": 1, "description": "One offline Bash script, within the HTTP request body transport limit. File paths are relative to the caller view mounted at /workspace." } }, "required": [ "agent_id", "command" ] }, "FilesystemPermission": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "node_id": { "type": "string", "minLength": 1 }, "member_id": { "type": "string", "format": "uuid", "nullable": true }, "role": { "type": "string", "enum": [ "reader", "writer" ] }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "node_id", "member_id", "role", "expires_at", "created_at" ] }, "FilesystemPermissionPage": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/FilesystemPermission" } }, "next_cursor": { "type": "string", "nullable": true }, "has_more": { "type": "boolean" } }, "required": [ "items", "next_cursor", "has_more" ] }, "FilesystemReference": { "type": "object", "additionalProperties": false, "properties": { "path": { "type": "string" } }, "required": [ "path" ] }, "FillAction": { "type": "object", "additionalProperties": false, "properties": { "kind": { "type": "string", "enum": [ "browser", "desktop" ] }, "resource_id": { "type": "string", "format": "uuid" }, "target": { "type": "string" }, "action_id": { "type": "string", "format": "uuid" }, "session_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "waiting_for_input", "running", "completed", "failed", "unknown", "cancelled" ] }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/FillFieldOutcome" } }, "error": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "target": { "type": "string" }, "label": { "type": "string" }, "vault_ref": { "type": "string" }, "vault_name": { "type": "string" } }, "required": [ "target" ] } }, "inputs": { "type": "array", "items": { "$ref": "#/components/schemas/MissingInput" } } }, "required": [ "kind", "resource_id", "target", "action_id", "status" ] }, "FillFieldOutcome": { "type": "object", "additionalProperties": false, "properties": { "index": { "type": "integer" }, "status": { "type": "string" }, "error_code": { "type": "string" } }, "required": [ "index", "status" ] }, "FillInputSubmission": { "type": "object", "additionalProperties": false, "properties": { "session_id": { "type": "string", "format": "uuid", "description": "Session that owns this native input request." }, "values": { "type": "array", "items": { "$ref": "#/components/schemas/FillInputValue" }, "minItems": 1 } }, "required": [ "values" ] }, "FillInputValue": { "type": "object", "additionalProperties": false, "properties": { "save": { "$ref": "#/components/schemas/VaultInputSave" }, "input_id": { "type": "string", "format": "uuid" }, "value": { "type": "string", "minLength": 1, "maxLength": 65536 } }, "required": [ "input_id", "value" ] }, "GuardrailDecision": { "type": "string", "enum": [ "allow", "ask_user", "block" ] }, "HTTPNetworkRule": { "type": "object", "additionalProperties": false, "required": [ "kind", "mode" ], "properties": { "kind": { "type": "string", "enum": [ "http" ] }, "mode": { "$ref": "#/components/schemas/NetworkRuleMode" }, "methods": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": "Case-sensitive native HTTP method tokens. Omitted means every method." }, "targets": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1, "maxLength": 4096 }, "description": "HTTP or HTTPS origin with optional path pattern and *. hostname suffix. No user information, query or fragment. Omitted path matches every path; * matches one nonempty segment and final ** matches the remaining path." } } }, "InboundConnectionRule": { "type": "object", "additionalProperties": false, "required": [ "kind", "direction", "mode" ], "properties": { "kind": { "type": "string", "enum": [ "connection" ] }, "direction": { "type": "string", "enum": [ "inbound" ] }, "mode": { "$ref": "#/components/schemas/NetworkRuleMode" }, "protocols": { "$ref": "#/components/schemas/NetworkRuleProtocols" }, "ports": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "integer", "minimum": 1, "maximum": 65535 } } } }, "McpAuthorization": { "type": "object", "additionalProperties": false, "required": [ "state" ], "properties": { "state": { "type": "string", "enum": [ "authorized" ] } } }, "McpClientMetadata": { "type": "object", "additionalProperties": false, "required": [ "client_id", "client_name", "redirect_uris", "grant_types", "response_types", "token_endpoint_auth_method" ], "description": "OAuth client ID metadata document; field names are the native OAuth names.", "properties": { "client_id": { "type": "string" }, "client_name": { "type": "string" }, "redirect_uris": { "type": "array", "items": { "type": "string" } }, "grant_types": { "type": "array", "items": { "type": "string" } }, "response_types": { "type": "array", "items": { "type": "string" } }, "token_endpoint_auth_method": { "type": "string" } } }, "McpConnection": { "type": "object", "additionalProperties": false, "required": [ "connection", "scope", "scope_id", "name", "url" ], "properties": { "connection": { "type": "string", "description": "Opaque canonical connection reference." }, "scope": { "type": "string", "enum": [ "organization", "user", "agent_template", "agent" ] }, "scope_id": { "type": "string", "format": "uuid", "description": "Scope owner. User scope uses the original global User ID within this Organization." }, "name": { "type": "string" }, "url": { "type": "string" }, "computer_id": { "type": "string", "format": "uuid", "description": "The connection's HTTP is carried through this Computer, so localhost is the Computer." }, "settings": { "$ref": "#/components/schemas/NativeRemoteMcpSettings" } } }, "McpConnectionPage": { "type": "object", "additionalProperties": false, "required": [ "items", "has_more" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/McpConnection" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string" } } }, "McpConnectionState": { "type": "object", "additionalProperties": false, "required": [ "connection", "name", "url", "state" ], "properties": { "connection": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "computer_id": { "type": "string", "format": "uuid" }, "settings": { "$ref": "#/components/schemas/NativeRemoteMcpSettings" }, "state": { "type": "string", "enum": [ "ready", "not_connected", "disconnected", "authorization_required", "error" ] }, "auth_url": { "type": "string", "description": "Provider authorization URL when state is authorization_required." }, "authorization_request_id": { "type": "string", "description": "Identifies this authorization attempt." }, "error": { "type": "string" }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Native MCP tool definitions when state is ready." } } }, "McpDisconnection": { "type": "object", "additionalProperties": false, "required": [ "state", "revoked" ], "properties": { "state": { "type": "string", "enum": [ "disconnected" ] }, "revoked": { "type": "boolean", "description": "Whether the provider accepted token revocation. False when it has no revocation endpoint or refused." } } }, "Member": { "type": "object", "properties": { "user_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "profile_image_url": { "type": "string", "nullable": true }, "id": { "type": "string", "format": "uuid" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "primary_owner", "owner", "admin", "member" ] }, "created_at": { "type": "string", "format": "date-time" }, "is_you": { "type": "boolean" }, "assignable_roles": { "type": "array", "items": { "type": "string", "enum": [ "owner", "admin", "member" ] } } }, "required": [ "id", "email", "role", "created_at", "is_you", "assignable_roles" ] }, "MemberPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Member" } }, "next_cursor": { "type": "string", "nullable": true }, "has_more": { "type": "boolean" } }, "required": [ "items", "next_cursor", "has_more" ] }, "MemberRoleInput": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "owner", "admin", "member" ] } }, "required": [ "role" ], "additionalProperties": false }, "MissingInput": { "type": "object", "additionalProperties": false, "properties": { "input_id": { "type": "string", "format": "uuid" }, "label": { "type": "string" }, "origin": { "type": "string" }, "path": { "type": "string" }, "save_as": { "$ref": "#/components/schemas/VaultDestination" } }, "required": [ "input_id", "label", "origin", "path" ] }, "NamespacePermission": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "namespace_id": { "type": "string", "minLength": 1 }, "member_id": { "type": "string", "format": "uuid", "nullable": true }, "grantee_agent_id": { "type": "string", "format": "uuid", "nullable": true }, "role": { "type": "string", "enum": [ "reader", "writer" ] }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "namespace_id", "member_id", "grantee_agent_id", "role", "expires_at", "created_at" ] }, "NamespacePermissionPage": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/NamespacePermission" } }, "next_cursor": { "type": "string", "nullable": true }, "has_more": { "type": "boolean" } }, "required": [ "items", "next_cursor", "has_more" ] }, "NativeEntry": { "type": "object", "description": "A committed Pi Durable EntryRecord, returned unchanged from its native store.", "additionalProperties": true }, "NativeRemoteMcpSettings": { "type": "object", "additionalProperties": false, "properties": { "required": { "type": "boolean" }, "headers": { "type": "object", "maxProperties": 32, "additionalProperties": { "type": "string", "maxLength": 8192 }, "description": "HTTP header values. Literal values pass through; Vault placeholders are resolved by the network gateway. OAuth state stays outside configuration." }, "tools": { "type": "object", "additionalProperties": false, "properties": { "default": { "$ref": "#/components/schemas/NativeRemoteMcpToolPolicy" }, "overrides": { "type": "object", "maxProperties": 256, "additionalProperties": { "$ref": "#/components/schemas/NativeRemoteMcpToolPolicy" } } } } } }, "NativeRemoteMcpToolPolicy": { "type": "object", "additionalProperties": false, "properties": { "enabled": { "type": "boolean" }, "require_approval": { "type": "boolean", "description": "Require exact-call approval for an autonomous Agent call." } } }, "NativeScope": { "type": "object", "additionalProperties": false, "properties": { "resources": { "type": "array", "items": { "$ref": "#/components/schemas/ScopeResource" } } }, "required": [ "resources" ] }, "NetworkRule": { "type": "object", "additionalProperties": false, "required": [ "id", "organization_id", "name", "definition", "scope", "scope_id", "scope_name", "can_edit", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "definition": { "$ref": "#/components/schemas/NetworkRuleDefinition" }, "scope": { "$ref": "#/components/schemas/NetworkRuleScope" }, "scope_id": { "type": "string", "format": "uuid" }, "scope_name": { "type": "string" }, "can_edit": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "NetworkRuleDefinition": { "description": "Gateway-enforced Computer network restrictions when the Organization Computer VPN is enabled. Computer command proxies and Computer HTTP MCP enforce the same selected policy before and after Vault substitution. Generic trusted Agent runtime HTTP, remote HTTP MCP without a Computer route, Workflows and builds are outside these rules. Values in a selector combine with OR; selectors combine with AND. Omitted selectors mean any. block_matches denies matches; block_except denies nonmatches and requires a selector. Any denial wins; approval cannot override it. Connection targets accept IPs, standalone CIDRs, IP endpoints, DNS hostnames and optional-port hostname endpoints. A leading *. matches subdomains but not the apex. Names are case-insensitive IDNA and lose one trailing dot. IPs are canonicalized and CIDR host bits masked. Duplicate canonical targets, zones, mapped IPv6 and port zero are invalid. Inbound ports are sandbox-local. DNS rejects names only when no protocol, port or address alternative can affect the connection decision; final endpoint and hostname checks run at connection establishment. Hostname policies inspect native TLS SNI and plaintext HTTP authority. Protocol selectors and explicit IP alternatives are evaluated first. When they cannot decide the rule, missing or numeric hostname evidence, ECH and opaque UDP/other protocols are denied. HTTP targets match scheme, host, effective port and canonical escaped path. Query and fragment are not selectors. An omitted path matches all paths; * matches one nonempty segment and a final ** matches the remaining path. Methods are case-sensitive HTTP tokens. HTTP rules inspect plain HTTP directly. HTTPS with method/path policy must use the existing command HTTP proxy; uninspected raw ciphertext and opaque protocols are denied. Native policy application confirms the current database revision before reporting success.", "oneOf": [ { "$ref": "#/components/schemas/OutboundConnectionRule" }, { "$ref": "#/components/schemas/InboundConnectionRule" }, { "$ref": "#/components/schemas/HTTPNetworkRule" } ] }, "NetworkRuleInput": { "type": "object", "additionalProperties": false, "required": [ "name", "definition", "scope", "scope_id" ], "properties": { "name": { "type": "string", "minLength": 1, "pattern": "\\S" }, "definition": { "$ref": "#/components/schemas/NetworkRuleDefinition" }, "scope": { "$ref": "#/components/schemas/NetworkRuleScope" }, "scope_id": { "type": "string", "format": "uuid" } } }, "NetworkRuleMode": { "type": "string", "enum": [ "block_matches", "block_except" ] }, "NetworkRulePage": { "type": "object", "additionalProperties": false, "required": [ "items", "next_cursor", "has_more" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkRule" } }, "next_cursor": { "type": "string", "nullable": true }, "has_more": { "type": "boolean" } } }, "NetworkRuleProtocols": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "enum": [ "tcp", "udp" ] } }, "NetworkRuleScope": { "type": "string", "enum": [ "organization", "user", "agent_template", "agent" ], "description": "The nearest owner with configured rules supplies the complete policy, in Agent then Agent Template then User then Organization order. User scope_id is an Organization User membership ID. The User is the selected Agent owner or otherwise the Computer owner. Mutation requires Organization update authority. Scope grants no execution authority." }, "NetworkRuleTargets": { "type": "array", "minItems": 1, "uniqueItems": true, "description": "IP addresses, standalone CIDRs, address-and-port endpoints, hostnames or *.subdomain suffixes with an optional port. Names use lowercase IDNA; wildcard does not match the apex. Addresses and prefixes are canonicalized; duplicates are rejected.", "items": { "type": "string", "minLength": 1 } }, "Organization": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "role": { "type": "string", "nullable": true, "enum": [ "primary_owner", "owner", "admin", "member" ] }, "agent_settings": { "$ref": "#/components/schemas/OrganizationAgentSettings" }, "deleting_at": { "type": "string", "format": "date-time", "nullable": true }, "deletion_id": { "type": "string", "format": "uuid", "nullable": true }, "members": { "type": "integer" }, "admins": { "type": "integer" }, "filesystem_ref": { "$ref": "#/components/schemas/FilesystemReference" }, "network_control_enabled": { "type": "boolean", "description": "Whether Computer workload traffic requires the protected WireGuard route and gateway enforcement of the selected Agent, Agent Template or Organization Network Rules. False preserves rule definitions. Authorized Vault substitution is available in both modes independently of tunnel enrollment. Vercel Computers do not support the protected WireGuard route." }, "private_network": { "$ref": "#/components/schemas/PrivateNetwork" }, "network_applied": { "type": "boolean", "readOnly": true, "description": "All affected native controls confirmed the saved network configuration. This records application, not current network health." } }, "required": [ "id", "name", "role", "agent_settings", "deleting_at", "deletion_id", "members", "admins", "filesystem_ref", "network_control_enabled" ] }, "OrganizationAgentSettings": { "type": "object", "properties": { "model": { "type": "string", "pattern": "^[^/\\s]+\\/\\S+$" }, "reasoning_effort": { "type": "string", "enum": [ "off", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "priority": { "type": "boolean" } }, "additionalProperties": false }, "OrganizationCreated": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "role": { "type": "string", "enum": [ "primary_owner", "owner", "admin", "member" ] } }, "required": [ "id", "name", "role" ] }, "OrganizationIdentity": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "filesystem_ref": { "$ref": "#/components/schemas/FilesystemReference" } }, "required": [ "id", "name", "filesystem_ref" ] }, "OrganizationListItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "role": { "type": "string", "enum": [ "primary_owner", "owner", "admin", "member" ] }, "deleting_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "role", "deleting_at", "created_at" ] }, "OrganizationListItemPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationListItem" } }, "next_cursor": { "type": "string", "nullable": true }, "has_more": { "type": "boolean" } }, "required": [ "items", "next_cursor", "has_more" ] }, "OutboundConnectionRule": { "type": "object", "additionalProperties": false, "required": [ "kind", "direction", "mode" ], "properties": { "kind": { "type": "string", "enum": [ "connection" ] }, "direction": { "type": "string", "enum": [ "outbound" ] }, "mode": { "$ref": "#/components/schemas/NetworkRuleMode" }, "protocols": { "$ref": "#/components/schemas/NetworkRuleProtocols" }, "targets": { "$ref": "#/components/schemas/NetworkRuleTargets" } } }, "PermissionSubject": { "type": "object", "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "member", "organization" ] }, "id": { "type": "string", "nullable": true, "description": "Membership UUID. Organization subjects use null." }, "name": { "type": "string" }, "email": { "type": "string", "nullable": true }, "profile_image_url": { "type": "string", "nullable": true } }, "required": [ "type", "id", "name", "email", "profile_image_url" ] }, "PrivateNetwork": { "type": "object", "nullable": true, "additionalProperties": false, "required": [ "auth_key", "exit_node" ], "description": "One Organization private-network attachment. The trusted gateway enrolls with a reusable, preauthorized Tailscale auth key from an Organization-owned Vault secret and selects the explicit, administratively approved exit node. Null removes the attachment and cancels its private connections. Reachability does not grant resource, MCP, Vault or Network Rule authority.", "properties": { "auth_key": { "type": "string", "minLength": 53, "pattern": "^completion-vault:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Vault reference. The API never returns the enrollment value." }, "auth_key_name": { "type": "string", "readOnly": true, "description": "Name of the selected Organization Vault entry." }, "exit_node": { "type": "string", "anyOf": [ { "format": "ipv4" }, { "format": "ipv6" } ], "description": "Canonical Tailscale IP of an existing approved exit node. Enrollment alone does not select or approve an exit. Native setup verifies this exact node and its protected route." } } }, "ProgramReference": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1 }, "path": { "type": "string" } }, "required": [ "id" ] }, "RegisterAPIKey": { "type": "object", "additionalProperties": false, "description": "Register a client-generated key hash and an explicit resource/operation scope. Human user ownership only; identity, secret hash and expiry are immutable.", "properties": { "id": { "type": "string", "format": "uuid" }, "secret_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "native_scope": { "$ref": "#/components/schemas/NativeScope" }, "expires_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "secret_hash", "native_scope" ] }, "RegisterVaultSecret": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "value", "scope_ref", "consumer_constraints" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "value": { "type": "string", "maxLength": 65536, "writeOnly": true }, "scope_ref": { "$ref": "#/components/schemas/VaultScopeRef" }, "consumer_constraints": { "$ref": "#/components/schemas/VaultConsumerConstraints" }, "http_targets": { "$ref": "#/components/schemas/VaultHTTPDestinations" } } }, "RemoteMcpToolCallInput": { "type": "object", "additionalProperties": false, "required": [ "connection", "name", "arguments" ], "properties": { "connection": { "type": "string", "minLength": 1, "maxLength": 8192 }, "name": { "type": "string", "minLength": 1, "maxLength": 256 }, "arguments": { "type": "object", "additionalProperties": true } } }, "RemoteMcpToolPage": { "type": "object", "additionalProperties": false, "required": [ "items", "has_more" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/McpConnectionState" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string" } } }, "ResourceOwner": { "type": "object", "additionalProperties": false, "properties": { "member_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" }, "profile_image_url": { "type": "string", "nullable": true } }, "required": [ "member_id", "name", "email", "profile_image_url" ] }, "ResourcePermission": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "resource_id": { "type": "string", "format": "uuid" }, "subject": { "$ref": "#/components/schemas/PermissionSubject" }, "role": { "type": "string", "enum": [ "viewer", "writer" ] }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "organization_id", "resource_id", "subject", "role", "expires_at", "created_at", "updated_at" ] }, "ResourcePermissionPage": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ResourcePermission" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true }, "owner": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/ResourceOwner" } ] }, "automatic_access": { "type": "string" } }, "required": [ "items", "has_more", "next_cursor", "owner", "automatic_access" ] }, "SSHKey": { "type": "object", "properties": { "api_key_id": { "type": "string", "format": "uuid", "nullable": true, "readOnly": true, "description": "The API credential this key authenticates. Null identifies a User key." }, "id": { "type": "string", "format": "uuid" }, "public_key": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "api_key_id", "id", "public_key", "created_at" ] }, "SSHKeyInput": { "type": "object", "properties": { "public_key": { "type": "string", "minLength": 1, "maxLength": 16384 } }, "required": [ "public_key" ], "additionalProperties": false }, "SSHKeyPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SSHKey" } }, "next_cursor": { "type": "string", "nullable": true }, "has_more": { "type": "boolean" } }, "required": [ "items", "next_cursor", "has_more" ] }, "SaveAgentTemplateSnapshotInput": { "type": "object", "additionalProperties": false, "properties": { "request_id": { "type": "string", "format": "uuid" }, "source_agent_id": { "type": "string", "format": "uuid" } }, "required": [ "request_id" ] }, "SaveBrowserTemplateSnapshotInput": { "type": "object", "additionalProperties": false, "properties": { "request_id": { "type": "string", "format": "uuid" }, "source_browser_id": { "type": "string", "format": "uuid" } }, "required": [ "request_id", "source_browser_id" ] }, "SaveComputerTemplateSnapshotInput": { "description": "Capture and publish source state using memory when the provider supports it, otherwise a disk snapshot. The capture mode is not a caller option.", "type": "object", "additionalProperties": false, "properties": { "request_id": { "type": "string", "format": "uuid" }, "computer_id": { "type": "string", "format": "uuid" } }, "required": [ "request_id", "computer_id" ] }, "ScopeResource": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "description": "Native resource identity. For filesystem operations on managed resources, use the canonical root /namespaces/{namespace_id}, /agents/{agent_id}, or /agent-templates/{template_id}; ordinary shared files use their filesystem node ID. Non-filesystem operations use the canonical lowercase hyphenated resource UUID, such as the Agent UUID for agent.share, the Computer UUID for computer.read/use/update/share/delete, or the Computer Template UUID for computer_template.use/update/share/delete. Delegation requires the issuer's credential ceiling and current resource authority; updates to another member's key also require that member's current authority." }, "operations": { "type": "array", "items": { "type": "string" }, "minItems": 1, "uniqueItems": true } }, "required": [ "id", "operations" ] }, "SetResourcePermissionInput": { "type": "object", "additionalProperties": false, "required": [ "role" ], "properties": { "role": { "type": "string", "enum": [ "viewer", "writer" ] }, "expires_at": { "type": "string", "format": "date-time", "nullable": true } } }, "SignInStep": { "type": "object", "additionalProperties": false, "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "redirect", "code", "verify_email", "authenticated" ] }, "user_id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri", "description": "Completion authorization URL for a redirect step." } } }, "StartSignInInput": { "type": "object", "additionalProperties": false, "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 254 }, "sso": { "type": "boolean", "description": "Require an existing company SSO connection for this email domain." } } }, "TransferOrganizationOwnershipInput": { "type": "object", "additionalProperties": false, "properties": { "member_id": { "type": "string", "format": "uuid" } }, "required": [ "member_id" ] }, "UpdateAPIKeyInput": { "type": "object", "additionalProperties": false, "required": [ "native_scope" ], "properties": { "native_scope": { "allOf": [ { "$ref": "#/components/schemas/NativeScope" } ], "description": "Replace the complete resource/operation allowlist. Empty resources grants no operations. Requires key-management authority and cannot grant authority the caller lacks or let a scoped key expand its own permissions. The key ID, secret hash, owner and expiry are unchanged. New requests use this scope; accepted turns retain admitted authority." } } }, "UpdateAgentInput": { "type": "object", "additionalProperties": false, "properties": { "title": { "type": "string", "nullable": true }, "archived": { "type": "boolean" }, "namespace_id": { "type": "string", "minLength": 1 }, "computer_id": { "type": "string", "format": "uuid", "nullable": true }, "browser_id": { "type": "string", "format": "uuid", "nullable": true } }, "minProperties": 1 }, "UpdateAgentPermissionInput": { "type": "object", "additionalProperties": false, "description": "Set supplied role or expiry. Omission retains the value; null expiry clears it. Subject is immutable.", "properties": { "role": { "type": "string", "enum": [ "viewer", "writer" ] }, "expires_at": { "type": "string", "format": "date-time", "nullable": true } }, "minProperties": 1 }, "UpdateAgentTemplateInput": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1 }, "computer_template_id": { "type": "string", "format": "uuid", "nullable": true }, "browser_template_id": { "type": "string", "format": "uuid", "nullable": true } }, "minProperties": 1 }, "UpdateBrowserInput": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1 }, "start_url": { "type": "string", "nullable": true } }, "minProperties": 1 }, "UpdateBrowserTemplateInput": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1 }, "start_url": { "type": "string", "nullable": true } }, "minProperties": 1 }, "UpdateComputerInput": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1 } }, "minProperties": 1 }, "UpdateComputerTemplateInput": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1 } }, "minProperties": 1 }, "UpdateFilesystemPermissionInput": { "type": "object", "additionalProperties": false, "properties": { "role": { "type": "string", "enum": [ "reader", "writer" ] }, "expires_at": { "type": "string", "format": "date-time", "nullable": true } }, "minProperties": 1 }, "UpdateNamespacePermissionInput": { "type": "object", "additionalProperties": false, "description": "Set supplied role or expiry. Omission retains the value; null expiry clears it. Subject is immutable.", "properties": { "role": { "type": "string", "enum": [ "reader", "writer" ] }, "expires_at": { "type": "string", "format": "date-time", "nullable": true } }, "minProperties": 1 }, "UpdateNetworkRuleInput": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "pattern": "\\S" }, "definition": { "$ref": "#/components/schemas/NetworkRuleDefinition" }, "scope": { "$ref": "#/components/schemas/NetworkRuleScope" }, "scope_id": { "type": "string", "format": "uuid" } }, "minProperties": 1, "description": "Set only the supplied top-level writable fields to their absolute values. Omitted fields retain their saved values. Supplied arrays and objects replace that field's value; this is not a recursive merge or JSON Patch operation. Explicit null is valid only where the field schema permits it. Validate the resulting effective resource, including coupled scope and policy fields, before committing. Repeating the same update has the same resource-state effect; never interpret values as increment, toggle or append commands." }, "UpdateOrganizationInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "network_control_enabled": { "type": "boolean", "description": "Route Computer workload traffic through the protected WireGuard gateway and enforce the selected scoped Network Rules when true. False uses ordinary networking and retains rule definitions without enforcing them. Supported HTTP tools and command proxies resolve authorized Vault references in both modes; false does not intercept arbitrary application connections. Vercel uses its native firewall independently; enabling the protected VPN for Vercel returns unsupported rather than broadening its policy." }, "private_network": { "allOf": [ { "$ref": "#/components/schemas/PrivateNetwork" } ], "nullable": true, "description": "Omit to preserve the attachment. Supply the complete reference and approved exit to replace it, or null to detach. The current native Vault version is pinned when this update is admitted." } }, "minProperties": 1, "additionalProperties": false }, "UpdateResourceOwnerInput": { "type": "object", "additionalProperties": false, "properties": { "owner_member_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Current organization membership to own the resource. Null clears ownership." } }, "required": [ "owner_member_id" ], "description": "Set the owner to an explicit same-organization membership, or clear it. Does not change creation provenance or sharing grants." }, "User": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string" }, "profile_image_url": { "type": "string", "nullable": true }, "name": { "type": "string" } }, "required": [ "id", "email", "profile_image_url", "name" ] }, "VaultConsumerConstraints": { "type": "object", "additionalProperties": false, "required": [ "consumer" ], "properties": { "consumer": { "type": "string", "enum": [ "computer_provider", "http", "tailscale_enrollment", "desktop", "browser", "mcp_oauth" ], "description": "mcp_oauth marks a remote MCP OAuth grant that Completion saves for an Agent connection; it cannot be created, renamed or given a value through this API, only revoked." }, "destination": { "type": "string", "description": "Immutable consumer destination. For browser, the exact HTTPS top-level page URL with no embedded user information, including its path, query and fragment. For provider or enrollment credentials, the exact HTTPS destination. For desktop, the exact native application launch path. Omit for HTTP substitution." } } }, "VaultDestination": { "type": "object", "additionalProperties": false, "required": [ "name", "scope" ], "properties": { "name": { "type": "string", "minLength": 1 }, "scope": { "type": "string", "enum": [ "user", "agent", "agent_template", "organization" ] }, "scope_id": { "type": "string", "format": "uuid" } } }, "VaultHTTPDestinations": { "type": "array", "items": { "type": "string" }, "description": "Replace the complete HTTPS target policy. Empty disables HTTP substitution. No plaintext value is returned." }, "VaultInputSave": { "type": "object", "additionalProperties": false, "required": [ "name", "scope" ], "properties": { "name": { "type": "string", "minLength": 1 }, "scope": { "type": "string", "enum": [ "user", "agent", "agent_template", "organization" ] }, "scope_id": { "type": "string", "format": "uuid" }, "replace_ref": { "type": "string", "pattern": "^completion-vault:[0-9a-fA-F-]{36}$" } } }, "VaultScope": { "type": "string", "enum": [ "organization", "user", "agent_template", "agent" ] }, "VaultScopeRef": { "type": "object", "additionalProperties": false, "minProperties": 1, "maxProperties": 1, "description": "Exactly one immutable scope owner. organization_user_id is the current Organization membership UUID. Scope selection grants no authority.", "properties": { "organization_id": { "type": "string", "format": "uuid" }, "organization_user_id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string", "format": "uuid" }, "agent_template_id": { "type": "string", "format": "uuid" } } }, "VaultSecret": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "scope_ref", "consumer_constraints", "http_targets", "version_id", "created_at", "updated_at", "revoked_at", "can_manage", "can_use" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "scope_ref": { "$ref": "#/components/schemas/VaultScopeRef" }, "consumer_constraints": { "$ref": "#/components/schemas/VaultConsumerConstraints" }, "http_targets": { "$ref": "#/components/schemas/VaultHTTPDestinations" }, "version_id": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "revoked_at": { "type": "string", "format": "date-time", "nullable": true }, "can_manage": { "type": "boolean" }, "can_use": { "type": "boolean" } } }, "VaultSecretInput": { "type": "object", "additionalProperties": false, "minProperties": 1, "description": "Set supplied name, write-only value or HTTP targets. Omitted fields retain their values. Scope and native consumer/destination are immutable. Rotation preserves existing bound versions.", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "value": { "type": "string", "maxLength": 65536, "writeOnly": true }, "http_targets": { "$ref": "#/components/schemas/VaultHTTPDestinations" } } }, "VaultSecretPage": { "type": "object", "additionalProperties": false, "required": [ "items", "next_cursor", "has_more" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/VaultSecret" } }, "next_cursor": { "type": "string", "nullable": true }, "has_more": { "type": "boolean" } } }, "VaultSecretReference": { "$ref": "#/components/schemas/ComputerCredentialReference" }, "VerifyCodeInput": { "type": "object", "additionalProperties": false, "required": [ "email", "code" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 254 }, "code": { "type": "string", "minLength": 6, "maxLength": 6, "writeOnly": true, "description": "Six decimal digits from the delivered email. Never log this value." } } }, "VoiceSettings": { "type": "object", "additionalProperties": false, "properties": { "model": { "type": "string", "minLength": 1 }, "voice": { "type": "string", "minLength": 1 }, "instructions": { "type": "string" } }, "required": [ "model", "voice", "instructions" ] } }, "responses": { "Error": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }