{ "openapi": "3.1.1", "info": { "title": "Deck API", "version": "2.0.0", "description": "Deck REST API for computer use agents, connections, tasks, credentials, sessions, storage, and events.\n\n## Base URL and versioning\n\nAll requests use URL path versioning:\n\n- Current: `https://api.deck.co/v2`\n- Previous: `https://api.deck.co/v1` (see the v1 migration guide)\n\nNew teams start on the latest stable version. Deck only cuts a new major/minor version for breaking changes (removed fields, changed types, auth or error-format changes, removed endpoints). Additive changes (optional fields, new endpoints, new event types) roll out to all supported versions without a version bump.\n\n## Deprecation policy\n\nDeprecated operations and parameters are marked with OpenAPI `deprecated: true`. Deck announces breaking changes in the changelog with migration notes before removal. Clients should treat `endpoint_deprecated` error codes as a signal to migrate. Sunset timing is published in https://docs.deck.co/api/api-status-and-changes and https://deck.co/changelog.\n\n## Errors\n\nEvery error is JSON (`application/json`) with this typed object:\n\n```\n{ \"errors\": [{ \"type\": \"\", \"code\": \"\", \"message\": \"\", \"field\": \"\" }], \"request_id\": \"req_...\" }\n```\n\nUse `type` + `code` for control flow. See https://docs.deck.co/api/errors and https://deck.co/errors.json.\n\n## Rate limits\n\nDefault: 200 requests per 10 seconds per organization. HTTP 429 uses the same error object (`type: rate_limit`, `code: rate_limit_exceeded` or `session_limit_exceeded`). Honor `Retry-After` and IETF RateLimit headers (`RateLimit`, `RateLimit-Policy`) when present.\n\n## Auth\n\n`Authorization: Bearer ` on every request. Keys come from https://console.deck.co.", "contact": { "name": "Deck", "url": "https://deck.co", "email": "hello@deck.co" }, "license": { "name": "Proprietary" } }, "servers": [ { "url": "https://api.deck.co/v2", "description": "Production" }, { "url": "https://api.deck.co/v1", "description": "Previous major version. Deprecated for new integrations; see migrating from v1." } ], "paths": { "/agents": { "post": { "tags": [ "Agents" ], "summary": "Create an agent", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/CreateAgentRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CreateAgentRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/CreateAgentResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/CreateAgentResponse" } } } }, "400": { "description": "Bad request \u2014 validation error or malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found \u2014 the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 the request is valid but cannot be completed in the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content \u2014 the request body is understood but contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "createAgent", "description": "Creates a new agent. An agent is an automation scoped to a use case that organizes related tasks." }, "get": { "tags": [ "Agents" ], "summary": "List agents", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of items to return (1-100, default 20)", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Cursor from a previous response for pagination." } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/PaginatedResponseOfListAgentData" } }, "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponseOfListAgentData" } }, "text/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponseOfListAgentData" } } } }, "400": { "description": "Bad request \u2014 validation error or malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found \u2014 the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 the request is valid but cannot be completed in the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content \u2014 the request body is understood but contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "listAgents", "description": "Returns a paginated list of agents in your organization." } }, "/agents/{agent_id}": { "get": { "tags": [ "Agents" ], "summary": "Retrieve an agent", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the agent (prefixed with `agt_`)." } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/GetAgentResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/GetAgentResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/GetAgentResponse" } } } }, "400": { "description": "Bad request \u2014 validation error or malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found \u2014 the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 the request is valid but cannot be completed in the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content \u2014 the request body is understood but contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "getAgent", "description": "Returns the full agent object including its associated tasks." }, "patch": { "tags": [ "Agents" ], "summary": "Update an agent", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the agent (prefixed with `agt_`)." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAgentRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/UpdateAgentRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/UpdateAgentRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/GetAgentResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/GetAgentResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/GetAgentResponse" } } } }, "400": { "description": "Bad request \u2014 validation error or malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found \u2014 the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 the request is valid but cannot be completed in the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content \u2014 the request body is understood but contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "updateAgent", "description": "Updates an agent's name or description. Only the fields you include in the request body are updated." }, "delete": { "tags": [ "Agents" ], "summary": "Delete an agent", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the agent (prefixed with `agt_`)." } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/DeleteAgentResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/DeleteAgentResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/DeleteAgentResponse" } } } }, "400": { "description": "Bad request \u2014 validation error or malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found \u2014 the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 the request is valid but cannot be completed in the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content \u2014 the request body is understood but contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "deleteAgent", "description": "Permanently deletes an agent." } }, "/credentials": { "post": { "tags": [ "Credentials" ], "summary": "Create a credential", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCredentialRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/CreateCredentialRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CreateCredentialRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/CreateCredentialResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/CreateCredentialResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/CreateCredentialResponse" } } } }, "400": { "description": "Bad request \u2014 validation error or malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found \u2014 the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 the request is valid but cannot be completed in the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content \u2014 the request body is understood but contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "createCredential", "description": "Stores a new credential for authenticating with an external source. The credential is created immediately and can be used on task runs." }, "get": { "tags": [ "Credentials" ], "summary": "List credentials", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of items to return (1-100, default 20)", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Cursor from a previous response for pagination." }, { "name": "source_id", "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "description": "Unique identifier for the source (prefixed with `src_`)." }, { "name": "status", "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "description": "Filter by credential status: unverified, verified, invalid, deleted." }, { "name": "external_id", "in": "query", "schema": { "type": "string" }, "description": "Filter by the external ID assigned when creating the credential." } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/PaginatedResponseOfListCredentialData" } }, "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponseOfListCredentialData" } }, "text/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponseOfListCredentialData" } } } }, "400": { "description": "Bad request \u2014 validation error or malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found \u2014 the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 the request is valid but cannot be completed in the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content \u2014 the request body is understood but contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "listCredentials", "description": "Returns a paginated list of credentials. Supports filtering by source, status, and external ID." } }, "/credentials/{credential_id}": { "get": { "tags": [ "Credentials" ], "summary": "Retrieve a credential", "parameters": [ { "name": "credential_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the credential (prefixed with `cred_`)." } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/GetCredentialResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/GetCredentialResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/GetCredentialResponse" } } } }, "400": { "description": "Bad request \u2014 validation error or malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found \u2014 the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 the request is valid but cannot be completed in the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content \u2014 the request body is understood but contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "getCredential", "description": "Returns a single credential by ID." }, "patch": { "tags": [ "Credentials" ], "summary": "Update a credential", "parameters": [ { "name": "credential_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the credential (prefixed with `cred_`)." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCredentialRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/UpdateCredentialRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/UpdateCredentialRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/UpdateCredentialResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCredentialResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/UpdateCredentialResponse" } } } }, "400": { "description": "Bad request \u2014 validation error or malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found \u2014 the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 the request is valid but cannot be completed in the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content \u2014 the request body is understood but contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "updateCredential", "description": "Updates a credential's authentication details or external ID. Only the fields you include in the request body are updated." }, "delete": { "tags": [ "Credentials" ], "summary": "Delete a credential", "parameters": [ { "name": "credential_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the credential (prefixed with `cred_`)." } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/DeleteCredentialResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/DeleteCredentialResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/DeleteCredentialResponse" } } } }, "400": { "description": "Bad request \u2014 validation error or malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found \u2014 the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 the request is valid but cannot be completed in the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content \u2014 the request body is understood but contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "deleteCredential", "description": "Permanently deletes a credential." } }, "/event-destinations": { "post": { "tags": [ "Event Destinations" ], "summary": "Create an event destination", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEventDestinationRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/CreateEventDestinationRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CreateEventDestinationRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/EventDestinationResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/EventDestinationResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/EventDestinationResponse" } } } }, "400": { "description": "Bad request \u2014 validation error or malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found \u2014 the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 the request is valid but cannot be completed in the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content \u2014 the request body is understood but contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "createEventDestination", "description": "Creates a new event destination (e.g. a webhook endpoint) to receive platform events." }, "get": { "tags": [ "Event Destinations" ], "summary": "List event destinations", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of items to return (1-100, default 20)", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Cursor from a previous response for pagination." } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/PaginatedResponseOfEventDestinationResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponseOfEventDestinationResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponseOfEventDestinationResponse" } } } }, "400": { "description": "Bad request \u2014 validation error or malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found \u2014 the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 the request is valid but cannot be completed in the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content \u2014 the request body is understood but contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "listEventDestinations", "description": "Returns a paginated list of event destinations." } }, "/event-destinations/{destination_id}": { "get": { "tags": [ "Event Destinations" ], "summary": "Retrieve an event destination", "parameters": [ { "name": "destination_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the event destination (prefixed with `evtd_`)." } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/EventDestinationResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/EventDestinationResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/EventDestinationResponse" } } } }, "400": { "description": "Bad request \u2014 validation error or malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found \u2014 the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 the request is valid but cannot be completed in the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content \u2014 the request body is understood but contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "getEventDestination", "description": "Returns a single event destination by ID." }, "patch": { "tags": [ "Event Destinations" ], "summary": "Update an event destination", "parameters": [ { "name": "destination_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the event destination (prefixed with `evtd_`)." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEventDestinationRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/UpdateEventDestinationRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/UpdateEventDestinationRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/EventDestinationResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/EventDestinationResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/EventDestinationResponse" } } } }, "400": { "description": "Bad request \u2014 validation error or malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found \u2014 the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 the request is valid but cannot be completed in the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content \u2014 the request body is understood but contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "updateEventDestination", "description": "Updates an event destination's name, status, or subscribed events. Only the fields you include in the request body are updated." }, "delete": { "tags": [ "Event Destinations" ], "summary": "Delete an event destination", "parameters": [ { "name": "destination_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the event destination (prefixed with `evtd_`)." } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/DeleteEventDestinationResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/DeleteEventDestinationResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/DeleteEventDestinationResponse" } } } }, "400": { "description": "Bad request \u2014 validation error or malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found \u2014 the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 the request is valid but cannot be completed in the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content \u2014 the request body is understood but contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "deleteEventDestination", "description": "Permanently deletes an event destination." } }, "/event-destinations/{destination_id}/event-deliveries": { "get": { "tags": [ "Event Destinations" ], "summary": "List event deliveries", "parameters": [ { "name": "destination_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the event destination (prefixed with `evtd_`)." }, { "name": "limit", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32", "default": 20 }, "description": "Maximum number of items to return (1-100, default 20)." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Cursor from a previous response for pagination." }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Filter by delivery status: success, failure." }, { "name": "type", "in": "query", "schema": { "type": "string" }, "description": "Filter by event type." } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/PaginatedResponseOfEventDeliveryResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponseOfEventDeliveryResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponseOfEventDeliveryResponse" } } } }, "400": { "description": "Bad request \u2014 validation error or malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found \u2014 the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 the request is valid but cannot be completed in the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content \u2014 the request body is understood but contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "listEventDeliveries", "description": "Returns a paginated list of event deliveries for a destination. Supports filtering by delivery status." } }, "/event-types": { "get": { "tags": [ "Events" ], "summary": "List event types", "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ListEventTypesResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ListEventTypesResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ListEventTypesResponse" } } } }, "400": { "description": "Bad request \u2014 validation error or malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found \u2014 the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 the request is valid but cannot be completed in the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content \u2014 the request body is understood but contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "listEventTypes", "description": "Returns a list of all available event types you can subscribe to." } }, "/events": { "get": { "tags": [ "Events" ], "summary": "List events", "parameters": [ { "name": "type", "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "description": "Filter by event type (e.g. `task_run.completed`, `credential.verified`)." }, { "name": "created_after", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Return events created after this timestamp (ISO 8601)." }, { "name": "created_before", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Return events created before this timestamp (ISO 8601)." }, { "name": "limit", "in": "query", "description": "Maximum number of items to return (1-100, default 20)", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Cursor from a previous response for pagination." } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/PaginatedResponseOfListEventData" } }, "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponseOfListEventData" } }, "text/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponseOfListEventData" } } } }, "400": { "description": "Bad request \u2014 validation error or malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found \u2014 the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 the request is valid but cannot be completed in the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content \u2014 the request body is understood but contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "listEvents", "description": "Returns a paginated list of events. Supports filtering by event type." } }, "/events/{event_id}": { "get": { "tags": [ "Events" ], "summary": "Retrieve an event", "parameters": [ { "name": "event_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the event (prefixed with `evt_`)." } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/EventResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/EventResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/EventResponse" } } } }, "400": { "description": "Bad request \u2014 validation error or malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found \u2014 the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 the request is valid but cannot be completed in the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content \u2014 the request body is understood but contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "getEvent", "description": "Returns a single event by ID, including its full data payload." } }, "/sessions": { "post": { "tags": [ "Sessions" ], "summary": "Start a session", "responses": { "201": { "description": "Created", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/CreateSessionResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/CreateSessionResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/CreateSessionResponse" } } } }, "400": { "description": "Bad request \u2014 validation error or malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found \u2014 the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 the request is valid but cannot be completed in the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content \u2014 the request body is understood but contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "startSession", "description": "Starts a new isolated compute session for executing tasks." }, "get": { "tags": [ "Sessions" ], "summary": "List sessions", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of items to return (1-100, default 20)", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Cursor from a previous response for pagination." } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/PaginatedResponseOfListSessionData" } }, "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponseOfListSessionData" } }, "text/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponseOfListSessionData" } } } }, "400": { "description": "Bad request \u2014 validation error or malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found \u2014 the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 the request is valid but cannot be completed in the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content \u2014 the request body is understood but contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "listSessions", "description": "Returns a paginated list of sessions." } }, "/sessions/{session_id}": { "get": { "tags": [ "Sessions" ], "summary": "Retrieve a session", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the session (prefixed with `sess_`)." } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/GetSessionResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/GetSessionResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/GetSessionResponse" } } } }, "400": { "description": "Bad request \u2014 validation error or malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found \u2014 the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 the request is valid but cannot be completed in the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content \u2014 the request body is understood but contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "getSession", "description": "Returns a single session by ID, including the task runs executed within it." } }, "/sessions/{session_id}/end": { "post": { "tags": [ "Sessions" ], "summary": "End a session", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the session (prefixed with `sess_`)." } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/GetSessionResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/GetSessionResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/GetSessionResponse" } } } }, "400": { "description": "Bad request \u2014 validation error or malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found \u2014 the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 the request is valid but cannot be completed in the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content \u2014 the request body is understood but contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "endSession", "description": "Ends an active session." } }, "/sources": { "post": { "tags": [ "Sources" ], "summary": "Create a source", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSourceRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/CreateSourceRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CreateSourceRequest" } } }, "required": true }, "responses": { "201": { "description": "The source was created.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/CreateSourceResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/CreateSourceResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/CreateSourceResponse" } } } }, "200": { "description": "An existing source with the same URL was returned. Sources are deduplicated by their normalized URL, so creating a source that already exists returns the existing source with `200` instead of `201`.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/CreateSourceResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/CreateSourceResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/CreateSourceResponse" } } } }, "400": { "description": "Bad request \u2014 validation error or malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found \u2014 the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 the request is valid but cannot be completed in the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content \u2014 the request body is understood but contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "createSource", "description": "Registers a new source. A source is a website or service that your agents connect to." }, "get": { "tags": [ "Sources" ], "summary": "List sources", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of items to return (1-100, default 20)", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Cursor from a previous response for pagination." }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Case-insensitive substring match against a source's name and website URL." } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/PaginatedResponseOfListSourceResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponseOfListSourceResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponseOfListSourceResponse" } } } }, "400": { "description": "Bad request \u2014 validation error or malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found \u2014 the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 the request is valid but cannot be completed in the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content \u2014 the request body is understood but contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "listSources", "description": "Returns a paginated list of sources in your organization." } }, "/sources/{source_id}": { "get": { "tags": [ "Sources" ], "summary": "Retrieve a source", "parameters": [ { "name": "source_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the source (prefixed with `src_`)." } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/GetSourceResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/GetSourceResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/GetSourceResponse" } } } }, "400": { "description": "Bad request \u2014 validation error or malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found \u2014 the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 the request is valid but cannot be completed in the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content \u2014 the request body is understood but contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "getSource", "description": "Returns a single source by ID." }, "patch": { "tags": [ "Sources" ], "summary": "Update a source", "parameters": [ { "name": "source_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the source (prefixed with `src_`)." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSourceRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/UpdateSourceRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/UpdateSourceRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/UpdateSourceResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSourceResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/UpdateSourceResponse" } } } }, "400": { "description": "Bad request \u2014 validation error or malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found \u2014 the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 the request is valid but cannot be completed in the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content \u2014 the request body is understood but contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "updateSource", "description": "Updates a source's name or URL. Only the fields you include in the request body are updated." }, "delete": { "tags": [ "Sources" ], "summary": "Delete a source", "parameters": [ { "name": "source_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the source (prefixed with `src_`)." } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/DeleteSourceResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/DeleteSourceResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/DeleteSourceResponse" } } } }, "400": { "description": "Bad request \u2014 validation error or malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found \u2014 the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 the request is valid but cannot be completed in the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content \u2014 the request body is understood but contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "deleteSource", "description": "Permanently deletes a source." } }, "/sources/{source_id}/reset": { "post": { "tags": [ "Sources" ], "summary": "Reset a source", "parameters": [ { "name": "source_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the source (prefixed with `src_`)." } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ResetSourceResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ResetSourceResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ResetSourceResponse" } } } }, "400": { "description": "Bad request \u2014 validation error or malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found \u2014 the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 the request is valid but cannot be completed in the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content \u2014 the request body is understood but contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "resetSource", "description": "Re-runs Deck's antibot analysis for the source. Runs keep using the existing analysis until the new one completes. Resetting again shortly after a previous reset has no effect and returns the current source; `reset_at` shows when the last reset took effect." } }, "/storage/{storage_id}": { "get": { "tags": [ "Storage" ], "summary": "Retrieve a storage item", "parameters": [ { "name": "storage_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the storage item (prefixed with `stor_`)." } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/GetStorageItemResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/GetStorageItemResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/GetStorageItemResponse" } } } }, "400": { "description": "Bad request \u2014 validation error or malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found \u2014 the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 the request is valid but cannot be completed in the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content \u2014 the request body is understood but contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "getStorageItem", "description": "Returns a single storage item by ID, including a signed download URL for the file." } }, "/task-runs/{run_id}": { "get": { "tags": [ "Task Runs" ], "summary": "Retrieve a task run", "parameters": [ { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the task run (prefixed with `trun_`)." }, { "name": "include", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated list of additional fields to include in the response. Supported values: `input`, `storage`, `storage_deduplicated`, `artifacts`. Sections are omitted from the response (not returned as null) when their flag is not present." } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/GetTaskRunResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/GetTaskRunResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/GetTaskRunResponse" } } } }, "400": { "description": "Bad request \u2014 validation error or malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found \u2014 the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 the request is valid but cannot be completed in the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content \u2014 the request body is understood but contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "getTaskRun", "description": "Returns a single task run by ID, including its status, input, output, errors, and interaction state." } }, "/task-runs": { "get": { "tags": [ "Task Runs" ], "summary": "List task runs", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of items to return (1-100, default 20)", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Cursor from a previous response for pagination." }, { "name": "status", "in": "query", "description": "Filter by status: queued, running, canceling, interaction_required, review_required, completed, canceled, failed", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "source_id", "in": "query", "description": "Filter by source ID", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "outcome", "in": "query", "description": "Filter by run result: success, failure, unknown. Maps to the `result` field on the task run object.", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "agent_id", "in": "query", "schema": { "type": "string" }, "description": "Unique identifier for the agent (prefixed with `agt_`)." }, { "name": "credential_id", "in": "query", "schema": { "type": "string" }, "description": "Unique identifier for the credential (prefixed with `cred_`)." }, { "name": "task_id", "in": "query", "schema": { "type": "string" }, "description": "Unique identifier for the task (prefixed with `task_`)." }, { "name": "workflow_id", "in": "query", "schema": { "type": "string" }, "description": "Filter by workflow ID." }, { "name": "trigger_id", "in": "query", "schema": { "type": "string" }, "description": "Filter to runs created by this trigger. Prefixed with `trg_`." }, { "name": "created_after", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Return runs created after this timestamp (ISO 8601)." }, { "name": "created_before", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Return runs created before this timestamp (ISO 8601)." }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Free-text search matching task name, task ID, or task run ID." } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/PaginatedResponseOfListTaskRunData" } }, "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponseOfListTaskRunData" } }, "text/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponseOfListTaskRunData" } } } }, "400": { "description": "Bad request \u2014 validation error or malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found \u2014 the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 the request is valid but cannot be completed in the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content \u2014 the request body is understood but contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "listTaskRuns", "description": "Returns a paginated list of task runs. Supports filtering by agent, credential, source, task, workflow, status, result, and date range." } }, "/task-runs/{run_id}/storage": { "get": { "tags": [ "Task Runs" ], "summary": "List task run storage items", "parameters": [ { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the task run (prefixed with `trun_`)." } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/PaginatedResponseOfListStorageItemResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponseOfListStorageItemResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponseOfListStorageItemResponse" } } } }, "400": { "description": "Bad request \u2014 validation error or malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found \u2014 the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 the request is valid but cannot be completed in the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content \u2014 the request body is understood but contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "listTaskRunStorage", "description": "Returns all storage items (files) produced by a task run in a single response." } }, "/task-runs/{run_id}/screenshots": { "get": { "tags": [ "Task Runs" ], "summary": "List task run screenshots", "parameters": [ { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the task run (prefixed with `trun_`)." }, { "name": "limit", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32", "default": 20 }, "description": "Maximum number of items to return (1-100, default 20)." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Cursor from a previous response for pagination." } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/PaginatedResponseOfListScreenshotItemResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponseOfListScreenshotItemResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponseOfListScreenshotItemResponse" } } } }, "400": { "description": "Bad request \u2014 validation error or malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found \u2014 the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 the request is valid but cannot be completed in the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content \u2014 the request body is understood but contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "listTaskRunScreenshots", "description": "Returns a paginated list of agent screenshots captured during a task run, oldest first. Each item includes a pre-signed download URL and the agent's reasoning at the time of capture." } }, "/task-runs/{run_id}/cancel": { "post": { "tags": [ "Task Runs" ], "summary": "Cancel a task run", "parameters": [ { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the task run (prefixed with `trun_`)." } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/GetTaskRunResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/GetTaskRunResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/GetTaskRunResponse" } } } }, "400": { "description": "Bad request \u2014 validation error or malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found \u2014 the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 the request is valid but cannot be completed in the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content \u2014 the request body is understood but contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "cancelTaskRun", "description": "Cancels a running or queued task run." } }, "/task-runs/{run_id}/interaction": { "post": { "tags": [ "Task Runs" ], "summary": "Submit interaction input", "parameters": [ { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the task run (prefixed with `trun_`)." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitInteractionRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/SubmitInteractionRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/SubmitInteractionRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/GetTaskRunResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/GetTaskRunResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/GetTaskRunResponse" } } } }, "400": { "description": "Bad request \u2014 validation error or malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found \u2014 the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 the request is valid but cannot be completed in the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content \u2014 the request body is understood but contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "submitInteraction", "description": "Submits user input to resume a task run that is paused waiting for interaction (e.g. MFA code, security question)." } }, "/tasks": { "post": { "tags": [ "Tasks" ], "summary": "Create a task", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTaskRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/CreateTaskRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CreateTaskRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/CreateTaskResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/CreateTaskResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/CreateTaskResponse" } } } }, "400": { "description": "Bad request \u2014 validation error or malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found \u2014 the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 the request is valid but cannot be completed in the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content \u2014 the request body is understood but contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "createTask", "description": "Creates a new task on an agent. A task is a defined action an agent can perform, such as fetching data or submitting a form." }, "get": { "tags": [ "Tasks" ], "summary": "List tasks", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of items to return (1-100, default 20)", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Cursor from a previous response for pagination." }, { "name": "agent_id", "in": "query", "schema": { "type": "string" }, "description": "Filter by agent ID (prefixed with `agt_`)." }, { "name": "status", "in": "query", "description": "Filter by task status: learning, test, live", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/PaginatedResponseOfGetTaskResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponseOfGetTaskResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponseOfGetTaskResponse" } } } }, "400": { "description": "Bad request \u2014 validation error or malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found \u2014 the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 the request is valid but cannot be completed in the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content \u2014 the request body is understood but contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "listTasks", "description": "Returns a paginated list of tasks. Supports filtering by agent and status." } }, "/tasks/{task_id}": { "get": { "tags": [ "Tasks" ], "summary": "Retrieve a task", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the task (prefixed with `task_`)." } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/GetTaskResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/GetTaskResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/GetTaskResponse" } } } }, "400": { "description": "Bad request \u2014 validation error or malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found \u2014 the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 the request is valid but cannot be completed in the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content \u2014 the request body is understood but contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "getTask", "description": "Returns a single task by ID, including its input/output schemas and storage configuration." }, "patch": { "tags": [ "Tasks" ], "summary": "Update a task", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the task (prefixed with `task_`)." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTaskRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/UpdateTaskRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/UpdateTaskRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/UpdateTaskResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTaskResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/UpdateTaskResponse" } } } }, "400": { "description": "Bad request \u2014 validation error or malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found \u2014 the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 the request is valid but cannot be completed in the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content \u2014 the request body is understood but contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "updateTask", "description": "Updates a task's name, schemas, prompt, or storage configuration. Only the fields you include in the request body are updated." }, "delete": { "tags": [ "Tasks" ], "summary": "Delete a task", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the task (prefixed with `task_`)." } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/DeleteTaskResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/DeleteTaskResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/DeleteTaskResponse" } } } }, "400": { "description": "Bad request \u2014 validation error or malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found \u2014 the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 the request is valid but cannot be completed in the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content \u2014 the request body is understood but contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "deleteTask", "description": "Permanently deletes a task." } }, "/tasks/{task_id}/run": { "post": { "tags": [ "Tasks" ], "summary": "Run a task", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the task (prefixed with `task_`)." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunTaskRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/RunTaskRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/RunTaskRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/GetTaskRunResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/GetTaskRunResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/GetTaskRunResponse" } } } }, "400": { "description": "Bad request \u2014 validation error or malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found \u2014 the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 the request is valid but cannot be completed in the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content \u2014 the request body is understood but contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "runTask", "description": "Executes a task, creating a new task run. The run executes asynchronously. Use events or poll the task run endpoint to track progress." } }, "/tasks/{task_id}/reset": { "post": { "tags": [ "Tasks" ], "summary": "Reset a task", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the task (prefixed with `task_`)." } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/UpdateTaskResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTaskResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/UpdateTaskResponse" } } } }, "400": { "description": "Bad request \u2014 validation error or malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found \u2014 the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 the request is valid but cannot be completed in the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content \u2014 the request body is understood but contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "resetTask", "description": "Resets a task's status to `learning`. The next run re-learns the flow from scratch." } }, "/test": { "get": { "tags": [ "Test" ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/TestResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/TestResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/TestResponse" } } } }, "400": { "description": "Bad request \u2014 validation error or malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found \u2014 the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 the request is valid but cannot be completed in the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content \u2014 the request body is understood but contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "testApiKey", "description": "Verifies your API key is valid." } }, "/token": { "post": { "tags": [ "Components" ], "summary": "Create a session token", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSessionTokenResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "createSessionToken", "description": "Creates a short-lived session token for the Auth Component." } }, "/triggers": { "post": { "tags": [ "Triggers" ], "summary": "Create a trigger", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTriggerRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/CreateTriggerRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CreateTriggerRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/TriggerResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/TriggerResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/TriggerResponse" } } } }, "400": { "description": "Bad request \u2014 validation error or malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found \u2014 the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 the request is valid but cannot be completed in the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content \u2014 the request body is understood but contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "createTrigger", "description": "Creates a trigger that runs a task on a schedule across a set of credentials. The trigger is created active and fires on its schedule immediately." }, "get": { "tags": [ "Triggers" ], "summary": "List triggers", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of items to return (1-100, default 20)", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Cursor from a previous response for pagination." }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Filter by status: `active` or `inactive`." }, { "name": "task_id", "in": "query", "schema": { "type": "string" }, "description": "Filter to triggers that run this task. Prefixed with `task_`." } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/PaginatedResponseOfListTriggerData" } }, "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponseOfListTriggerData" } }, "text/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponseOfListTriggerData" } } } }, "400": { "description": "Bad request \u2014 validation error or malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found \u2014 the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 the request is valid but cannot be completed in the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content \u2014 the request body is understood but contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "listTriggers", "description": "Returns a paginated list of triggers in your organization." } }, "/triggers/{trigger_id}": { "get": { "tags": [ "Triggers" ], "summary": "Retrieve a trigger", "parameters": [ { "name": "trigger_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the trigger (prefixed with `trg_`)." } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/TriggerResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/TriggerResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/TriggerResponse" } } } }, "400": { "description": "Bad request \u2014 validation error or malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found \u2014 the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 the request is valid but cannot be completed in the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content \u2014 the request body is understood but contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "getTrigger", "description": "Retrieves a single trigger by ID." }, "patch": { "tags": [ "Triggers" ], "summary": "Update a trigger", "parameters": [ { "name": "trigger_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the trigger (prefixed with `trg_`)." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTriggerRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/UpdateTriggerRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/UpdateTriggerRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/TriggerResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/TriggerResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/TriggerResponse" } } } }, "400": { "description": "Bad request \u2014 validation error or malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found \u2014 the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 the request is valid but cannot be completed in the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content \u2014 the request body is understood but contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "updateTrigger", "description": "Updates a trigger. Send any subset of fields; omitted fields are left unchanged. Set `status` to `active` or `inactive` to resume or pause the trigger." }, "delete": { "tags": [ "Triggers" ], "summary": "Delete a trigger", "parameters": [ { "name": "trigger_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the trigger (prefixed with `trg_`)." } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/DeleteTriggerResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/DeleteTriggerResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/DeleteTriggerResponse" } } } }, "400": { "description": "Bad request \u2014 validation error or malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found \u2014 the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 the request is valid but cannot be completed in the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content \u2014 the request body is understood but contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "deleteTrigger", "description": "Permanently deletes a trigger. Scheduled fires stop immediately." } }, "/triggers/{trigger_id}/credentials": { "get": { "tags": [ "Triggers" ], "summary": "List trigger credentials", "parameters": [ { "name": "trigger_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the trigger (prefixed with `trg_`)." }, { "name": "limit", "in": "query", "description": "Maximum number of items to return (1-100, default 20)", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Cursor from a previous response for pagination." } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/PaginatedResponseOfListCredentialData" } }, "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponseOfListCredentialData" } }, "text/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponseOfListCredentialData" } } } }, "400": { "description": "Bad request \u2014 validation error or malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found \u2014 the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 the request is valid but cannot be completed in the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content \u2014 the request body is understood but contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "listTriggerCredentials", "description": "Returns the credentials currently in scope for this trigger: the explicit `credential_ids`, or the current matches of `credential_filter`. This is the set that will get runs on the next fire. Each entry is a standard credential object." } } }, "components": { "schemas": { "AuthCredentialsSummary": { "type": "object", "properties": { "username": { "type": [ "null", "string" ], "description": "The username associated with this credential, if applicable." }, "source_fields": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Non-tokenized `source_fields` returned as key/value pairs in the clear (for example, `{ \"company_id\": \"ACME-4412\" }`). Tokenized source fields are dropped from this map and named in `tokenized` instead. Omitted when empty." }, "tokenized": { "type": "array", "items": { "type": "string" }, "description": "Names of the source fields whose values were vaulted. Their values never appear in `source_fields` and cannot be read back through the API. Omitted when nothing was tokenized." } }, "description": "Summary of stored authentication credentials. Secret values such as `password` are encrypted at rest and never returned. Non-tokenized `source_fields` are returned in the clear; fields named in `tokenized` are vaulted and omitted from the map." }, "AuthCredentialsInput": { "type": "object", "properties": { "username": { "type": "string", "description": "Username for `username_password`." }, "password": { "type": "string", "description": "Password for `username_password`. Encrypted at rest and never returned." }, "source_fields": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Additional values the source requires at login, beyond what the `auth_method` covers (for example, `{ \"company_id\": \"ACME-4412\" }`). For the `source_fields` auth method, at least one entry is required. Values must be strings. Keys must match `^[a-z][a-z0-9_]{0,63}$`, must not collide with reserved keys on the `auth_method` (such as `username` or `password`), and are capped at 10 entries per credential. Values are returned in the clear on read unless named in `tokenized`." }, "tokenized": { "type": "array", "items": { "type": "string" }, "description": "Names of `source_fields` keys to vault. Each entry must name a key present in `source_fields`. Tokenized values are stored in a secure vault, removed from API responses, and listed by name in the response `tokenized` array; they cannot be read back. On update, may only name keys supplied in the same request. Auth secrets such as `password` are always vaulted regardless of this array." } }, "description": "Credentials payload. Structure depends on `auth_method`. For `username_password`, pass `username` and `password`. For `source_fields`, pass at least one entry in `source_fields`. Any `auth_method` except `none` may also include `source_fields` alongside its credentials (for example, `username` and `password` plus `source_fields` in the same payload), and `tokenized` to vault selected source-field values." }, "CreateAgentRequest": { "required": [ "name" ], "type": "object", "properties": { "name": { "type": "string", "description": "Display name for the agent." }, "description": { "type": [ "null", "string" ], "description": "A description of the agent's purpose." } }, "description": "Request body for creating a new agent." }, "CreateAgentResponse": { "required": [ "id", "object", "name", "description", "tasks", "created_at", "updated_at", "request_id" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the agent, prefixed with `agt_`." }, "object": { "type": "string", "description": "Always `agent`." }, "name": { "type": "string", "description": "Display name for the agent." }, "description": { "type": [ "null", "string" ], "description": "Description of the agent's purpose." }, "tasks": { "type": "array", "items": { "$ref": "#/components/schemas/TaskSummary" }, "description": "Tasks associated with this agent." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the resource was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the resource was last updated." }, "request_id": { "type": "string", "description": "Unique identifier for the API request. Include this when contacting support." } }, "description": "An agent object. Agents organize related tasks under a single use case." }, "PersistenceInput": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether to save this credential's login state between runs. Defaults to `false`." } }, "description": "Credential persistence settings. When enabled, Deck saves the credential's authenticated login state after each run and restores it on later runs. Sources that honor the restored state skip the login flow and repeat MFA prompts." }, "PersistenceSummary": { "required": [ "enabled" ], "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether persistence is enabled for this credential." } }, "description": "Persistence settings for this credential." }, "CreateCredentialRequest": { "required": [ "source_id" ], "type": "object", "properties": { "source_id": { "type": "string", "description": "The source to authenticate against. Prefixed with `src_`." }, "auth_method": { "type": [ "null", "string" ], "description": "Authentication method for the source. One of `username_password`, `source_fields`, or `none`. Defaults to `none` if not provided." }, "auth_credentials": { "$ref": "#/components/schemas/AuthCredentialsInput" }, "external_id": { "type": [ "null", "string" ], "description": "An identifier from your system to associate with this credential. Max 255 characters. See the external IDs guide for multi-tenant patterns." }, "persistence": { "$ref": "#/components/schemas/PersistenceInput", "description": "Persistence settings. Omit to leave persistence off." } }, "description": "Request body for creating a new credential." }, "CreateCredentialResponse": { "required": [ "id", "object", "status", "external_id", "source_id", "auth_method", "auth_credentials", "persistence", "created_at", "updated_at", "request_id" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the credential, prefixed with `cred_`." }, "object": { "type": "string", "description": "Always `credential`." }, "status": { "type": "string", "description": "Credential status: `unverified`, `verified`, `invalid`, or `deleted`." }, "external_id": { "type": [ "null", "string" ], "description": "External identifier from your system, if set." }, "source_id": { "type": "string", "description": "The source this credential authenticates against. Prefixed with `src_`." }, "auth_method": { "type": "string", "description": "Authentication method: `username_password`, `source_fields`, or `none`." }, "auth_credentials": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AuthCredentialsSummary" } ], "description": "Summary of stored credentials. Sensitive values are not returned." }, "persistence": { "$ref": "#/components/schemas/PersistenceSummary", "description": "Persistence settings for this credential." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the resource was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the resource was last updated." }, "request_id": { "type": "string", "description": "Unique identifier for the API request. Include this when contacting support." } } }, "CreateEventDestinationRequest": { "required": [ "name" ], "type": "object", "properties": { "name": { "type": "string", "description": "Display name for the event destination." }, "type": { "type": "string", "enum": [ "webhook", "aws_sqs", "aws_kinesis", "aws_s3", "aws_eventbridge", "gcp_pubsub", "rabbitmq", "azure_servicebus", "hookdeck" ], "description": "Destination type. Defaults to `webhook` if omitted. Send the matching configuration object under a property whose name equals this value (for example, when `type` is `aws_sqs`, include an `aws_sqs` object)." }, "events": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Event types to subscribe to (for example `task_run.completed`, `credential.verified`). Use `[\"*\"]` to subscribe to all event types; `*` cannot be combined with specific types, and the list must not be empty." }, "webhook": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "Absolute `https` or `http` URL that receives event deliveries." }, "secret": { "type": "string", "description": "Signing secret used to verify webhook signatures. Write-only; never returned." } }, "description": "Configuration for a `webhook` destination. Provide this object under the `webhook` property when `type` is `webhook`." }, "aws_sqs": { "type": "object", "required": [ "queue_url" ], "properties": { "queue_url": { "type": "string", "description": "URL of the destination Amazon SQS queue." }, "key": { "type": "string", "description": "AWS access key ID. Accepted alias: `access_key`. Write-only." }, "secret": { "type": "string", "description": "AWS secret access key. Accepted alias: `secret_key`. Write-only." } }, "description": "Configuration for a `aws_sqs` destination. Provide this object under the `aws_sqs` property when `type` is `aws_sqs`." }, "aws_kinesis": { "type": "object", "required": [ "stream_name", "region" ], "properties": { "stream_name": { "type": "string", "description": "Name of the Amazon Kinesis stream." }, "region": { "type": "string", "description": "AWS region of the stream." }, "key": { "type": "string", "description": "AWS access key ID. Accepted alias: `access_key`. Write-only." }, "secret": { "type": "string", "description": "AWS secret access key. Accepted alias: `secret_key`. Write-only." } }, "description": "Configuration for a `aws_kinesis` destination. Provide this object under the `aws_kinesis` property when `type` is `aws_kinesis`." }, "aws_s3": { "type": "object", "required": [ "bucket", "region" ], "properties": { "bucket": { "type": "string", "description": "Name of the destination Amazon S3 bucket." }, "region": { "type": "string", "description": "AWS region of the bucket." }, "key": { "type": "string", "description": "AWS access key ID. Accepted alias: `access_key`. Write-only." }, "secret": { "type": "string", "description": "AWS secret access key. Accepted alias: `secret_key`. Write-only." } }, "description": "Configuration for a `aws_s3` destination. Provide this object under the `aws_s3` property when `type` is `aws_s3`." }, "aws_eventbridge": { "type": "object", "required": [ "event_bus_name", "region" ], "properties": { "event_bus_name": { "type": "string", "description": "Name of the Amazon EventBridge event bus." }, "region": { "type": "string", "description": "AWS region of the event bus." }, "access_key_id": { "type": "string", "description": "AWS access key ID. Write-only." }, "secret_access_key": { "type": "string", "description": "AWS secret access key. Write-only." } }, "description": "Configuration for a `aws_eventbridge` destination. Provide this object under the `aws_eventbridge` property when `type` is `aws_eventbridge`." }, "gcp_pubsub": { "type": "object", "required": [ "project_id", "topic" ], "properties": { "project_id": { "type": "string", "description": "Google Cloud project ID." }, "topic": { "type": "string", "description": "Pub/Sub topic name. Accepted alias: `topic_name`." }, "service_account_json": { "type": "string", "description": "Service account credentials JSON. Accepted alias: `credentials_json`. Write-only." } }, "description": "Configuration for a `gcp_pubsub` destination. Provide this object under the `gcp_pubsub` property when `type` is `gcp_pubsub`." }, "rabbitmq": { "type": "object", "required": [ "exchange", "server_url" ], "properties": { "exchange": { "type": "string", "description": "Name of the RabbitMQ exchange." }, "server_url": { "type": "string", "description": "RabbitMQ host as `host[:port]` (for example `rabbitmq:5672`). You may instead pass a full AMQP URL with embedded credentials; Deck extracts the host, username, and password from it." }, "username": { "type": "string", "description": "RabbitMQ username (or embed it in the AMQP `server_url`). Write-only." }, "password": { "type": "string", "description": "RabbitMQ password (or embed it in the AMQP `server_url`). Write-only." } }, "description": "Configuration for a `rabbitmq` destination. Provide this object under the `rabbitmq` property when `type` is `rabbitmq`." }, "azure_servicebus": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Name of the Service Bus queue or topic. Accepted alias: `queue_name`." }, "connection_string": { "type": "string", "description": "Azure Service Bus connection string. Write-only." } }, "description": "Configuration for a `azure_servicebus` destination. Provide this object under the `azure_servicebus` property when `type` is `azure_servicebus`." }, "hookdeck": { "type": "object", "properties": { "token": { "type": "string", "description": "Hookdeck API key. Accepted alias: `api_key`. Write-only." } }, "description": "Configuration for a `hookdeck` destination. Provide this object under the `hookdeck` property when `type` is `hookdeck`." } }, "description": "Request body for creating a new event destination. Provide `name`, `type`, `events`, and exactly one type-specific configuration object whose property name matches `type` (for example `{\"type\": \"webhook\", \"webhook\": {\"url\": \"...\"}}`)." }, "CreateSessionResponse": { "required": [ "id", "object", "status", "runtime_ms", "task_runs", "created_at", "updated_at", "request_id" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the session, prefixed with `sess_`." }, "object": { "type": "string", "description": "Always `session`." }, "status": { "type": "string", "description": "Session status: `queued`, `running`, `idle`, `completing`, `completed`, or `failed`." }, "runtime_ms": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32", "description": "Total session runtime in milliseconds." }, "task_runs": { "type": "array", "items": { "$ref": "#/components/schemas/SessionTaskRunData" }, "description": "Task runs executed within this session." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the resource was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the resource was last updated." }, "request_id": { "type": "string", "description": "Unique identifier for the API request. Include this when contacting support." } }, "description": "A session object representing an isolated compute session for executing tasks." }, "CreateSessionTokenResponse": { "required": [ "id", "object", "token", "expires_at", "created_at", "request_id" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the session token, prefixed with `tok_`." }, "object": { "type": "string", "description": "Always `token`." }, "token": { "type": "string", "description": "The token value to pass to ``. Prefixed with `tk_`. Treat as a bearer secret until it expires." }, "expires_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp at which the token stops being accepted. 30 minutes after `created_at`." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the token was created." }, "request_id": { "type": "string", "description": "Unique identifier for the API request. Include this when contacting support." } }, "description": "A session token for the Auth Component. Short-lived (30 minutes) and scoped to a single component session." }, "CreateSourceRequest": { "required": [ "type", "website" ], "type": "object", "properties": { "type": { "type": "string", "description": "The source type. `website` is currently the only supported type; it defaults to `website` if omitted." }, "website": { "$ref": "#/components/schemas/SourceWebsite", "description": "Website configuration for the source." }, "name": { "type": [ "null", "string" ], "description": "Display name for the source." } }, "description": "Request body for creating a new source." }, "CreateSourceResponse": { "required": [ "id", "object", "name", "type", "website", "created_at", "updated_at", "request_id" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the source, prefixed with `src_`." }, "object": { "type": "string", "description": "Always `source`." }, "name": { "type": [ "null", "string" ], "description": "Display name for the source." }, "type": { "type": "string", "description": "The source type. `website` is currently the only supported type; it defaults to `website` if omitted." }, "website": { "$ref": "#/components/schemas/SourceWebsite", "description": "Website configuration for the source." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the resource was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the resource was last updated." }, "request_id": { "type": "string", "description": "Unique identifier for the API request. Include this when contacting support." } }, "description": "A source object. Sources are websites or services that agents connect to." }, "CreateTaskRequest": { "required": [ "name", "agent_id" ], "type": "object", "properties": { "name": { "type": "string", "description": "Display name for the task." }, "agent_id": { "type": "string", "description": "The agent this task belongs to. Prefixed with `agt_`." }, "id": { "type": [ "null", "string" ], "description": "Optional client-specified ID for the task. If not provided, Deck generates one." }, "input_schema": { "description": "JSON Schema defining the expected input for task runs." }, "output_schema": { "description": "JSON Schema defining the expected output for task runs." }, "prompt": { "type": [ "null", "string" ], "description": "Instructions for the agent describing what this task should do." }, "storage": { "description": "Storage configuration for file capture. Set `enabled` to `true` to capture files. Supports `enabled`, `extraction`, `extraction_schema`, `extraction_prompt`, `deduplication`, and `deduplication_schema` fields." }, "settings": { "type": "object", "properties": { "timeout_seconds": { "type": "integer", "minimum": 1, "description": "Maximum wall-clock time, in seconds, that a single run of this task may execute before Deck stops it and the run fails with a `timeout` error. Must be a positive integer. The maximum you can set is determined by your plan (see https://deck.co/pricing); the overall ceiling is 28800 seconds (8 hours). If omitted, the task uses your plan's default timeout. A value above your plan's maximum is rejected when the task is created or updated with a `422` `timeout_exceeds_plan_max` error." }, "sensitive": { "type": "boolean", "description": "Marks the task as sensitive. When `true`, the Console hides the live browser view, agent reasoning, and screenshots for this task's runs. Must be a boolean; any other value is rejected with a `422` `invalid_field_value` error. If omitted, the task is not sensitive." } }, "description": "Task-level settings. Supports `timeout_seconds` and `sensitive`." } }, "description": "Request body for creating a new task." }, "CreateTaskResponse": { "required": [ "id", "object", "name", "prompt", "status", "agent_id", "input_schema", "output_schema", "storage", "settings", "created_at", "updated_at", "request_id" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the task, prefixed with `task_`." }, "object": { "type": "string", "description": "Always `task`." }, "name": { "type": "string", "description": "Display name for the task." }, "prompt": { "type": [ "null", "string" ], "description": "Instructions for the agent describing what this task should do." }, "status": { "type": "string", "description": "Task status: `learning`, `test`, or `live`." }, "agent_id": { "type": "string", "description": "The agent this task belongs to. Prefixed with `agt_`." }, "input_schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/JsonElement" } ], "description": "JSON Schema defining the expected input for task runs." }, "output_schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/JsonElement" } ], "description": "JSON Schema defining the expected output for task runs." }, "storage": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/JsonElement" } ], "description": "Storage configuration for file capture during task execution." }, "settings": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/JsonElement" } ], "description": "Task-level settings. Supports `timeout_seconds` (the per-run timeout, in seconds) and `sensitive` (when `true`, the Console hides the live browser view, agent reasoning, and screenshots for this task's runs). `null` when no settings were set on the task, in which case runs use your plan's default timeout and the task is not sensitive." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the resource was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the resource was last updated." }, "request_id": { "type": "string", "description": "Unique identifier for the API request. Include this when contacting support." } }, "description": "A task object. Tasks are defined actions an agent can perform." }, "DeleteAgentResponse": { "required": [ "id", "object", "deleted", "request_id" ], "type": "object", "properties": { "id": { "type": "string", "description": "ID of the deleted agent." }, "object": { "type": "string", "description": "Always `agent`." }, "deleted": { "type": "boolean", "description": "Always `true` for successful deletions." }, "request_id": { "type": "string", "description": "Unique identifier for the API request. Include this when contacting support." } }, "description": "Confirmation object returned after a successful deletion." }, "DeleteCredentialResponse": { "required": [ "id", "object", "status", "request_id" ], "type": "object", "properties": { "id": { "type": "string", "description": "ID of the deleted credential." }, "object": { "type": "string", "description": "Always `credential`." }, "status": { "type": "string", "description": "Credential status after deletion." }, "request_id": { "type": "string", "description": "Unique identifier for the API request. Include this when contacting support." } }, "description": "Confirmation object returned after a successful credential deletion." }, "DeleteEventDestinationResponse": { "required": [ "id", "object", "deleted", "request_id" ], "type": "object", "properties": { "id": { "type": "string", "description": "ID of the deleted event destination." }, "object": { "type": "string", "description": "Always `event_destination`." }, "deleted": { "type": "boolean", "description": "Always `true` for successful deletions." }, "request_id": { "type": "string", "description": "Unique identifier for the API request. Include this when contacting support." } }, "description": "Confirmation object returned after a successful deletion." }, "DeleteSourceResponse": { "required": [ "id", "object", "deleted", "request_id" ], "type": "object", "properties": { "id": { "type": "string", "description": "ID of the deleted source." }, "object": { "type": "string", "description": "Always `source`." }, "deleted": { "type": "boolean", "description": "Always `true` for successful deletions." }, "request_id": { "type": "string", "description": "Unique identifier for the API request. Include this when contacting support." } }, "description": "Confirmation object returned after a successful deletion." }, "DeleteTaskResponse": { "required": [ "id", "object", "deleted", "request_id" ], "type": "object", "properties": { "id": { "type": "string", "description": "ID of the deleted task." }, "object": { "type": "string", "description": "Always `task`." }, "deleted": { "type": "boolean", "description": "Always `true` for successful deletions." }, "request_id": { "type": "string", "description": "Unique identifier for the API request. Include this when contacting support." } }, "description": "Confirmation object returned after a successful deletion." }, "EventDeliveryResponse": { "type": "object", "properties": { "object": { "type": "string", "description": "Always `event_delivery`." }, "status": { "type": "string", "description": "Delivery status: `success` or `failure`." }, "event_type": { "type": [ "null", "string" ], "description": "The type of event that was delivered." }, "event_id": { "type": "string", "description": "The event that was delivered. Prefixed with `evt_`." }, "event_destination_id": { "type": "string", "description": "The destination the event was delivered to. Prefixed with `evtd_`." }, "attempts": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32", "description": "Number of delivery attempts." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the resource was created." }, "delivered_at": { "type": [ "null", "string" ], "format": "date-time", "description": "ISO 8601 timestamp of successful delivery, if applicable." } }, "description": "A record of an event sent to a destination." }, "EventDestinationResponse": { "required": [ "id", "object", "name", "status", "type", "events", "created_at", "updated_at" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the event destination, prefixed with `evtd_`." }, "object": { "type": "string", "description": "Always `event_destination`." }, "name": { "type": "string", "description": "Display name for the event destination." }, "status": { "type": "string", "description": "Destination status: `pending_verification`, `active`, or `inactive`." }, "type": { "type": "string", "enum": [ "webhook", "aws_sqs", "aws_kinesis", "aws_s3", "aws_eventbridge", "gcp_pubsub", "rabbitmq", "azure_servicebus", "hookdeck" ], "description": "Destination type. The endpoint configuration is returned under a property whose name equals this value (for example, a `webhook` destination returns a `webhook` object)." }, "events": { "type": "array", "items": { "type": "string" }, "description": "Event types this destination is subscribed to." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the resource was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the resource was last updated." }, "request_id": { "type": [ "null", "string" ], "description": "Unique identifier for the API request. Include this when contacting support." }, "webhook": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "Absolute `https` or `http` URL that receives event deliveries." } }, "description": "Configuration returned for a `webhook` destination (credentials are never returned)." }, "aws_sqs": { "type": "object", "required": [ "queue_url" ], "properties": { "queue_url": { "type": "string", "description": "URL of the destination Amazon SQS queue." } }, "description": "Configuration returned for a `aws_sqs` destination (credentials are never returned)." }, "aws_kinesis": { "type": "object", "required": [ "stream_name", "region" ], "properties": { "stream_name": { "type": "string", "description": "Name of the Amazon Kinesis stream." }, "region": { "type": "string", "description": "AWS region of the stream." } }, "description": "Configuration returned for a `aws_kinesis` destination (credentials are never returned)." }, "aws_s3": { "type": "object", "required": [ "bucket", "region" ], "properties": { "bucket": { "type": "string", "description": "Name of the destination Amazon S3 bucket." }, "region": { "type": "string", "description": "AWS region of the bucket." } }, "description": "Configuration returned for a `aws_s3` destination (credentials are never returned)." }, "aws_eventbridge": { "type": "object", "required": [ "event_bus_name", "region" ], "properties": { "event_bus_name": { "type": "string", "description": "Name of the Amazon EventBridge event bus." }, "region": { "type": "string", "description": "AWS region of the event bus." } }, "description": "Configuration returned for a `aws_eventbridge` destination (credentials are never returned)." }, "gcp_pubsub": { "type": "object", "required": [ "project_id", "topic" ], "properties": { "project_id": { "type": "string", "description": "Google Cloud project ID." }, "topic": { "type": "string", "description": "Pub/Sub topic name. Accepted alias: `topic_name`." } }, "description": "Configuration returned for a `gcp_pubsub` destination (credentials are never returned)." }, "rabbitmq": { "type": "object", "required": [ "exchange", "server_url" ], "properties": { "exchange": { "type": "string", "description": "Name of the RabbitMQ exchange." }, "server_url": { "type": "string", "description": "RabbitMQ host as `host[:port]` (for example `rabbitmq:5672`). You may instead pass a full AMQP URL with embedded credentials; Deck extracts the host, username, and password from it." } }, "description": "Configuration returned for a `rabbitmq` destination (credentials are never returned)." }, "azure_servicebus": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Name of the Service Bus queue or topic. Accepted alias: `queue_name`." } }, "description": "Configuration returned for a `azure_servicebus` destination (credentials are never returned)." }, "hookdeck": { "type": "object", "properties": {}, "description": "Configuration returned for a `hookdeck` destination (credentials are never returned)." } }, "description": "An event destination object representing an endpoint that receives platform events." }, "EventResponse": { "required": [ "id", "object", "type", "data", "created_at", "request_id" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the event, prefixed with `evt_`." }, "object": { "type": "string", "description": "Always `event`." }, "type": { "type": "string", "description": "Event type (e.g. `task_run.completed`, `credential.verified`)." }, "data": { "$ref": "#/components/schemas/JsonElement", "description": "Event payload containing a summary of the resource that triggered the event." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the resource was created." }, "request_id": { "type": [ "null", "string" ], "description": "Unique identifier for the API request. Include this when contacting support." } }, "description": "A lifecycle event emitted by the platform." }, "EventTypeItem": { "required": [ "type", "description" ], "type": "object", "properties": { "type": { "type": "string", "description": "Event type identifier (e.g. `task_run.completed`)." }, "description": { "type": "string", "description": "Human-readable description of when this event fires." } }, "description": "An available event type." }, "GetAgentResponse": { "required": [ "id", "object", "name", "description", "tasks", "created_at", "updated_at", "request_id" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the agent, prefixed with `agt_`." }, "object": { "type": "string", "description": "Always `agent`." }, "name": { "type": "string", "description": "Display name for the agent." }, "description": { "type": [ "null", "string" ], "description": "Description of the agent's purpose." }, "tasks": { "type": "array", "items": { "$ref": "#/components/schemas/TaskSummary" }, "description": "Tasks associated with this agent." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the resource was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the resource was last updated." }, "request_id": { "type": "string", "description": "Unique identifier for the API request. Include this when contacting support." } }, "description": "An agent object. Agents organize related tasks under a single use case." }, "GetCredentialResponse": { "required": [ "id", "object", "status", "external_id", "source_id", "auth_method", "auth_credentials", "persistence", "created_at", "updated_at", "request_id" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the credential, prefixed with `cred_`." }, "object": { "type": "string", "description": "Always `credential`." }, "status": { "type": "string", "description": "Credential status: `unverified`, `verified`, `invalid`, or `deleted`." }, "external_id": { "type": [ "null", "string" ], "description": "External identifier from your system, if set." }, "source_id": { "type": "string", "description": "The source this credential authenticates against. Prefixed with `src_`." }, "auth_method": { "type": "string", "description": "Authentication method: `username_password`, `source_fields`, or `none`." }, "auth_credentials": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AuthCredentialsSummary" } ], "description": "Summary of stored credentials. Sensitive values are not returned." }, "persistence": { "$ref": "#/components/schemas/PersistenceSummary", "description": "Persistence settings for this credential." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the resource was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the resource was last updated." }, "request_id": { "type": "string", "description": "Unique identifier for the API request. Include this when contacting support." } } }, "GetSessionResponse": { "required": [ "id", "object", "status", "runtime_ms", "task_runs", "created_at", "updated_at", "request_id" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the session, prefixed with `sess_`." }, "object": { "type": "string", "description": "Always `session`." }, "status": { "type": "string", "description": "Session status: `queued`, `running`, `idle`, `completing`, `completed`, or `failed`." }, "runtime_ms": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32", "description": "Total session runtime in milliseconds." }, "task_runs": { "type": "array", "items": { "$ref": "#/components/schemas/SessionTaskRunData" }, "description": "Task runs executed within this session." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the resource was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the resource was last updated." }, "request_id": { "type": "string", "description": "Unique identifier for the API request. Include this when contacting support." } }, "description": "A session object representing an isolated compute session for executing tasks." }, "GetSourceResponse": { "required": [ "id", "object", "name", "type", "website", "created_at", "updated_at", "request_id" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the source, prefixed with `src_`." }, "object": { "type": "string", "description": "Always `source`." }, "name": { "type": [ "null", "string" ], "description": "Display name for the source." }, "type": { "type": "string", "description": "The source type. `website` is currently the only supported type; it defaults to `website` if omitted." }, "website": { "$ref": "#/components/schemas/SourceWebsite", "description": "Website configuration for the source." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the resource was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the resource was last updated." }, "request_id": { "type": "string", "description": "Unique identifier for the API request. Include this when contacting support." } }, "description": "A source object. Sources are websites or services that agents connect to." }, "GetStorageItemResponse": { "required": [ "id", "object", "file_name", "file_type", "file_size", "url", "metadata", "extraction", "task_run_id", "result", "created_at" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the storage item, prefixed with `stor_`." }, "object": { "type": "string", "description": "Always `storage`." }, "file_name": { "type": "string", "description": "Original file name as it appeared on the source." }, "file_type": { "type": "string", "description": "MIME type (e.g. `application/pdf`, `image/png`, `text/csv`)." }, "file_size": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64", "description": "File size in bytes." }, "url": { "type": [ "null", "string" ], "description": "Signed download URL for the file." }, "metadata": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/JsonElement" } ], "description": "A JSON object of additional key-value details Deck records about the file, or `null` when there are none. Which keys appear depends on the file and how it was captured, so treat it as informational and don't depend on specific keys being present." }, "extraction": { "description": "Structured data extracted from the file, if extraction is enabled. Null if extraction failed or is not enabled." }, "task_run_id": { "type": "string", "description": "The task run that produced this storage item. Prefixed with `trun_`." }, "result": { "type": "string", "description": "Extraction outcome: `failure` if the file's data couldn't be extracted, otherwise `success` (including files with no extraction)." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the resource was created." } }, "description": "A storage item representing a file captured during a task run." }, "GetTaskResponse": { "required": [ "id", "object", "name", "prompt", "status", "agent_id", "input_schema", "output_schema", "storage", "settings", "created_at", "updated_at", "request_id" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the task, prefixed with `task_`." }, "object": { "type": "string", "description": "Always `task`." }, "name": { "type": "string", "description": "Display name for the task." }, "prompt": { "type": [ "null", "string" ], "description": "Instructions for the agent describing what this task should do." }, "status": { "type": "string", "description": "Task status: `learning`, `test`, or `live`." }, "agent_id": { "type": "string", "description": "The agent this task belongs to. Prefixed with `agt_`." }, "input_schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/JsonElement" } ], "description": "JSON Schema defining the expected input for task runs." }, "output_schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/JsonElement" } ], "description": "JSON Schema defining the expected output for task runs." }, "storage": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/JsonElement" } ], "description": "Storage configuration for file capture during task execution." }, "settings": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/JsonElement" } ], "description": "Task-level settings. Supports `timeout_seconds` (the per-run timeout, in seconds) and `sensitive` (when `true`, the Console hides the live browser view, agent reasoning, and screenshots for this task's runs). `null` when no settings were set on the task, in which case runs use your plan's default timeout and the task is not sensitive." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the resource was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the resource was last updated." }, "request_id": { "type": "string", "description": "Unique identifier for the API request. Include this when contacting support." } }, "description": "A task object. Tasks are defined actions an agent can perform." }, "GetTaskRunResponse": { "required": [ "id", "object", "status", "result", "task_id", "trigger_id", "credential_id", "session_id", "agent_id", "source_id", "runtime_ms", "output", "errors", "interaction", "created_at", "updated_at", "request_id" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the task run, prefixed with `trun_`." }, "object": { "type": "string", "description": "Always `task_run`." }, "status": { "type": "string", "description": "Run status: `queued`, `running`, `canceling`, `interaction_required`, `review_required`, `completed`, `canceled`, or `failed`." }, "result": { "type": [ "null", "string" ], "description": "Run result after completion: `success`, `failure`, or `unknown`. Null while running." }, "task_id": { "type": "string", "description": "The task that was executed. Prefixed with `task_`." }, "trigger_id": { "type": [ "null", "string" ], "description": "The trigger that created this run, if any. Prefixed with `trg_`. `null` for runs created directly through the API." }, "credential_id": { "type": [ "null", "string" ], "description": "The credential used for authentication, if any. Prefixed with `cred_`." }, "session_id": { "type": [ "null", "string" ], "description": "The session this run executed within, if any. Prefixed with `sess_`." }, "agent_id": { "type": "string", "description": "The agent that executed this run. Prefixed with `agt_`." }, "source_id": { "type": [ "null", "string" ], "description": "The source this run connected to, if any. Prefixed with `src_`." }, "runtime_ms": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32", "description": "Execution time in milliseconds." }, "input": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/JsonElement" } ], "description": "Input data provided when the run was created." }, "tokenized": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Names of input fields whose values were tokenized when the run was created. The listed fields are removed from `input`. Returned alongside `input` (only when `include=input` is requested and one or more fields were vaulted); omitted otherwise." }, "output": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/JsonElement" } ], "description": "Output data produced by the task execution." }, "storage": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/TaskRunStorageItem" }, "description": "Files captured during the run, each with inline extraction (if any). Returned only when `include=storage` is requested." }, "storage_deduplicated": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/TaskRunDeduplicatedFile" }, "description": "Files skipped by deduplication during the run. Returned only when `include=storage_deduplicated` is requested and the run's task has `storage.deduplication` enabled; omitted otherwise. An empty array means deduplication ran and no files were skipped." }, "artifacts": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TaskRunArtifactData" } ], "description": "Run-level visibility artifacts (screenshots). Returned only when `include=artifacts` is requested." }, "errors": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/TaskRunError" }, "description": "Error details if the run failed. Same structure as API-level errors." }, "interaction": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/JsonElement" } ], "description": "Interaction details when the run is paused waiting for user input (e.g. MFA code, security question)." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the resource was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the resource was last updated." }, "request_id": { "type": "string", "description": "Unique identifier for the API request. Include this when contacting support." } }, "description": "A task run object representing a single execution of a task." }, "JsonElement": { "description": "Arbitrary JSON value." }, "ListAgentData": { "required": [ "id", "object", "name", "description", "tasks", "created_at", "updated_at" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the agent, prefixed with `agt_`." }, "object": { "type": "string", "description": "Always `agent`." }, "name": { "type": "string", "description": "Display name for the agent." }, "description": { "type": [ "null", "string" ], "description": "Description of the agent's purpose." }, "tasks": { "type": "array", "items": { "$ref": "#/components/schemas/TaskSummary" }, "description": "Tasks associated with this agent." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the resource was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the resource was last updated." } }, "description": "An agent object. Agents organize related tasks under a single use case." }, "ListCredentialData": { "required": [ "id", "object", "status", "external_id", "source_id", "auth_method", "auth_credentials", "persistence", "created_at", "updated_at" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the credential, prefixed with `cred_`." }, "object": { "type": "string", "description": "Always `credential`." }, "status": { "type": "string", "description": "Credential status: `unverified`, `verified`, `invalid`, or `deleted`." }, "external_id": { "type": [ "null", "string" ], "description": "External identifier from your system, if set." }, "source_id": { "type": "string", "description": "The source this credential authenticates against. Prefixed with `src_`." }, "auth_method": { "type": "string", "description": "Authentication method: `username_password`, `source_fields`, or `none`." }, "auth_credentials": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AuthCredentialsSummary" } ], "description": "Summary of stored credentials. Sensitive values are not returned." }, "persistence": { "$ref": "#/components/schemas/PersistenceSummary", "description": "Persistence settings for this credential." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the resource was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the resource was last updated." } } }, "ListEventData": { "required": [ "id", "object", "type", "data", "created_at" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the event, prefixed with `evt_`." }, "object": { "type": "string", "description": "Always `event`." }, "type": { "type": "string", "description": "Event type (e.g. `task_run.completed`, `credential.verified`)." }, "data": { "$ref": "#/components/schemas/JsonElement", "description": "Event payload containing a summary of the resource that triggered the event." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the resource was created." } }, "description": "A lifecycle event emitted by the platform." }, "ListEventTypesResponse": { "required": [ "data", "request_id" ], "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EventTypeItem" }, "description": "Array of available event types." }, "request_id": { "type": "string" } }, "description": "Response containing all available event types." }, "ListSessionData": { "required": [ "id", "object", "status", "runtime_ms", "task_runs", "created_at", "updated_at" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the session, prefixed with `sess_`." }, "object": { "type": "string", "description": "Always `session`." }, "status": { "type": "string", "description": "Session status: `queued`, `running`, `idle`, `completing`, `completed`, or `failed`." }, "runtime_ms": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32", "description": "Total session runtime in milliseconds." }, "task_runs": { "type": "array", "items": { "$ref": "#/components/schemas/SessionTaskRunData" }, "description": "Task runs executed within this session." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the resource was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the resource was last updated." } }, "description": "A session object representing an isolated compute session for executing tasks." }, "ListSourceResponse": { "required": [ "id", "object", "name", "type", "website", "created_at", "updated_at" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the source, prefixed with `src_`." }, "object": { "type": "string", "description": "Always `source`." }, "name": { "type": [ "null", "string" ], "description": "Display name for the source." }, "type": { "type": "string", "description": "The source type. `website` is currently the only supported type; it defaults to `website` if omitted." }, "website": { "$ref": "#/components/schemas/SourceWebsite", "description": "Website configuration for the source." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the resource was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the resource was last updated." } }, "description": "A source object. Sources are websites or services that agents connect to." }, "ListStorageItemResponse": { "required": [ "id", "object", "file_name", "file_type", "file_size", "url", "metadata", "extraction", "purpose", "result", "created_at" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the storage item, prefixed with `stor_`." }, "object": { "type": "string", "description": "Always `storage`." }, "file_name": { "type": "string", "description": "Original file name as it appeared on the source." }, "file_type": { "type": "string", "description": "MIME type (e.g. `application/pdf`, `image/png`, `text/csv`)." }, "file_size": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64", "description": "File size in bytes." }, "url": { "type": [ "null", "string" ], "description": "Pre-signed URL to download the file. Time-limited; re-fetch the item if it expires." }, "metadata": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/JsonElement" } ], "description": "A JSON object of additional key-value details Deck records about the file, or `null` when there are none. Which keys appear depends on the file and how it was captured, so treat it as informational and don't depend on specific keys being present." }, "extraction": { "description": "Structured data extracted from the file, if extraction is enabled. Null if extraction failed or is not enabled." }, "purpose": { "type": "string", "enum": [ "attachment", "extraction", "output" ], "description": "How the file relates to the run: `attachment` (a file you provided as task input for the agent to use), `extraction` (a file you provided as task input that Deck extracts data from directly, skipping the agent), or `output` (a file the agent captured during the run)." }, "result": { "type": "string", "description": "Extraction outcome: `failure` if the file's data couldn't be extracted, otherwise `success` (including files with no extraction)." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the resource was created." } }, "description": "A storage item representing a file captured during a task run." }, "ListScreenshotItemResponse": { "required": [ "id", "object", "file_name", "file_type", "file_size", "created_at" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the storage item, prefixed with `stor_`." }, "object": { "type": "string", "description": "Always `screenshot`." }, "file_name": { "type": "string", "description": "Original file name." }, "file_type": { "type": "string", "description": "MIME type of the screenshot (e.g. `image/png`, `image/jpeg`)." }, "file_size": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64", "description": "File size in bytes." }, "url": { "type": [ "null", "string" ], "description": "Pre-signed URL to download the screenshot. Time-limited; re-fetch the item if it expires." }, "reasoning": { "type": [ "null", "string" ], "description": "Agent reasoning captured at the time of this screenshot, if any." }, "created_at": { "type": "string", "format": "date-time", "description": "When the screenshot was captured." } }, "description": "A single agent screenshot captured during a task run." }, "ListTaskRunData": { "required": [ "id", "object", "status", "result", "task_id", "trigger_id", "credential_id", "session_id", "agent_id", "source_id", "runtime_ms", "output", "errors", "interaction", "created_at", "updated_at" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the task run, prefixed with `trun_`." }, "object": { "type": "string", "description": "Always `task_run`." }, "status": { "type": "string", "description": "Run status: `queued`, `running`, `canceling`, `interaction_required`, `review_required`, `completed`, `canceled`, or `failed`." }, "result": { "type": [ "null", "string" ], "description": "Run result after completion: `success`, `failure`, or `unknown`. Null while running." }, "task_id": { "type": "string", "description": "The task that was executed. Prefixed with `task_`." }, "trigger_id": { "type": [ "null", "string" ], "description": "The trigger that created this run, if any. Prefixed with `trg_`. `null` for runs created directly through the API." }, "credential_id": { "type": [ "null", "string" ], "description": "The credential used for authentication, if any. Prefixed with `cred_`." }, "session_id": { "type": [ "null", "string" ], "description": "The session this run executed within, if any. Prefixed with `sess_`." }, "agent_id": { "type": "string", "description": "The agent that executed this run. Prefixed with `agt_`." }, "source_id": { "type": [ "null", "string" ], "description": "The source this run connected to, if any. Prefixed with `src_`." }, "runtime_ms": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32", "description": "Execution time in milliseconds." }, "output": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/JsonElement" } ], "description": "Output data produced by the task execution." }, "errors": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/TaskRunError" }, "description": "Error details if the run failed. Same structure as API-level errors." }, "interaction": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/JsonElement" } ], "description": "Interaction details when the run is paused waiting for user input (e.g. MFA code, security question)." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the resource was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the resource was last updated." } }, "description": "A task run object representing a single execution of a task." }, "PaginatedResponseOfEventDeliveryResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EventDeliveryResponse" }, "description": "Array of resource objects for the current page." }, "has_more": { "type": "boolean", "description": "`true` if there are more results beyond this page." }, "next_cursor": { "type": [ "null", "string" ], "description": "Opaque cursor string to pass as the `cursor` query parameter on the next request. `null` when there are no more pages." }, "request_id": { "type": [ "null", "string" ], "description": "Unique identifier for the API request." } } }, "PaginatedResponseOfEventDestinationResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EventDestinationResponse" }, "description": "Array of resource objects for the current page." }, "has_more": { "type": "boolean", "description": "`true` if there are more results beyond this page." }, "next_cursor": { "type": [ "null", "string" ], "description": "Opaque cursor string to pass as the `cursor` query parameter on the next request. `null` when there are no more pages." }, "request_id": { "type": [ "null", "string" ], "description": "Unique identifier for the API request." } } }, "PaginatedResponseOfGetTaskResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/GetTaskResponse" }, "description": "Array of resource objects for the current page." }, "has_more": { "type": "boolean", "description": "`true` if there are more results beyond this page." }, "next_cursor": { "type": [ "null", "string" ], "description": "Opaque cursor string to pass as the `cursor` query parameter on the next request. `null` when there are no more pages." }, "request_id": { "type": [ "null", "string" ], "description": "Unique identifier for the API request." } } }, "PaginatedResponseOfListAgentData": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ListAgentData" }, "description": "Array of resource objects for the current page." }, "has_more": { "type": "boolean", "description": "`true` if there are more results beyond this page." }, "next_cursor": { "type": [ "null", "string" ], "description": "Opaque cursor string to pass as the `cursor` query parameter on the next request. `null` when there are no more pages." }, "request_id": { "type": [ "null", "string" ], "description": "Unique identifier for the API request." } } }, "PaginatedResponseOfListCredentialData": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ListCredentialData" }, "description": "Array of resource objects for the current page." }, "has_more": { "type": "boolean", "description": "`true` if there are more results beyond this page." }, "next_cursor": { "type": [ "null", "string" ], "description": "Opaque cursor string to pass as the `cursor` query parameter on the next request. `null` when there are no more pages." }, "request_id": { "type": [ "null", "string" ], "description": "Unique identifier for the API request." } } }, "PaginatedResponseOfListEventData": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ListEventData" }, "description": "Array of resource objects for the current page." }, "has_more": { "type": "boolean", "description": "`true` if there are more results beyond this page." }, "next_cursor": { "type": [ "null", "string" ], "description": "Opaque cursor string to pass as the `cursor` query parameter on the next request. `null` when there are no more pages." }, "request_id": { "type": [ "null", "string" ], "description": "Unique identifier for the API request." } } }, "PaginatedResponseOfListSessionData": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ListSessionData" }, "description": "Array of resource objects for the current page." }, "has_more": { "type": "boolean", "description": "`true` if there are more results beyond this page." }, "next_cursor": { "type": [ "null", "string" ], "description": "Opaque cursor string to pass as the `cursor` query parameter on the next request. `null` when there are no more pages." }, "request_id": { "type": [ "null", "string" ], "description": "Unique identifier for the API request." } } }, "PaginatedResponseOfListSourceResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ListSourceResponse" }, "description": "Array of resource objects for the current page." }, "has_more": { "type": "boolean", "description": "`true` if there are more results beyond this page." }, "next_cursor": { "type": [ "null", "string" ], "description": "Opaque cursor string to pass as the `cursor` query parameter on the next request. `null` when there are no more pages." }, "request_id": { "type": [ "null", "string" ], "description": "Unique identifier for the API request." } } }, "PaginatedResponseOfListStorageItemResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ListStorageItemResponse" }, "description": "Array of storage items. All of the run's files are returned in a single response." }, "has_more": { "type": "boolean", "description": "Always `false`; this endpoint returns all items in one response." }, "request_id": { "type": [ "null", "string" ], "description": "Unique identifier for the API request." } } }, "PaginatedResponseOfListScreenshotItemResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ListScreenshotItemResponse" }, "description": "Array of screenshot items for the current page, oldest first." }, "has_more": { "type": "boolean", "description": "`true` if there are more results beyond this page." }, "next_cursor": { "type": [ "null", "string" ], "description": "Opaque cursor string to pass as the `cursor` query parameter on the next request. `null` when there are no more pages." }, "request_id": { "type": [ "null", "string" ], "description": "Unique identifier for the API request." } } }, "PaginatedResponseOfListTaskRunData": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ListTaskRunData" }, "description": "Array of resource objects for the current page." }, "has_more": { "type": "boolean", "description": "`true` if there are more results beyond this page." }, "next_cursor": { "type": [ "null", "string" ], "description": "Opaque cursor string to pass as the `cursor` query parameter on the next request. `null` when there are no more pages." }, "request_id": { "type": [ "null", "string" ], "description": "Unique identifier for the API request." } } }, "ResetSourceResponse": { "required": [ "id", "object", "name", "type", "website", "created_at", "updated_at", "reset_at", "request_id" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the source, prefixed with `src_`." }, "object": { "type": "string", "description": "Always `source`." }, "name": { "type": [ "null", "string" ], "description": "Display name for the source." }, "type": { "type": "string", "description": "The source type. `website` is currently the only supported type; it defaults to `website` if omitted." }, "website": { "$ref": "#/components/schemas/SourceWebsite", "description": "Website configuration for the source." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the resource was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the resource was last updated." }, "reset_at": { "type": [ "null", "string" ], "format": "date-time", "description": "ISO 8601 timestamp of when the source's antibot analysis was last reset, if ever." }, "request_id": { "type": "string", "description": "Unique identifier for the API request. Include this when contacting support." } }, "description": "The source after a reset request." }, "RunTaskRequest": { "type": "object", "properties": { "credential_id": { "type": [ "null", "string" ], "description": "The credential to authenticate with. Prefixed with `cred_`." }, "source_id": { "type": [ "null", "string" ], "description": "The source to run the task against. Prefixed with `src_`." }, "session_id": { "type": [ "null", "string" ], "description": "An existing session to reuse for this run. Prefixed with `sess_`." }, "input": { "description": "Input data matching the task's `input_schema`." }, "request_id": { "type": [ "null", "string" ], "description": "Client-specified request identifier for tracing." } }, "description": "Request body for running a task." }, "SessionTaskRunData": { "required": [ "id", "task_id", "agent_id", "credential_id" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the task run." }, "task_id": { "type": "string", "description": "ID of the task that was executed." }, "agent_id": { "type": "string", "description": "ID of the agent that executed the run." }, "credential_id": { "type": [ "null", "string" ], "description": "ID of the credential used for authentication, if any." } }, "description": "Lightweight summary of a task run within a session." }, "SourceWebsite": { "required": [ "url" ], "type": "object", "properties": { "url": { "type": "string", "description": "The URL of the website or service. Deck normalizes this on create: it prepends `https://` when no scheme is given, lowercases the scheme and host, drops default ports (80/443), and trims trailing slashes \u2014 so the stored and returned value may differ from what you sent. Non-HTTP(S) URLs are rejected." } }, "description": "Website configuration for a source." }, "SubmitInteractionRequest": { "type": "object", "properties": { "input": { "description": "Field values matching the interaction's field names. Each key corresponds to a field `name` from the interaction object (e.g. `{ \"code\": \"123456\" }`)." } }, "description": "Request body for submitting interaction input to a paused task run." }, "TaskRunArtifactData": { "type": "object", "properties": { "screenshots": { "type": "array", "items": { "$ref": "#/components/schemas/TaskRunScreenshot" }, "description": "Screenshots captured during the run." } }, "description": "Run-level visibility artifacts returned when include=artifacts is requested." }, "TaskRunError": { "required": [ "type", "code", "message" ], "type": "object", "properties": { "type": { "type": "string", "description": "Error category (e.g. `source`, `auth`, `task`, `rate_limit`). Determines the class of failure." }, "code": { "type": "string", "description": "Machine-readable error code. Use this for programmatic handling." }, "message": { "type": "string", "description": "Human-readable explanation. Do not rely on this for logic \u2014 it may change." }, "field": { "type": [ "null", "string" ], "description": "The input field that caused the error, when applicable." } }, "description": "Error details for a failed task run. Same structure as API-level errors." }, "TaskRunScreenshot": { "required": [ "file_name", "file_type", "file_size", "created_at" ], "type": "object", "properties": { "file_name": { "type": "string", "description": "Original file name." }, "file_type": { "type": "string", "description": "MIME type of the screenshot." }, "file_size": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64", "description": "Size of the file in bytes." }, "url": { "type": [ "null", "string" ], "description": "Signed URL to download the screenshot. Time-limited." }, "reasoning": { "type": [ "null", "string" ], "description": "AI reasoning at the time of capture, if recorded." }, "created_at": { "type": "string", "format": "date-time", "description": "When the screenshot was captured." } }, "description": "A single screenshot captured during a task run." }, "TaskRunStorageItem": { "required": [ "id", "object", "file_name", "file_type", "file_size", "purpose", "created_at" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the storage item, prefixed with `stor_`." }, "object": { "type": "string", "description": "Always `storage`." }, "file_name": { "type": "string", "description": "Original file name." }, "file_type": { "type": "string", "description": "MIME type of the file." }, "file_size": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64", "description": "Size of the file in bytes." }, "url": { "type": [ "null", "string" ], "description": "Signed URL to download the file. Time-limited." }, "extraction": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/JsonElement" } ], "description": "Extracted structured data from the file, if any." }, "purpose": { "type": "string", "enum": [ "attachment", "extraction", "output" ], "description": "How the file relates to the run: `attachment` (a file you provided as task input for the agent to use), `extraction` (a file you provided as task input that Deck extracts data from directly, skipping the agent), or `output` (a file the agent captured during the run)." }, "created_at": { "type": "string", "format": "date-time", "description": "When the storage item was created." } }, "description": "A storage item embedded in the task run detail response when include=storage is requested. Includes the signed download URL and any inline extraction." }, "TaskRunDeduplicatedFile": { "required": [ "file_name", "duplicate_of", "task_run_id", "created_at" ], "type": "object", "properties": { "file_name": { "type": "string", "description": "Name of the skipped file as the agent captured it." }, "duplicate_of": { "type": "string", "description": "Storage ID of the surviving item this file matched, prefixed with `stor_`. Fetch `GET /v2/storage/{duplicate_of}` for the original's file name, extraction, and a fresh signed URL. The referenced item is deleted on the normal file retention schedule, after which the ID no longer resolves." }, "task_run_id": { "type": "string", "description": "The task run that originally captured the matched file, prefixed with `trun_`. This is the earlier capture run, not the run this entry appears on." }, "created_at": { "type": "string", "format": "date-time", "description": "When the file was skipped." } }, "description": "A file skipped by deduplication, embedded in the task run detail response when include=storage_deduplicated is requested and the task has deduplication enabled. Entries are inline values, not addressable resources: no id, no object type, and no query endpoint." }, "TaskSummary": { "required": [ "id", "object", "name", "status" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the task, prefixed with `task_`." }, "object": { "type": "string", "description": "Resource type string (`task`)." }, "name": { "type": "string", "description": "Display name for the task." }, "status": { "type": "string", "description": "Current task status: `learning`, `test`, or `live`." } }, "description": "Lightweight summary of a task, included in agent responses." }, "UpdateAgentRequest": { "type": "object", "properties": { "name": { "type": [ "null", "string" ], "description": "Updated display name." }, "description": { "type": [ "null", "string" ], "description": "Updated description." } }, "description": "Request body for updating an agent. Only include fields you want to change." }, "UpdateCredentialRequest": { "type": "object", "properties": { "auth_credentials": { "$ref": "#/components/schemas/AuthCredentialsInput" }, "external_id": { "type": [ "null", "string" ], "description": "Updated external identifier. Set to `null` to remove the mapping." }, "persistence": { "$ref": "#/components/schemas/PersistenceInput", "description": "Updated persistence settings. Setting `enabled` to `false` permanently deletes the saved login state." } }, "description": "Request body for updating a credential. Only include fields you want to change." }, "UpdateCredentialResponse": { "required": [ "id", "object", "status", "source_id", "auth_method", "auth_credentials", "persistence", "external_id", "created_at", "updated_at", "request_id" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the credential, prefixed with `cred_`." }, "object": { "type": "string", "description": "Always `credential`." }, "status": { "type": "string", "description": "Credential status: `unverified`, `verified`, `invalid`, or `deleted`." }, "source_id": { "type": "string", "description": "The source this credential authenticates against. Prefixed with `src_`." }, "auth_method": { "type": "string", "description": "Authentication method: `username_password`, `source_fields`, or `none`." }, "auth_credentials": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AuthCredentialsSummary" } ], "description": "Summary of stored credentials. Sensitive values are not returned." }, "persistence": { "$ref": "#/components/schemas/PersistenceSummary", "description": "Persistence settings for this credential." }, "external_id": { "type": [ "null", "string" ], "description": "External identifier from your system, if set." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the resource was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the resource was last updated." }, "request_id": { "type": "string", "description": "Unique identifier for the API request. Include this when contacting support." } } }, "UpdateEventDestinationRequest": { "type": "object", "properties": { "name": { "type": [ "null", "string" ], "description": "Updated display name." }, "status": { "type": [ "null", "string" ], "description": "Updated status: `active` or `inactive`." }, "events": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Updated list of subscribed event types (for example `task_run.completed`, `credential.verified`). Use `[\"*\"]` to subscribe to all event types; `*` cannot be combined with specific types, and the list must not be empty." }, "webhook": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "Absolute `https` or `http` URL that receives event deliveries." }, "secret": { "type": "string", "description": "Signing secret used to verify webhook signatures. Write-only; never returned." } }, "description": "Configuration for a `webhook` destination. Provide this object under the `webhook` property when `type` is `webhook`." }, "aws_sqs": { "type": "object", "required": [ "queue_url" ], "properties": { "queue_url": { "type": "string", "description": "URL of the destination Amazon SQS queue." }, "key": { "type": "string", "description": "AWS access key ID. Accepted alias: `access_key`. Write-only." }, "secret": { "type": "string", "description": "AWS secret access key. Accepted alias: `secret_key`. Write-only." } }, "description": "Configuration for a `aws_sqs` destination. Provide this object under the `aws_sqs` property when `type` is `aws_sqs`." }, "aws_kinesis": { "type": "object", "required": [ "stream_name", "region" ], "properties": { "stream_name": { "type": "string", "description": "Name of the Amazon Kinesis stream." }, "region": { "type": "string", "description": "AWS region of the stream." }, "key": { "type": "string", "description": "AWS access key ID. Accepted alias: `access_key`. Write-only." }, "secret": { "type": "string", "description": "AWS secret access key. Accepted alias: `secret_key`. Write-only." } }, "description": "Configuration for a `aws_kinesis` destination. Provide this object under the `aws_kinesis` property when `type` is `aws_kinesis`." }, "aws_s3": { "type": "object", "required": [ "bucket", "region" ], "properties": { "bucket": { "type": "string", "description": "Name of the destination Amazon S3 bucket." }, "region": { "type": "string", "description": "AWS region of the bucket." }, "key": { "type": "string", "description": "AWS access key ID. Accepted alias: `access_key`. Write-only." }, "secret": { "type": "string", "description": "AWS secret access key. Accepted alias: `secret_key`. Write-only." } }, "description": "Configuration for a `aws_s3` destination. Provide this object under the `aws_s3` property when `type` is `aws_s3`." }, "aws_eventbridge": { "type": "object", "required": [ "event_bus_name", "region" ], "properties": { "event_bus_name": { "type": "string", "description": "Name of the Amazon EventBridge event bus." }, "region": { "type": "string", "description": "AWS region of the event bus." }, "access_key_id": { "type": "string", "description": "AWS access key ID. Write-only." }, "secret_access_key": { "type": "string", "description": "AWS secret access key. Write-only." } }, "description": "Configuration for a `aws_eventbridge` destination. Provide this object under the `aws_eventbridge` property when `type` is `aws_eventbridge`." }, "gcp_pubsub": { "type": "object", "required": [ "project_id", "topic" ], "properties": { "project_id": { "type": "string", "description": "Google Cloud project ID." }, "topic": { "type": "string", "description": "Pub/Sub topic name. Accepted alias: `topic_name`." }, "service_account_json": { "type": "string", "description": "Service account credentials JSON. Accepted alias: `credentials_json`. Write-only." } }, "description": "Configuration for a `gcp_pubsub` destination. Provide this object under the `gcp_pubsub` property when `type` is `gcp_pubsub`." }, "rabbitmq": { "type": "object", "required": [ "exchange", "server_url" ], "properties": { "exchange": { "type": "string", "description": "Name of the RabbitMQ exchange." }, "server_url": { "type": "string", "description": "RabbitMQ host as `host[:port]` (for example `rabbitmq:5672`). You may instead pass a full AMQP URL with embedded credentials; Deck extracts the host, username, and password from it." }, "username": { "type": "string", "description": "RabbitMQ username (or embed it in the AMQP `server_url`). Write-only." }, "password": { "type": "string", "description": "RabbitMQ password (or embed it in the AMQP `server_url`). Write-only." } }, "description": "Configuration for a `rabbitmq` destination. Provide this object under the `rabbitmq` property when `type` is `rabbitmq`." }, "azure_servicebus": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Name of the Service Bus queue or topic. Accepted alias: `queue_name`." }, "connection_string": { "type": "string", "description": "Azure Service Bus connection string. Write-only." } }, "description": "Configuration for a `azure_servicebus` destination. Provide this object under the `azure_servicebus` property when `type` is `azure_servicebus`." }, "hookdeck": { "type": "object", "properties": { "token": { "type": "string", "description": "Hookdeck API key. Accepted alias: `api_key`. Write-only." } }, "description": "Configuration for a `hookdeck` destination. Provide this object under the `hookdeck` property when `type` is `hookdeck`." } }, "description": "Request body for updating an event destination. Only include fields you want to change. To change endpoint configuration or credentials, include the configuration object whose property name matches the destination's existing `type`." }, "UpdateSourceRequest": { "type": "object", "properties": { "name": { "type": [ "null", "string" ], "description": "Updated display name." }, "url": { "type": [ "null", "string" ], "description": "Updated website URL." } }, "description": "Request body for updating a source. Only include fields you want to change." }, "UpdateSourceResponse": { "required": [ "id", "object", "name", "type", "website", "created_at", "updated_at", "request_id" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the source, prefixed with `src_`." }, "object": { "type": "string", "description": "Always `source`." }, "name": { "type": [ "null", "string" ], "description": "Display name for the source." }, "type": { "type": "string", "description": "The source type. `website` is currently the only supported type; it defaults to `website` if omitted." }, "website": { "$ref": "#/components/schemas/SourceWebsite", "description": "Website configuration for the source." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the resource was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the resource was last updated." }, "request_id": { "type": "string", "description": "Unique identifier for the API request. Include this when contacting support." } }, "description": "A source object. Sources are websites or services that agents connect to." }, "UpdateTaskRequest": { "type": "object", "properties": { "name": { "type": [ "null", "string" ], "description": "Updated display name." }, "input_schema": { "description": "Updated JSON Schema for task run input." }, "output_schema": { "description": "Updated JSON Schema for task run output." }, "prompt": { "type": [ "null", "string" ], "description": "Updated agent instructions." }, "storage": { "description": "Updated storage configuration." }, "settings": { "type": "object", "properties": { "timeout_seconds": { "type": "integer", "minimum": 1, "description": "Maximum wall-clock time, in seconds, that a single run of this task may execute before Deck stops it and the run fails with a `timeout` error. Must be a positive integer. The maximum you can set is determined by your plan (see https://deck.co/pricing); the overall ceiling is 28800 seconds (8 hours). If omitted, the task uses your plan's default timeout. A value above your plan's maximum is rejected when the task is updated with a `422` `timeout_exceeds_plan_max` error." }, "sensitive": { "type": "boolean", "description": "Marks the task as sensitive. When `true`, the Console hides the live browser view, agent reasoning, and screenshots for this task's runs. Must be a boolean; any other value is rejected with a `422` `invalid_field_value` error." } }, "description": "Task-level settings. Supports `timeout_seconds` and `sensitive`. When included, `settings` replaces the task's settings as a whole, so send every key you want to keep." } }, "description": "Request body for updating a task. Only include fields you want to change." }, "UpdateTaskResponse": { "required": [ "id", "object", "name", "prompt", "status", "agent_id", "input_schema", "output_schema", "storage", "settings", "created_at", "updated_at", "request_id" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the task, prefixed with `task_`." }, "object": { "type": "string", "description": "Always `task`." }, "name": { "type": "string", "description": "Display name for the task." }, "prompt": { "type": [ "null", "string" ], "description": "Instructions for the agent describing what this task should do." }, "status": { "type": "string", "description": "Task status: `learning`, `test`, or `live`." }, "agent_id": { "type": "string", "description": "The agent this task belongs to. Prefixed with `agt_`." }, "input_schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/JsonElement" } ], "description": "JSON Schema defining the expected input for task runs." }, "output_schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/JsonElement" } ], "description": "JSON Schema defining the expected output for task runs." }, "storage": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/JsonElement" } ], "description": "Storage configuration for file capture during task execution." }, "settings": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/JsonElement" } ], "description": "Task-level settings. Supports `timeout_seconds` (the per-run timeout, in seconds) and `sensitive` (when `true`, the Console hides the live browser view, agent reasoning, and screenshots for this task's runs). `null` when no settings were set on the task, in which case runs use your plan's default timeout and the task is not sensitive." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the resource was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the resource was last updated." }, "request_id": { "type": "string", "description": "Unique identifier for the API request. Include this when contacting support." } }, "description": "A task object. Tasks are defined actions an agent can perform." }, "TestResponse": { "required": [ "status", "environment", "request_id" ], "type": "object", "properties": { "status": { "type": "string", "description": "Always \"ready\"." }, "environment": { "type": "string", "description": "Always \"live\"." }, "request_id": { "type": "string", "description": "Unique identifier for this request, useful for tracing." } }, "description": "Response from the API health check endpoint." }, "ValidationErrorResponse": { "required": [ "errors" ], "type": "object", "properties": { "type": { "type": [ "null", "string" ], "description": "RFC 9110 problem type URI." }, "title": { "type": [ "null", "string" ], "description": "Short summary of the validation failure." }, "status": { "type": [ "null", "integer" ], "description": "HTTP status code.", "format": "int32" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Validation errors grouped by field name." }, "traceId": { "type": [ "null", "string" ], "description": "Request trace identifier." } }, "description": "Validation error returned for malformed requests (HTTP 400)." }, "ErrorResponse": { "required": [ "errors", "request_id" ], "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/TaskRunError" }, "description": "One or more errors that describe what went wrong." }, "request_id": { "type": "string", "description": "Unique identifier for this request, useful for tracing." } }, "description": "Standard error response." }, "TriggerCondition": { "required": [ "type", "cron", "timezone" ], "type": "object", "properties": { "type": { "type": "string", "description": "The condition type. Always `schedule`." }, "cron": { "type": "string", "description": "Standard 5-field cron expression: minute, hour, day of month, month, day of week." }, "timezone": { "type": "string", "description": "IANA timezone name the schedule is evaluated in (e.g. `America/New_York`). Day boundaries and DST shifts follow local time." } }, "description": "When the trigger fires: a cron expression evaluated in a timezone." }, "TriggerCredentialFilter": { "required": [ "source_ids", "status" ], "type": "object", "properties": { "source_ids": { "type": "array", "items": { "type": "string" }, "description": "Match credentials on any of these sources. IDs prefixed with `src_`. Pass `[\"*\"]` to match every source in the organization; the wildcard must be the only entry." }, "status": { "type": "array", "items": { "type": "string" }, "description": "Allowlist of credential statuses to fan out to, typically `unverified` and `verified`. There is no default, and an empty list is rejected. `invalid` / `deleted` credentials never match." } }, "description": "A scope of credentials, resolved each time the trigger fires." }, "TriggerSkipLastRun": { "required": [ "result", "within_seconds" ], "type": "object", "properties": { "result": { "type": "string", "description": "Task run result to match: `success`, `failure`, or `unknown`." }, "within_seconds": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64", "description": "Time window in seconds, measured back from the fire time." } }, "description": "Skips a credential when its most recent completed run of the trigger's task finished with `result` within `within_seconds`." }, "TriggerSkipIf": { "required": [ "last_run" ], "type": "object", "properties": { "last_run": { "$ref": "#/components/schemas/TriggerSkipLastRun" } }, "description": "Skip condition evaluated per credential before a run is created. When met, the credential is skipped for that fire and no run is created." }, "TriggerResponse": { "required": [ "id", "object", "name", "description", "status", "condition", "task_id", "credential_ids", "credential_filter", "input", "skip_if", "concurrency_max", "created_at", "updated_at", "request_id" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the trigger, prefixed with `trg_`." }, "object": { "type": "string", "description": "Always `trigger`." }, "name": { "type": "string", "description": "Display name for the trigger." }, "description": { "type": [ "null", "string" ], "description": "Description of the trigger's purpose." }, "status": { "type": "string", "description": "`active` or `inactive`. Inactive triggers keep their configuration and fire nothing." }, "condition": { "$ref": "#/components/schemas/TriggerCondition" }, "task_id": { "type": "string", "description": "The task this trigger runs. Prefixed with `task_`. Fixed at creation." }, "credential_ids": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Explicit credentials the trigger targets. `null` when the trigger uses `credential_filter`." }, "credential_filter": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TriggerCredentialFilter" } ], "description": "Credential scope the trigger fans out across. `null` when the trigger uses `credential_ids`." }, "input": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/JsonElement" } ], "description": "Input passed to every run this trigger creates, matching the task's `input_schema`." }, "skip_if": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TriggerSkipIf" } ], "description": "Skip condition evaluated per credential before a run is created." }, "concurrency_max": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32", "description": "Maximum simultaneous runs from this trigger. `null` means no per-trigger cap." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the resource was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the resource was last updated." }, "request_id": { "type": "string", "description": "Unique identifier for the API request. Include this when contacting support." } }, "description": "A trigger object. Triggers create task runs on a schedule across a set of credentials." }, "ListTriggerData": { "required": [ "id", "object", "name", "description", "status", "condition", "task_id", "credential_ids", "credential_filter", "input", "skip_if", "concurrency_max", "created_at", "updated_at" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the trigger, prefixed with `trg_`." }, "object": { "type": "string", "description": "Always `trigger`." }, "name": { "type": "string", "description": "Display name for the trigger." }, "description": { "type": [ "null", "string" ], "description": "Description of the trigger's purpose." }, "status": { "type": "string", "description": "`active` or `inactive`. Inactive triggers keep their configuration and fire nothing." }, "condition": { "$ref": "#/components/schemas/TriggerCondition" }, "task_id": { "type": "string", "description": "The task this trigger runs. Prefixed with `task_`. Fixed at creation." }, "credential_ids": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Explicit credentials the trigger targets. `null` when the trigger uses `credential_filter`." }, "credential_filter": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TriggerCredentialFilter" } ], "description": "Credential scope the trigger fans out across. `null` when the trigger uses `credential_ids`." }, "input": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/JsonElement" } ], "description": "Input passed to every run this trigger creates, matching the task's `input_schema`." }, "skip_if": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TriggerSkipIf" } ], "description": "Skip condition evaluated per credential before a run is created." }, "concurrency_max": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32", "description": "Maximum simultaneous runs from this trigger. `null` means no per-trigger cap." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the resource was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the resource was last updated." } }, "description": "A trigger object. Triggers create task runs on a schedule across a set of credentials." }, "CreateTriggerRequest": { "required": [ "name", "condition", "task_id" ], "type": "object", "properties": { "name": { "type": "string", "description": "Display name for the trigger." }, "description": { "type": [ "null", "string" ], "description": "Description of the trigger's purpose." }, "condition": { "$ref": "#/components/schemas/TriggerCondition" }, "task_id": { "type": "string", "description": "The task to run. Prefixed with `task_`. Cannot be changed after creation." }, "credential_ids": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Explicit credentials to target, one or many. Pass exactly one of `credential_ids` / `credential_filter`." }, "credential_filter": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TriggerCredentialFilter" } ], "description": "A scope of credentials to fan out across, resolved each time the trigger fires. Pass exactly one of `credential_ids` / `credential_filter`." }, "input": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/JsonElement" } ], "description": "Input passed to every run this trigger creates, validated against the task's `input_schema`." }, "skip_if": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TriggerSkipIf" } ], "description": "Skip condition evaluated per credential before a run is created." }, "concurrency_max": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32", "description": "Maximum simultaneous runs from this trigger. Omit for no per-trigger cap." } }, "description": "Creates a trigger. The trigger is created with `status: \"active\"` and fires on its schedule immediately." }, "UpdateTriggerRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name for the trigger." }, "description": { "type": [ "null", "string" ], "description": "Description of the trigger's purpose. `null` clears it." }, "status": { "type": "string", "description": "`active` or `inactive`. Setting this is how you pause and resume a trigger." }, "condition": { "$ref": "#/components/schemas/TriggerCondition" }, "credential_ids": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Explicit credentials to target. Replaces the existing list wholesale." }, "credential_filter": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TriggerCredentialFilter" } ], "description": "A scope of credentials to fan out across." }, "input": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/JsonElement" } ], "description": "Input passed to every run this trigger creates, validated against the task's `input_schema`." }, "skip_if": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TriggerSkipIf" } ], "description": "Skip condition evaluated per credential. `null` clears it." }, "concurrency_max": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32", "description": "Maximum simultaneous runs from this trigger. `null` removes the cap." } }, "description": "All fields are optional; omitted fields are left unchanged. The trigger's target task cannot be changed." }, "DeleteTriggerResponse": { "required": [ "id", "object", "deleted", "request_id" ], "type": "object", "properties": { "id": { "type": "string", "description": "ID of the deleted trigger." }, "object": { "type": "string", "description": "Always `trigger`." }, "deleted": { "type": "boolean", "description": "Always `true` for successful deletions." }, "request_id": { "type": "string", "description": "Unique identifier for the API request. Include this when contacting support." } }, "description": "Confirmation object returned after a successful deletion." }, "PaginatedResponseOfListTriggerData": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ListTriggerData" }, "description": "Array of resource objects for the current page." }, "has_more": { "type": "boolean", "description": "`true` if there are more results beyond this page." }, "next_cursor": { "type": [ "null", "string" ], "description": "Opaque cursor string to pass as the `cursor` query parameter on the next request. `null` when there are no more pages." }, "request_id": { "type": [ "null", "string" ], "description": "Unique identifier for the API request." } } } }, "securitySchemes": { "BearerAuth": { "type": "http", "description": "Secret key (sk_live_...)", "scheme": "bearer", "bearerFormat": "JWT" } }, "headers": { "RateLimit": { "description": "IETF RateLimit header (draft-ietf-httpapi-ratelimit-headers). Example: `limit=200, remaining=180, reset=8`.", "schema": { "type": "string" }, "example": "limit=200, remaining=180, reset=8" }, "RateLimitPolicy": { "description": "IETF RateLimit-Policy quota window. Default policy is 200 requests per 10 seconds per organization.", "schema": { "type": "string" }, "example": "200;w=10" }, "RetryAfter": { "description": "Seconds to wait before retrying a 429.", "schema": { "type": "integer" }, "example": 10 } }, "responses": { "Error": { "description": "JSON error. Typed `errors[]` with machine-readable `type`/`code` plus `request_id`.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "RateLimited": { "description": "Too many requests or session concurrency exceeded. Retry with backoff; honor Retry-After and RateLimit headers when present.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "type": "rate_limit", "code": "rate_limit_exceeded", "message": "Too many requests." } ], "request_id": "req_a1b2c3d4" } } } } } }, "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "Agents" }, { "name": "Components" }, { "name": "Credentials" }, { "name": "Event Destinations" }, { "name": "Events" }, { "name": "Sessions" }, { "name": "Sources" }, { "name": "Storage" }, { "name": "Task Runs" }, { "name": "Tasks" }, { "name": "Test" }, { "name": "Triggers" } ], "externalDocs": { "description": "Deck API documentation, errors, versioning, and rate limits", "url": "https://docs.deck.co/api/using-the-api" } }