{ "components": { "headers": { "Deprecation": { "description": "Present when the operation is deprecated.", "schema": { "type": "string" } }, "IdempotentReplayed": { "description": "`true` when this is the stored answer to an earlier request with the same `Idempotency-Key`.", "schema": { "const": "true" } }, "RequestId": { "description": "The id of this request, `req_` and a ULID. Quote it when you ask for help.", "schema": { "pattern": "^req_[0-9A-HJKMNP-TV-Z]{26}$", "type": "string" } }, "RetryAfter": { "description": "Seconds to wait before the next request; sent with 429.", "schema": { "minimum": 1, "type": "integer" } }, "Sunset": { "description": "When a deprecated operation stops working, if a date is set.", "schema": { "type": "string" } } }, "responses": { "Error": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "The error envelope. `error.type` and `error.code` say what went wrong. The status is one of 400, 401, 403, 404, 409, 422 or 429; `Retry-After` comes with 429 only.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } }, "schemas": { "ApprovalDecision": { "additionalProperties": false, "properties": { "decision": { "enum": [ "allow", "deny" ], "type": "string" }, "note": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ] } }, "required": [ "decision" ], "type": "object" }, "Approvals": { "additionalProperties": false, "properties": { "mode": { "default": "deny", "enum": [ "deny", "ask" ], "type": "string" } }, "type": "object" }, "Budget": { "additionalProperties": false, "properties": { "max_cost_usd": { "anyOf": [ { "exclusiveMinimum": 0.0, "type": "number" }, { "type": "string" } ] } }, "required": [ "max_cost_usd" ], "type": "object" }, "BundleVersionCreate": { "additionalProperties": false, "properties": { "spec": { "additionalProperties": true, "type": "object" }, "version": { "type": "string" } }, "required": [ "version", "spec" ], "type": "object" }, "Collect": { "additionalProperties": false, "properties": { "workspace_diff": { "default": false, "type": "boolean" } }, "type": "object" }, "CredentialPut": { "additionalProperties": false, "properties": { "api_key": { "format": "password", "minLength": 1, "type": "string", "writeOnly": true }, "type": { "type": "string" } }, "required": [ "type", "api_key" ], "type": "object" }, "CredentialRefreshPut": { "additionalProperties": false, "properties": { "url": { "type": "string" } }, "required": [ "url" ], "type": "object" }, "CredentialRefreshRequest": { "additionalProperties": false, "properties": { "expires_at": { "description": "When the secret's current value expires.", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$", "type": "string" }, "run": { "additionalProperties": false, "properties": { "id": { "pattern": "^run_[0-9A-HJKMNP-TV-Z]{26}$", "type": "string" }, "metadata": { "additionalProperties": true, "type": "object" } }, "required": [ "id", "metadata" ], "type": "object" }, "secret": { "description": "The name of the run secret to refresh.", "type": "string" }, "type": { "const": "credential.refresh" }, "workspace": { "additionalProperties": false, "properties": { "external_id": { "type": [ "string", "null" ] }, "id": { "pattern": "^ws_[0-9A-HJKMNP-TV-Z]{26}$", "type": "string" } }, "required": [ "id", "external_id" ], "type": "object" } }, "required": [ "type", "run", "workspace", "secret", "expires_at" ], "type": "object" }, "CredentialRefreshResponse": { "properties": { "expires_at": { "description": "When the new value expires.", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$", "type": "string" }, "value": { "description": "The new value of the secret.", "type": "string" } }, "required": [ "value", "expires_at" ], "type": "object" }, "ErrorEnvelope": { "additionalProperties": false, "properties": { "error": { "additionalProperties": false, "properties": { "code": { "description": "What went wrong, for a program to act on.", "enum": [ "approval_not_pending", "approval_required", "bundle_version_exists", "bundle_version_unavailable", "credential_invalid", "credential_missing", "idempotency_conflict", "idempotency_key_required", "internal", "invalid_api_key", "malformed_json", "missing_scope", "not_found", "quota_exceeded", "rate_limited", "repo_host_unsupported", "repo_policy_ack_required", "run_not_active", "suspended", "tier_limit", "turn_not_cancellable", "unavailable", "unsupported_credential_type", "unsupported_version", "validation_failed" ] }, "details": { "additionalProperties": true, "description": "Machine-readable extras, such as `required_scope`, `quota`, `field` and `max`, or `errors`, a list of `{path, message}`.", "type": "object" }, "message": { "description": "A sentence for a person; its wording may change.", "type": "string" }, "param": { "description": "The request field or header at fault, if one is.", "type": "string" }, "request_id": { "description": "The `Request-Id` of the response; quote it when you ask for help.", "pattern": "^req_[0-9A-HJKMNP-TV-Z]{26}$", "type": "string" }, "type": { "description": "The class of the error.", "enum": [ "api_error", "authentication", "conflict", "invalid_request", "not_found", "permission", "rate_limit" ] } }, "required": [ "type", "code", "message", "request_id" ], "type": "object" } }, "required": [ "error" ], "type": "object" }, "EventData.approval.requested": { "additionalProperties": false, "description": "The agent asks to use a tool and the run's approvals mode is ask.", "properties": { "approval_id": { "pattern": "^apr_[0-9A-HJKMNP-TV-Z]{26}$", "type": "string" }, "expires_at": { "description": "When the request lapses unanswered.", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$", "type": "string" }, "input_summary": { "description": "At most 16 KiB. Run secrets are redacted.", "type": "string" }, "tool": { "type": "string" } }, "required": [ "approval_id", "tool", "input_summary", "expires_at" ], "title": "approval.requested", "type": "object" }, "EventData.approval.resolved": { "additionalProperties": false, "description": "An approval was decided, or lapsed.", "properties": { "approval_id": { "pattern": "^apr_[0-9A-HJKMNP-TV-Z]{26}$", "type": "string" }, "decision": { "enum": [ "allow", "deny" ] }, "note": { "type": [ "string", "null" ] }, "reason": { "enum": [ "decided", "expired" ] } }, "required": [ "approval_id", "decision", "reason", "note" ], "title": "approval.resolved", "type": "object" }, "EventData.budget.warning": { "additionalProperties": false, "description": "A run has spent 80% of its budget.", "properties": { "max_cost_usd": { "minimum": 0, "type": "number" }, "spent_usd": { "minimum": 0, "type": "number" }, "threshold": { "const": 0.8 } }, "required": [ "max_cost_usd", "spent_usd", "threshold" ], "title": "budget.warning", "type": "object" }, "EventData.bundle.version_ready": { "additionalProperties": false, "description": "A bundle version passed validation and can be used.", "properties": { "bundle": { "type": "string" }, "version": { "type": "string" } }, "required": [ "bundle", "version" ], "title": "bundle.version_ready", "type": "object" }, "EventData.bundle.version_rejected": { "additionalProperties": false, "description": "A bundle version failed validation.", "properties": { "bundle": { "type": "string" }, "errors": { "items": { "additionalProperties": false, "properties": { "message": { "type": "string" }, "path": { "type": "string" } }, "required": [ "path", "message" ], "type": "object" }, "type": "array" }, "version": { "type": "string" } }, "required": [ "bundle", "version", "errors" ], "title": "bundle.version_rejected", "type": "object" }, "EventData.message.completed": { "additionalProperties": false, "description": "The agent wrote a whole block of text. Opt-in.", "properties": { "text": { "description": "Run secrets are redacted.", "type": "string" } }, "required": [ "text" ], "title": "message.completed", "type": "object" }, "EventData.output.created": { "additionalProperties": false, "description": "A run wrote a new version of an output file.", "properties": { "file": { "$ref": "#/components/schemas/File" } }, "required": [ "file" ], "title": "output.created", "type": "object" }, "EventData.ping": { "additionalProperties": false, "description": "A test delivery to one webhook endpoint.", "properties": {}, "required": [], "title": "ping", "type": "object" }, "EventData.run.cancelled": { "additionalProperties": false, "description": "The run was cancelled.", "properties": {}, "required": [], "title": "run.cancelled", "type": "object" }, "EventData.run.completed": { "additionalProperties": false, "description": "The run ended normally.", "properties": { "pushed_refs": { "items": { "$ref": "#/components/schemas/PushedRef" }, "type": "array" }, "usage_total": { "$ref": "#/components/schemas/Usage" } }, "required": [ "usage_total", "pushed_refs" ], "title": "run.completed", "type": "object" }, "EventData.run.expired": { "additionalProperties": false, "description": "The run reached the end of its lifetime, or its capacity was taken.", "properties": { "reason": { "enum": [ "lifetime", "capacity_evicted" ] } }, "required": [ "reason" ], "title": "run.expired", "type": "object" }, "EventData.run.failed": { "additionalProperties": false, "description": "The run ended in failure.", "properties": { "code": { "enum": [ "capacity_unavailable", "image_unavailable", "infrastructure", "credential_missing", "repo_policy_unmet", "repo_auth_failed", "repo_not_found", "ref_not_found", "clone_failed", "bootstrap_failed", "events_lost", "sandbox_protocol_violation" ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "title": "run.failed", "type": "object" }, "EventData.run.idle": { "additionalProperties": false, "description": "The run finished a turn and waits for the next. Not emitted for a run created without an initial turn.", "properties": { "stop_reason": { "enum": [ "end_turn", "budget_reached" ] } }, "required": [ "stop_reason" ], "title": "run.idle", "type": "object" }, "EventData.run.provisioning": { "additionalProperties": false, "description": "A container is being made for the run.", "properties": {}, "required": [], "title": "run.provisioning", "type": "object" }, "EventData.run.queued": { "additionalProperties": false, "description": "The run waits for a slot.", "properties": { "position": { "description": "Its place in the app's queue.", "minimum": 0, "type": "integer" } }, "required": [ "position" ], "title": "run.queued", "type": "object" }, "EventData.run.ready": { "additionalProperties": false, "description": "The run's container is up and its repository is cloned.", "properties": { "image_digest": { "description": "The run image the run started on.", "type": "string" }, "resources": { "items": { "additionalProperties": false, "properties": { "branch": { "description": "The branch the run works on.", "type": "string" }, "branch_created": { "type": "boolean" }, "default_branch": { "type": "string" }, "head_sha": { "description": "The head of that branch at clone time.", "pattern": "^[0-9a-f]{40}$", "type": "string" }, "path": { "description": "Where the repository is, relative to the run root.", "type": "string" }, "repo_policy_check": { "enum": [ "passed", "failed_allowed" ] }, "type": { "const": "git_repository" } }, "required": [ "type", "path", "default_branch", "branch", "head_sha", "branch_created", "repo_policy_check" ], "type": "object" }, "type": "array" } }, "required": [ "image_digest", "resources" ], "title": "run.ready", "type": "object" }, "EventData.run.resumed": { "additionalProperties": false, "description": "A suspended run is running again.", "properties": {}, "required": [], "title": "run.resumed", "type": "object" }, "EventData.run.running": { "additionalProperties": false, "description": "A turn was forwarded to a ready or idle run.", "properties": {}, "required": [], "title": "run.running", "type": "object" }, "EventData.run.suspended": { "additionalProperties": false, "description": "The run's container was suspended; its disk is kept.", "properties": {}, "required": [], "title": "run.suspended", "type": "object" }, "EventData.secret.refresh_failed": { "additionalProperties": false, "description": "A refreshable run secret could not be refreshed before it expired.", "properties": { "expires_at": { "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$", "type": "string" }, "name": { "pattern": "^[A-Z_][A-Z0-9_]{0,63}$", "type": "string" } }, "required": [ "name", "expires_at" ], "title": "secret.refresh_failed", "type": "object" }, "EventData.tool.completed": { "additionalProperties": false, "description": "A tool call returned. Opt-in.", "properties": { "call_index": { "description": "1-based within the turn; pairs tool.started with tool.completed.", "minimum": 1, "type": "integer" }, "duration_ms": { "minimum": 0, "type": "integer" }, "is_error": { "type": "boolean" }, "name": { "type": "string" }, "summary": { "description": "At most 16 KiB. Run secrets are redacted.", "type": "string" } }, "required": [ "call_index", "name", "is_error", "summary", "duration_ms" ], "title": "tool.completed", "type": "object" }, "EventData.tool.started": { "additionalProperties": false, "description": "The agent called a tool. Opt-in.", "properties": { "call_index": { "description": "1-based within the turn; pairs tool.started with tool.completed.", "minimum": 1, "type": "integer" }, "input_summary": { "description": "At most 16 KiB. Run secrets are redacted.", "type": "string" }, "name": { "type": "string" } }, "required": [ "call_index", "name", "input_summary" ], "title": "tool.started", "type": "object" }, "EventData.turn.cancelled": { "additionalProperties": false, "description": "A turn was cancelled. Source platform for a turn cancelled before it was forwarded.", "properties": { "duration_ms": { "minimum": 0, "type": [ "integer", "null" ] }, "usage": { "anyOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Usage" } ] } }, "required": [ "usage", "duration_ms" ], "title": "turn.cancelled", "type": "object" }, "EventData.turn.completed": { "additionalProperties": false, "description": "A turn ended with an answer. The sandbox reports status, stop_reason, output, result, result_error, usage and duration_ms; the API fills turn_id, idempotency_key and metadata and re-validates result against the turn's output_schema. Source platform only for a turn that reached the front of the queue with no budget left.", "properties": { "duration_ms": { "minimum": 0, "type": "integer" }, "idempotency_key": { "description": "The Idempotency-Key the turn was posted with.", "type": [ "string", "null" ] }, "metadata": { "additionalProperties": true, "description": "The turn's metadata, echoed as the app sent it.", "type": "object" }, "output": { "additionalProperties": false, "properties": { "text": { "description": "The agent's final text.", "type": "string" } }, "required": [ "text" ], "type": "object" }, "result": { "description": "The value the agent submitted for the turn's output_schema; any JSON value, null when none was submitted." }, "result_error": { "description": "Why result is null although the turn had an output_schema.", "enum": [ null, "not_submitted", "invalid" ] }, "status": { "const": "completed" }, "stop_reason": { "enum": [ "end_turn", "budget_reached" ] }, "turn_id": { "pattern": "^trn_[0-9A-HJKMNP-TV-Z]{26}$", "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } }, "required": [ "turn_id", "idempotency_key", "status", "stop_reason", "output", "result", "result_error", "usage", "metadata", "duration_ms" ], "title": "turn.completed", "type": "object" }, "EventData.turn.failed": { "additionalProperties": false, "description": "A turn ended in failure.", "properties": { "duration_ms": { "minimum": 0, "type": [ "integer", "null" ] }, "error": { "additionalProperties": false, "properties": { "code": { "enum": [ "timeout", "model_auth", "model_billing", "model_error", "capacity_unavailable", "repo_policy_unmet", "internal" ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "usage": { "anyOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Usage" } ] } }, "required": [ "error", "usage", "duration_ms" ], "title": "turn.failed", "type": "object" }, "EventData.turn.interrupted": { "additionalProperties": false, "description": "A turn was lost with its container, or found unfinished when the sandbox restarted.", "properties": {}, "required": [], "title": "turn.interrupted", "type": "object" }, "EventData.turn.queued": { "additionalProperties": false, "description": "A turn waits because it could not be forwarded when it reached the front. Never for an initial turn waiting for run.ready.", "properties": { "reason": { "enum": [ "busy", "resuming", "capacity", null ] } }, "required": [ "reason" ], "title": "turn.queued", "type": "object" }, "EventData.turn.started": { "additionalProperties": false, "description": "The agent began a turn.", "properties": {}, "required": [], "title": "turn.started", "type": "object" }, "EventData.workspace.credential_invalid": { "additionalProperties": false, "description": "A workspace's model credential failed re-validation.", "properties": { "checked_at": { "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$", "type": "string" }, "type": { "const": "anthropic_api_key" } }, "required": [ "type", "checked_at" ], "title": "workspace.credential_invalid", "type": "object" }, "EventEnvelope": { "additionalProperties": false, "description": "What every event, webhook body and stream record looks like around its type's data.", "properties": { "api_version": { "const": "2026-11-01" }, "created_at": { "description": "When the API ingested the event, never the sandbox's clock.", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$", "type": "string" }, "data": { "additionalProperties": true, "description": "The payload; its schema is events/.json.", "type": "object" }, "id": { "pattern": "^evt_[0-9A-HJKMNP-TV-Z]{26}$", "type": "string" }, "metadata": { "additionalProperties": true, "description": "Present only when turn_id is set: the turn's metadata, echoed as the app sent it.", "type": "object" }, "repo_policy": { "description": "Present only on runs that set it.", "enum": [ "require_push_block", "allow_unprotected" ] }, "source": { "enum": [ "platform", "sandbox" ] }, "stream": { "additionalProperties": false, "description": "The stream of the event; null for workspace.*, bundle.* and ping.", "properties": { "id": { "pattern": "^run_[0-9A-HJKMNP-TV-Z]{26}$", "type": "string" }, "seq": { "description": "Gap-free within the stream.", "minimum": 1, "type": "integer" }, "type": { "const": "run" } }, "required": [ "type", "id", "seq" ], "type": [ "object", "null" ] }, "turn_id": { "description": "The turn the event belongs to, if any.", "pattern": "^trn_[0-9A-HJKMNP-TV-Z]{26}$", "type": [ "string", "null" ] }, "type": { "description": "The event type. Clients ignore types they do not know.", "type": "string" }, "workspace": { "additionalProperties": false, "description": "The workspace of the event; null for bundle.* and ping.", "properties": { "external_id": { "type": "string" }, "id": { "pattern": "^ws_[0-9A-HJKMNP-TV-Z]{26}$", "type": "string" } }, "required": [ "id", "external_id" ], "type": [ "object", "null" ] } }, "required": [ "id", "type", "created_at", "api_version", "workspace", "stream", "turn_id", "source", "data" ], "title": "Event envelope", "type": "object" }, "File": { "additionalProperties": false, "description": "An output file a run wrote under outputs/.", "properties": { "content_type": { "type": "string" }, "created_at": { "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$", "type": "string" }, "expires_at": { "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$", "type": "string" }, "id": { "pattern": "^file_[0-9A-HJKMNP-TV-Z]{26}$", "type": "string" }, "object": { "const": "file" }, "path": { "description": "Relative to the run root.", "pattern": "^outputs/.+$", "type": "string" }, "run": { "pattern": "^run_[0-9A-HJKMNP-TV-Z]{26}$", "type": "string" }, "sha256": { "description": "Lower-case hex.", "pattern": "^[0-9a-f]{64}$", "type": "string" }, "size_bytes": { "minimum": 0, "type": "integer" }, "status": { "enum": [ "available", "expired" ] }, "workspace": { "pattern": "^ws_[0-9A-HJKMNP-TV-Z]{26}$", "type": "string" } }, "required": [ "id", "object", "run", "workspace", "path", "size_bytes", "sha256", "content_type", "created_at", "expires_at", "status" ], "title": "File", "type": "object" }, "GitAuthor": { "additionalProperties": false, "properties": { "email": { "minLength": 1, "type": "string" }, "name": { "minLength": 1, "type": "string" } }, "required": [ "name", "email" ], "type": "object" }, "GitRepository": { "additionalProperties": false, "properties": { "attribution": { "default": "default", "enum": [ "default", "none" ], "type": "string" }, "author": { "anyOf": [ { "$ref": "#/components/schemas/GitAuthor" }, { "type": "null" } ] }, "branch": { "anyOf": [ { "minLength": 1, "type": "string" }, { "type": "null" } ] }, "credential_secret": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "depth": { "anyOf": [ { "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "default": 50 }, "path": { "default": "repo", "type": "string" }, "ref": { "minLength": 1, "type": "string" }, "repo_policy": { "default": "require_push_block", "enum": [ "require_push_block", "allow_unprotected" ], "type": "string" }, "repo_policy_ack": { "anyOf": [ { "$ref": "#/components/schemas/RepoPolicyAck" }, { "type": "null" } ] }, "type": { "const": "git_repository", "type": "string" }, "url": { "type": "string" } }, "required": [ "type", "url", "ref" ], "type": "object" }, "InputFile": { "additionalProperties": false, "properties": { "content": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "content_base64": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "path": { "type": "string" }, "root": { "default": "run", "type": "string" } }, "required": [ "path" ], "type": "object" }, "InputPart": { "additionalProperties": false, "properties": { "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "text": { "type": "string" }, "trust": { "default": "user", "type": "string" }, "type": { "const": "text", "type": "string" } }, "required": [ "type", "text" ], "type": "object" }, "Lifecycle": { "additionalProperties": false, "properties": { "expires_in_s": { "anyOf": [ { "minimum": 1.0, "type": "integer" }, { "type": "null" } ] }, "idle_suspend_s": { "anyOf": [ { "minimum": 1.0, "type": "integer" }, { "type": "null" } ] }, "queue_timeout_s": { "anyOf": [ { "minimum": 1.0, "type": "integer" }, { "type": "null" } ] }, "resume_timeout_s": { "anyOf": [ { "minimum": 1.0, "type": "integer" }, { "type": "null" } ] } }, "type": "object" }, "ListResponse": { "properties": { "data": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_after": { "description": "Pass as `after` to get the next page; null on the last.", "type": [ "string", "null" ] }, "object": { "const": "list" } }, "required": [ "object", "data", "has_more", "next_after" ], "type": "object" }, "PushedRef": { "additionalProperties": false, "description": "A ref the run pushed, as the sandbox's git wrapper saw it. Sandbox-reported: it proves origin, not truth, so compare it with GitHub.", "properties": { "at": { "description": "When the push happened, RFC 3339 UTC.", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,6})?Z$", "type": "string" }, "ref": { "description": "The full ref name.", "pattern": "^refs/[^\\x00-\\x20\\x7f]{1,1000}$", "type": "string" }, "remote": { "description": "The repository.", "pattern": "^https://github\\.com/[^/\\s]+/[^/\\s]+$", "type": "string" }, "sha": { "description": "The commit pushed; null when the wrapper did not see it.", "pattern": "^[0-9a-f]{40}$", "type": [ "string", "null" ] } }, "required": [ "ref", "sha", "remote", "at" ], "title": "PushedRef", "type": "object" }, "RepoPolicyAck": { "additionalProperties": false, "properties": { "at": { "format": "date-time", "type": "string" }, "by": { "minLength": 1, "type": "string" } }, "required": [ "by", "at" ], "type": "object" }, "RunCreate": { "additionalProperties": false, "properties": { "approvals": { "$ref": "#/components/schemas/Approvals" }, "budget": { "anyOf": [ { "$ref": "#/components/schemas/Budget" }, { "type": "null" } ] }, "collect": { "$ref": "#/components/schemas/Collect" }, "definition": { "$ref": "#/components/schemas/RunDefinition" }, "files": { "items": { "$ref": "#/components/schemas/InputFile" }, "type": "array" }, "initial_turn": { "anyOf": [ { "$ref": "#/components/schemas/TurnInput" }, { "type": "null" } ] }, "lifecycle": { "$ref": "#/components/schemas/Lifecycle" }, "limits": { "$ref": "#/components/schemas/RunLimits" }, "metadata": { "additionalProperties": true, "type": "object" }, "resources": { "items": { "$ref": "#/components/schemas/GitRepository" }, "type": "array" }, "runtime": { "default": "current", "enum": [ "current", "previous", "next" ], "type": "string" }, "secrets": { "additionalProperties": { "oneOf": [ { "$ref": "#/components/schemas/SecretValue" }, { "format": "password", "type": "string", "writeOnly": true } ] }, "type": "object" }, "size": { "default": "small", "enum": [ "small", "standard", "large" ], "type": "string" } }, "required": [ "definition" ], "type": "object" }, "RunDefinition": { "additionalProperties": false, "properties": { "bundle": { "pattern": "^[a-z0-9][a-z0-9-]{0,47}$", "type": "string" }, "variables": { "additionalProperties": { "type": "string" }, "type": "object" }, "version": { "pattern": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(-[0-9A-Za-z.-]{1,32})?$", "type": "string" } }, "required": [ "bundle", "version" ], "type": "object" }, "RunLimits": { "additionalProperties": false, "properties": { "turn_timeout_s": { "anyOf": [ { "minimum": 1.0, "type": "integer" }, { "type": "null" } ] } }, "type": "object" }, "RunPatch": { "additionalProperties": false, "properties": { "budget": { "anyOf": [ { "$ref": "#/components/schemas/Budget" }, { "type": "null" } ] }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ] } }, "type": "object" }, "SecretPut": { "additionalProperties": false, "properties": { "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "refreshable": { "default": false, "type": "boolean" }, "value": { "format": "password", "type": "string", "writeOnly": true } }, "required": [ "value" ], "type": "object" }, "SecretValue": { "additionalProperties": false, "properties": { "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "refreshable": { "default": false, "type": "boolean" }, "value": { "format": "password", "type": "string", "writeOnly": true } }, "required": [ "value" ], "type": "object" }, "TurnActor": { "additionalProperties": false, "properties": { "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "kind": { "type": "string" } }, "required": [ "kind" ], "type": "object" }, "TurnInput": { "additionalProperties": false, "properties": { "actor": { "anyOf": [ { "$ref": "#/components/schemas/TurnActor" }, { "type": "null" } ] }, "context": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ] }, "input": { "items": { "$ref": "#/components/schemas/InputPart" }, "type": "array" }, "limits": { "anyOf": [ { "$ref": "#/components/schemas/TurnLimits" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ] }, "output_schema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ] }, "trigger": { "anyOf": [ { "$ref": "#/components/schemas/TurnTrigger" }, { "type": "null" } ] } }, "type": "object" }, "TurnLimits": { "additionalProperties": false, "properties": { "turn_timeout_s": { "anyOf": [ { "minimum": 1.0, "type": "integer" }, { "type": "null" } ] } }, "type": "object" }, "TurnTrigger": { "additionalProperties": false, "properties": { "schedule": { "minLength": 1, "type": "string" } }, "required": [ "schedule" ], "type": "object" }, "Usage": { "additionalProperties": false, "description": "The model usage and cost of a turn, or the total of a run.", "properties": { "cache_creation_tokens": { "minimum": 0, "type": "integer" }, "cache_read_tokens": { "minimum": 0, "type": "integer" }, "cost_usd": { "description": "Cost in US dollars.", "minimum": 0, "type": "number" }, "input_tokens": { "minimum": 0, "type": "integer" }, "model": { "description": "The model that served the turn.", "type": "string" }, "output_tokens": { "minimum": 0, "type": "integer" } }, "required": [ "model", "input_tokens", "output_tokens", "cache_read_tokens", "cache_creation_tokens", "cost_usd" ], "title": "Usage", "type": "object" }, "WebhookEndpointCreate": { "additionalProperties": false, "properties": { "events": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ] }, "url": { "type": "string" }, "workspace_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ] } }, "required": [ "url" ], "type": "object" }, "WebhookEndpointPatch": { "additionalProperties": false, "properties": { "events": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ] }, "status": { "anyOf": [ { "enum": [ "enabled", "disabled" ], "type": "string" }, { "type": "null" } ] }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "workspace_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ] } }, "type": "object" }, "WorkspaceCreate": { "additionalProperties": false, "properties": { "external_id": { "type": "string" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tz": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "external_id" ], "type": "object" }, "WorkspacePatch": { "additionalProperties": false, "properties": { "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tz": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "type": "object" } }, "securitySchemes": { "apiKey": { "scheme": "bearer", "type": "http" } } }, "info": { "description": "The Agent API runs coding and automation agents for your app in isolated workspaces. Every request goes to https://api.forgeling.io/v1 over HTTPS with JSON bodies and an API key as a bearer token (`Authorization: Bearer fgk_...`); the key's scopes decide which operations it may call. Errors, pagination, idempotency, versioning, rate limits and the signed webhooks are described in [conventions](/reference/conventions/).", "title": "Agent API", "version": "2026-11-01" }, "openapi": "3.1.0", "paths": { "/app": { "get": { "operationId": "get_app", "parameters": [ { "description": "The API version. The only version is the default.", "in": "header", "name": "Forgeling-Version", "required": false, "schema": { "enum": [ "2026-11-01" ] } }, { "description": "Comma-separated beta features to use, such as `runtime-next`. May be repeated.", "in": "header", "name": "Forgeling-Beta", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "OK", "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Sunset": { "$ref": "#/components/headers/Sunset" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "apiKey": [] } ], "summary": "Get the calling app", "tags": [ "App" ] } }, "/app/credential_refresh": { "delete": { "operationId": "delete_credential_refresh", "parameters": [ { "description": "The API version. The only version is the default.", "in": "header", "name": "Forgeling-Version", "required": false, "schema": { "enum": [ "2026-11-01" ] } }, { "description": "Comma-separated beta features to use, such as `runtime-next`. May be repeated.", "in": "header", "name": "Forgeling-Beta", "required": false, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content", "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Sunset": { "$ref": "#/components/headers/Sunset" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "apiKey": [ "webhooks:write" ] } ], "summary": "Remove the credential-refresh endpoint", "tags": [ "Webhooks" ] }, "get": { "operationId": "get_credential_refresh", "parameters": [ { "description": "The API version. The only version is the default.", "in": "header", "name": "Forgeling-Version", "required": false, "schema": { "enum": [ "2026-11-01" ] } }, { "description": "Comma-separated beta features to use, such as `runtime-next`. May be repeated.", "in": "header", "name": "Forgeling-Beta", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "OK", "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Sunset": { "$ref": "#/components/headers/Sunset" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "apiKey": [ "webhooks:read" ] } ], "summary": "Get the credential-refresh endpoint", "tags": [ "Webhooks" ] }, "put": { "operationId": "put_credential_refresh", "parameters": [ { "description": "The API version. The only version is the default.", "in": "header", "name": "Forgeling-Version", "required": false, "schema": { "enum": [ "2026-11-01" ] } }, { "description": "Comma-separated beta features to use, such as `runtime-next`. May be repeated.", "in": "header", "name": "Forgeling-Beta", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialRefreshPut" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "OK", "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Sunset": { "$ref": "#/components/headers/Sunset" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "apiKey": [ "webhooks:write" ] } ], "summary": "Set the credential-refresh URL", "tags": [ "Webhooks" ] } }, "/app/credential_refresh/rotate_secret": { "post": { "operationId": "rotate_credential_refresh_secret", "parameters": [ { "description": "The API version. The only version is the default.", "in": "header", "name": "Forgeling-Version", "required": false, "schema": { "enum": [ "2026-11-01" ] } }, { "description": "Comma-separated beta features to use, such as `runtime-next`. May be repeated.", "in": "header", "name": "Forgeling-Beta", "required": false, "schema": { "type": "string" } }, { "description": "Makes the request safe to retry: a repeat with the same key and body within 24 hours returns the original response with `Idempotent-Replayed: true`, and a different body is a 409 `idempotency_conflict`.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "minLength": 1, "pattern": "^[\\x21-\\x7e]+$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "OK", "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Sunset": { "$ref": "#/components/headers/Sunset" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "apiKey": [ "webhooks:write" ] } ], "summary": "Give the credential-refresh endpoint a new secret; the old one signs for another 24 hours", "tags": [ "Webhooks" ] } }, "/approvals": { "get": { "operationId": "list_approvals", "parameters": [ { "in": "query", "name": "status", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, { "in": "query", "name": "workspace", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, { "in": "query", "name": "run", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, { "in": "query", "name": "after", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "The API version. The only version is the default.", "in": "header", "name": "Forgeling-Version", "required": false, "schema": { "enum": [ "2026-11-01" ] } }, { "description": "Comma-separated beta features to use, such as `runtime-next`. May be repeated.", "in": "header", "name": "Forgeling-Beta", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse" } } }, "description": "OK", "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Sunset": { "$ref": "#/components/headers/Sunset" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "apiKey": [ "approvals:read" ] } ], "summary": "List approvals", "tags": [ "Approvals" ] } }, "/approvals/{apr}/decision": { "post": { "operationId": "decide_approval", "parameters": [ { "description": "An approval id, `apr_` and a ULID.", "in": "path", "name": "apr", "required": true, "schema": { "type": "string" } }, { "description": "The API version. The only version is the default.", "in": "header", "name": "Forgeling-Version", "required": false, "schema": { "enum": [ "2026-11-01" ] } }, { "description": "Comma-separated beta features to use, such as `runtime-next`. May be repeated.", "in": "header", "name": "Forgeling-Beta", "required": false, "schema": { "type": "string" } }, { "description": "Makes the request safe to retry: a repeat with the same key and body within 24 hours returns the original response with `Idempotent-Replayed: true`, and a different body is a 409 `idempotency_conflict`.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "minLength": 1, "pattern": "^[\\x21-\\x7e]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalDecision" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "OK", "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Sunset": { "$ref": "#/components/headers/Sunset" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "apiKey": [ "approvals:write" ] } ], "summary": "Allow or deny an approval", "tags": [ "Approvals" ] } }, "/bundles": { "get": { "operationId": "list_bundles", "parameters": [ { "in": "query", "name": "after", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "The API version. The only version is the default.", "in": "header", "name": "Forgeling-Version", "required": false, "schema": { "enum": [ "2026-11-01" ] } }, { "description": "Comma-separated beta features to use, such as `runtime-next`. May be repeated.", "in": "header", "name": "Forgeling-Beta", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse" } } }, "description": "OK", "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Sunset": { "$ref": "#/components/headers/Sunset" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "apiKey": [ "bundles:read" ] } ], "summary": "List bundles", "tags": [ "Bundles" ] } }, "/bundles/{name}/versions": { "get": { "operationId": "list_bundle_versions", "parameters": [ { "description": "The name of a bundle.", "in": "path", "name": "name", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "after", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "The API version. The only version is the default.", "in": "header", "name": "Forgeling-Version", "required": false, "schema": { "enum": [ "2026-11-01" ] } }, { "description": "Comma-separated beta features to use, such as `runtime-next`. May be repeated.", "in": "header", "name": "Forgeling-Beta", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse" } } }, "description": "OK", "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Sunset": { "$ref": "#/components/headers/Sunset" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "apiKey": [ "bundles:read" ] } ], "summary": "List the versions of a bundle", "tags": [ "Bundles" ] }, "post": { "operationId": "create_bundle_version", "parameters": [ { "description": "The name of a bundle.", "in": "path", "name": "name", "required": true, "schema": { "type": "string" } }, { "description": "The API version. The only version is the default.", "in": "header", "name": "Forgeling-Version", "required": false, "schema": { "enum": [ "2026-11-01" ] } }, { "description": "Comma-separated beta features to use, such as `runtime-next`. May be repeated.", "in": "header", "name": "Forgeling-Beta", "required": false, "schema": { "type": "string" } }, { "description": "Makes the request safe to retry: a repeat with the same key and body within 24 hours returns the original response with `Idempotent-Replayed: true`, and a different body is a 409 `idempotency_conflict`.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "minLength": 1, "pattern": "^[\\x21-\\x7e]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BundleVersionCreate" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Accepted", "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Sunset": { "$ref": "#/components/headers/Sunset" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "apiKey": [ "bundles:write" ] } ], "summary": "Publish a version of a bundle from an inline spec", "tags": [ "Bundles" ] } }, "/bundles/{name}/versions/{v}": { "get": { "operationId": "get_bundle_version", "parameters": [ { "description": "The name of a bundle.", "in": "path", "name": "name", "required": true, "schema": { "type": "string" } }, { "description": "A bundle version, such as `1.0.0`.", "in": "path", "name": "v", "required": true, "schema": { "type": "string" } }, { "description": "The API version. The only version is the default.", "in": "header", "name": "Forgeling-Version", "required": false, "schema": { "enum": [ "2026-11-01" ] } }, { "description": "Comma-separated beta features to use, such as `runtime-next`. May be repeated.", "in": "header", "name": "Forgeling-Beta", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "OK", "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Sunset": { "$ref": "#/components/headers/Sunset" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "apiKey": [ "bundles:read" ] } ], "summary": "Get a version of a bundle", "tags": [ "Bundles" ] } }, "/bundles/{name}/versions/{v}/yank": { "post": { "operationId": "yank_bundle_version", "parameters": [ { "description": "The name of a bundle.", "in": "path", "name": "name", "required": true, "schema": { "type": "string" } }, { "description": "A bundle version, such as `1.0.0`.", "in": "path", "name": "v", "required": true, "schema": { "type": "string" } }, { "description": "The API version. The only version is the default.", "in": "header", "name": "Forgeling-Version", "required": false, "schema": { "enum": [ "2026-11-01" ] } }, { "description": "Comma-separated beta features to use, such as `runtime-next`. May be repeated.", "in": "header", "name": "Forgeling-Beta", "required": false, "schema": { "type": "string" } }, { "description": "Makes the request safe to retry: a repeat with the same key and body within 24 hours returns the original response with `Idempotent-Replayed: true`, and a different body is a 409 `idempotency_conflict`.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "minLength": 1, "pattern": "^[\\x21-\\x7e]+$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "OK", "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Sunset": { "$ref": "#/components/headers/Sunset" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "apiKey": [ "bundles:write" ] } ], "summary": "Yank a version: it starts no new runs", "tags": [ "Bundles" ] } }, "/events": { "get": { "operationId": "list_events", "parameters": [ { "in": "query", "name": "after", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, { "in": "query", "name": "workspace", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, { "in": "query", "name": "type", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "The API version. The only version is the default.", "in": "header", "name": "Forgeling-Version", "required": false, "schema": { "enum": [ "2026-11-01" ] } }, { "description": "Comma-separated beta features to use, such as `runtime-next`. May be repeated.", "in": "header", "name": "Forgeling-Beta", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse" } } }, "description": "OK", "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Sunset": { "$ref": "#/components/headers/Sunset" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "apiKey": [ "events:read" ] } ], "summary": "List the app's events", "tags": [ "Events" ] } }, "/files/{f}": { "get": { "operationId": "get_file", "parameters": [ { "description": "A file id, `file_` and a ULID.", "in": "path", "name": "f", "required": true, "schema": { "type": "string" } }, { "description": "The API version. The only version is the default.", "in": "header", "name": "Forgeling-Version", "required": false, "schema": { "enum": [ "2026-11-01" ] } }, { "description": "Comma-separated beta features to use, such as `runtime-next`. May be repeated.", "in": "header", "name": "Forgeling-Beta", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "OK", "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Sunset": { "$ref": "#/components/headers/Sunset" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "apiKey": [ "files:read" ] } ], "summary": "Get an output file", "tags": [ "Files" ] } }, "/files/{f}/content": { "get": { "operationId": "download_file", "parameters": [ { "description": "A file id, `file_` and a ULID.", "in": "path", "name": "f", "required": true, "schema": { "type": "string" } }, { "description": "The API version. The only version is the default.", "in": "header", "name": "Forgeling-Version", "required": false, "schema": { "enum": [ "2026-11-01" ] } }, { "description": "Comma-separated beta features to use, such as `runtime-next`. May be repeated.", "in": "header", "name": "Forgeling-Beta", "required": false, "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirect to a signed URL", "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Location": { "description": "A signed URL that serves the file for five minutes.", "schema": { "format": "uri", "type": "string" } }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Sunset": { "$ref": "#/components/headers/Sunset" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "apiKey": [ "files:read" ] } ], "summary": "Download an output file", "tags": [ "Files" ] } }, "/runs/{run}": { "delete": { "operationId": "delete_run", "parameters": [ { "description": "A run id, `run_` and a ULID.", "in": "path", "name": "run", "required": true, "schema": { "type": "string" } }, { "description": "The API version. The only version is the default.", "in": "header", "name": "Forgeling-Version", "required": false, "schema": { "enum": [ "2026-11-01" ] } }, { "description": "Comma-separated beta features to use, such as `runtime-next`. May be repeated.", "in": "header", "name": "Forgeling-Beta", "required": false, "schema": { "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Accepted", "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Sunset": { "$ref": "#/components/headers/Sunset" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "apiKey": [ "runs:write" ] } ], "summary": "Delete a run", "tags": [ "Runs" ] }, "get": { "operationId": "get_run", "parameters": [ { "description": "A run id, `run_` and a ULID.", "in": "path", "name": "run", "required": true, "schema": { "type": "string" } }, { "description": "The API version. The only version is the default.", "in": "header", "name": "Forgeling-Version", "required": false, "schema": { "enum": [ "2026-11-01" ] } }, { "description": "Comma-separated beta features to use, such as `runtime-next`. May be repeated.", "in": "header", "name": "Forgeling-Beta", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "OK", "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Sunset": { "$ref": "#/components/headers/Sunset" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "apiKey": [ "runs:read" ] } ], "summary": "Get a run", "tags": [ "Runs" ] }, "patch": { "operationId": "update_run", "parameters": [ { "description": "A run id, `run_` and a ULID.", "in": "path", "name": "run", "required": true, "schema": { "type": "string" } }, { "description": "The API version. The only version is the default.", "in": "header", "name": "Forgeling-Version", "required": false, "schema": { "enum": [ "2026-11-01" ] } }, { "description": "Comma-separated beta features to use, such as `runtime-next`. May be repeated.", "in": "header", "name": "Forgeling-Beta", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunPatch" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "OK", "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Sunset": { "$ref": "#/components/headers/Sunset" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "apiKey": [ "runs:write" ] } ], "summary": "Raise a run's budget, extend its expiry or replace its metadata", "tags": [ "Runs" ] } }, "/runs/{run}/cancel": { "post": { "operationId": "cancel_run", "parameters": [ { "description": "A run id, `run_` and a ULID.", "in": "path", "name": "run", "required": true, "schema": { "type": "string" } }, { "description": "The API version. The only version is the default.", "in": "header", "name": "Forgeling-Version", "required": false, "schema": { "enum": [ "2026-11-01" ] } }, { "description": "Comma-separated beta features to use, such as `runtime-next`. May be repeated.", "in": "header", "name": "Forgeling-Beta", "required": false, "schema": { "type": "string" } }, { "description": "Makes the request safe to retry: a repeat with the same key and body within 24 hours returns the original response with `Idempotent-Replayed: true`, and a different body is a 409 `idempotency_conflict`.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "minLength": 1, "pattern": "^[\\x21-\\x7e]+$", "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Accepted", "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Sunset": { "$ref": "#/components/headers/Sunset" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "apiKey": [ "runs:write" ] } ], "summary": "Cancel a run", "tags": [ "Runs" ] } }, "/runs/{run}/complete": { "post": { "operationId": "complete_run", "parameters": [ { "description": "A run id, `run_` and a ULID.", "in": "path", "name": "run", "required": true, "schema": { "type": "string" } }, { "description": "The API version. The only version is the default.", "in": "header", "name": "Forgeling-Version", "required": false, "schema": { "enum": [ "2026-11-01" ] } }, { "description": "Comma-separated beta features to use, such as `runtime-next`. May be repeated.", "in": "header", "name": "Forgeling-Beta", "required": false, "schema": { "type": "string" } }, { "description": "Makes the request safe to retry: a repeat with the same key and body within 24 hours returns the original response with `Idempotent-Replayed: true`, and a different body is a 409 `idempotency_conflict`.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "minLength": 1, "pattern": "^[\\x21-\\x7e]+$", "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Accepted", "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Sunset": { "$ref": "#/components/headers/Sunset" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "apiKey": [ "runs:write" ] } ], "summary": "Complete a run", "tags": [ "Runs" ] } }, "/runs/{run}/events": { "get": { "operationId": "list_run_events", "parameters": [ { "description": "A run id, `run_` and a ULID.", "in": "path", "name": "run", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "after", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "The API version. The only version is the default.", "in": "header", "name": "Forgeling-Version", "required": false, "schema": { "enum": [ "2026-11-01" ] } }, { "description": "Comma-separated beta features to use, such as `runtime-next`. May be repeated.", "in": "header", "name": "Forgeling-Beta", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse" } } }, "description": "OK", "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Sunset": { "$ref": "#/components/headers/Sunset" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "apiKey": [ "events:read" ] } ], "summary": "List a run's events", "tags": [ "Events" ] } }, "/runs/{run}/events/stream": { "get": { "operationId": "stream_run_events", "parameters": [ { "description": "A run id, `run_` and a ULID.", "in": "path", "name": "run", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "after", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, { "description": "The API version. The only version is the default.", "in": "header", "name": "Forgeling-Version", "required": false, "schema": { "enum": [ "2026-11-01" ] } }, { "description": "Comma-separated beta features to use, such as `runtime-next`. May be repeated.", "in": "header", "name": "Forgeling-Beta", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "text/event-stream": { "schema": { "type": "string" } } }, "description": "OK", "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Sunset": { "$ref": "#/components/headers/Sunset" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "apiKey": [ "events:read" ] } ], "summary": "Stream a run's events", "tags": [ "Events" ] } }, "/runs/{run}/files": { "get": { "operationId": "list_run_files", "parameters": [ { "description": "A run id, `run_` and a ULID.", "in": "path", "name": "run", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "after", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "The API version. The only version is the default.", "in": "header", "name": "Forgeling-Version", "required": false, "schema": { "enum": [ "2026-11-01" ] } }, { "description": "Comma-separated beta features to use, such as `runtime-next`. May be repeated.", "in": "header", "name": "Forgeling-Beta", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse" } } }, "description": "OK", "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Sunset": { "$ref": "#/components/headers/Sunset" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "apiKey": [ "files:read" ] } ], "summary": "List a run's output files", "tags": [ "Files" ] } }, "/runs/{run}/secrets/{name}": { "delete": { "operationId": "delete_run_secret", "parameters": [ { "description": "A run id, `run_` and a ULID.", "in": "path", "name": "run", "required": true, "schema": { "type": "string" } }, { "description": "The name of a run secret.", "in": "path", "name": "name", "required": true, "schema": { "type": "string" } }, { "description": "The API version. The only version is the default.", "in": "header", "name": "Forgeling-Version", "required": false, "schema": { "enum": [ "2026-11-01" ] } }, { "description": "Comma-separated beta features to use, such as `runtime-next`. May be repeated.", "in": "header", "name": "Forgeling-Beta", "required": false, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content", "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Sunset": { "$ref": "#/components/headers/Sunset" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "apiKey": [ "runs:write" ] } ], "summary": "Remove a run secret", "tags": [ "Runs" ] }, "put": { "operationId": "put_run_secret", "parameters": [ { "description": "A run id, `run_` and a ULID.", "in": "path", "name": "run", "required": true, "schema": { "type": "string" } }, { "description": "The name of a run secret.", "in": "path", "name": "name", "required": true, "schema": { "type": "string" } }, { "description": "The API version. The only version is the default.", "in": "header", "name": "Forgeling-Version", "required": false, "schema": { "enum": [ "2026-11-01" ] } }, { "description": "Comma-separated beta features to use, such as `runtime-next`. May be repeated.", "in": "header", "name": "Forgeling-Beta", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretPut" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "OK", "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Sunset": { "$ref": "#/components/headers/Sunset" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "apiKey": [ "runs:write" ] } ], "summary": "Set a run secret", "tags": [ "Runs" ] } }, "/runs/{run}/turns": { "post": { "operationId": "create_turn", "parameters": [ { "description": "A run id, `run_` and a ULID.", "in": "path", "name": "run", "required": true, "schema": { "type": "string" } }, { "description": "The API version. The only version is the default.", "in": "header", "name": "Forgeling-Version", "required": false, "schema": { "enum": [ "2026-11-01" ] } }, { "description": "Comma-separated beta features to use, such as `runtime-next`. May be repeated.", "in": "header", "name": "Forgeling-Beta", "required": false, "schema": { "type": "string" } }, { "description": "Makes the request safe to retry: a repeat with the same key and body within 24 hours returns the original response with `Idempotent-Replayed: true`, and a different body is a 409 `idempotency_conflict`. Required here.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 255, "minLength": 1, "pattern": "^[\\x21-\\x7e]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TurnInput" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Accepted", "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Sunset": { "$ref": "#/components/headers/Sunset" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "apiKey": [ "runs:write" ] } ], "summary": "Post a turn to a run", "tags": [ "Turns" ] } }, "/turns": { "get": { "operationId": "find_turn", "parameters": [ { "in": "query", "name": "run", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "idempotency_key", "required": true, "schema": { "type": "string" } }, { "description": "The API version. The only version is the default.", "in": "header", "name": "Forgeling-Version", "required": false, "schema": { "enum": [ "2026-11-01" ] } }, { "description": "Comma-separated beta features to use, such as `runtime-next`. May be repeated.", "in": "header", "name": "Forgeling-Beta", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "OK", "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Sunset": { "$ref": "#/components/headers/Sunset" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "apiKey": [ "runs:read" ] } ], "summary": "Find a run's turn by the Idempotency-Key it was posted with", "tags": [ "Turns" ] } }, "/turns/{trn}": { "get": { "operationId": "get_turn", "parameters": [ { "description": "A turn id, `trn_` and a ULID.", "in": "path", "name": "trn", "required": true, "schema": { "type": "string" } }, { "description": "The API version. The only version is the default.", "in": "header", "name": "Forgeling-Version", "required": false, "schema": { "enum": [ "2026-11-01" ] } }, { "description": "Comma-separated beta features to use, such as `runtime-next`. May be repeated.", "in": "header", "name": "Forgeling-Beta", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "OK", "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Sunset": { "$ref": "#/components/headers/Sunset" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "apiKey": [ "runs:read" ] } ], "summary": "Get a turn", "tags": [ "Turns" ] } }, "/turns/{trn}/cancel": { "post": { "operationId": "cancel_turn", "parameters": [ { "description": "A turn id, `trn_` and a ULID.", "in": "path", "name": "trn", "required": true, "schema": { "type": "string" } }, { "description": "The API version. The only version is the default.", "in": "header", "name": "Forgeling-Version", "required": false, "schema": { "enum": [ "2026-11-01" ] } }, { "description": "Comma-separated beta features to use, such as `runtime-next`. May be repeated.", "in": "header", "name": "Forgeling-Beta", "required": false, "schema": { "type": "string" } }, { "description": "Makes the request safe to retry: a repeat with the same key and body within 24 hours returns the original response with `Idempotent-Replayed: true`, and a different body is a 409 `idempotency_conflict`.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "minLength": 1, "pattern": "^[\\x21-\\x7e]+$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "OK", "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Sunset": { "$ref": "#/components/headers/Sunset" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "apiKey": [ "runs:write" ] } ], "summary": "Cancel a turn", "tags": [ "Turns" ] } }, "/usage": { "get": { "operationId": "list_usage", "parameters": [ { "in": "query", "name": "workspace", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, { "in": "query", "name": "from", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, { "in": "query", "name": "to", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, { "in": "query", "name": "group_by", "required": false, "schema": { "default": "day", "type": "string" } }, { "in": "query", "name": "after", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "The API version. The only version is the default.", "in": "header", "name": "Forgeling-Version", "required": false, "schema": { "enum": [ "2026-11-01" ] } }, { "description": "Comma-separated beta features to use, such as `runtime-next`. May be repeated.", "in": "header", "name": "Forgeling-Beta", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse" } } }, "description": "OK", "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Sunset": { "$ref": "#/components/headers/Sunset" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "apiKey": [ "usage:read" ] } ], "summary": "Usage by day or by run", "tags": [ "Usage" ] } }, "/webhook_deliveries": { "get": { "operationId": "list_webhook_deliveries", "parameters": [ { "in": "query", "name": "endpoint", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, { "in": "query", "name": "status", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, { "in": "query", "name": "after", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "The API version. The only version is the default.", "in": "header", "name": "Forgeling-Version", "required": false, "schema": { "enum": [ "2026-11-01" ] } }, { "description": "Comma-separated beta features to use, such as `runtime-next`. May be repeated.", "in": "header", "name": "Forgeling-Beta", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse" } } }, "description": "OK", "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Sunset": { "$ref": "#/components/headers/Sunset" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "apiKey": [ "webhooks:read" ] } ], "summary": "List webhook deliveries, newest first", "tags": [ "Webhooks" ] } }, "/webhook_deliveries/{id}/retry": { "post": { "operationId": "retry_webhook_delivery", "parameters": [ { "description": "A webhook delivery id, `whd_` and a ULID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "The API version. The only version is the default.", "in": "header", "name": "Forgeling-Version", "required": false, "schema": { "enum": [ "2026-11-01" ] } }, { "description": "Comma-separated beta features to use, such as `runtime-next`. May be repeated.", "in": "header", "name": "Forgeling-Beta", "required": false, "schema": { "type": "string" } }, { "description": "Makes the request safe to retry: a repeat with the same key and body within 24 hours returns the original response with `Idempotent-Replayed: true`, and a different body is a 409 `idempotency_conflict`.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "minLength": 1, "pattern": "^[\\x21-\\x7e]+$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "OK", "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Sunset": { "$ref": "#/components/headers/Sunset" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "apiKey": [ "webhooks:write" ] } ], "summary": "Send a delivery again now", "tags": [ "Webhooks" ] } }, "/webhook_endpoints": { "get": { "operationId": "list_webhook_endpoints", "parameters": [ { "in": "query", "name": "after", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "The API version. The only version is the default.", "in": "header", "name": "Forgeling-Version", "required": false, "schema": { "enum": [ "2026-11-01" ] } }, { "description": "Comma-separated beta features to use, such as `runtime-next`. May be repeated.", "in": "header", "name": "Forgeling-Beta", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse" } } }, "description": "OK", "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Sunset": { "$ref": "#/components/headers/Sunset" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "apiKey": [ "webhooks:read" ] } ], "summary": "List webhook endpoints", "tags": [ "Webhooks" ] }, "post": { "operationId": "create_webhook_endpoint", "parameters": [ { "description": "The API version. The only version is the default.", "in": "header", "name": "Forgeling-Version", "required": false, "schema": { "enum": [ "2026-11-01" ] } }, { "description": "Comma-separated beta features to use, such as `runtime-next`. May be repeated.", "in": "header", "name": "Forgeling-Beta", "required": false, "schema": { "type": "string" } }, { "description": "Makes the request safe to retry: a repeat with the same key and body within 24 hours returns the original response with `Idempotent-Replayed: true`, and a different body is a 409 `idempotency_conflict`.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "minLength": 1, "pattern": "^[\\x21-\\x7e]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Created", "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Sunset": { "$ref": "#/components/headers/Sunset" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "apiKey": [ "webhooks:write" ] } ], "summary": "Register a webhook endpoint", "tags": [ "Webhooks" ] } }, "/webhook_endpoints/{id}": { "delete": { "operationId": "delete_webhook_endpoint", "parameters": [ { "description": "A webhook endpoint id, `whe_` and a ULID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "The API version. The only version is the default.", "in": "header", "name": "Forgeling-Version", "required": false, "schema": { "enum": [ "2026-11-01" ] } }, { "description": "Comma-separated beta features to use, such as `runtime-next`. May be repeated.", "in": "header", "name": "Forgeling-Beta", "required": false, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content", "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Sunset": { "$ref": "#/components/headers/Sunset" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "apiKey": [ "webhooks:write" ] } ], "summary": "Delete a webhook endpoint", "tags": [ "Webhooks" ] }, "get": { "operationId": "get_webhook_endpoint", "parameters": [ { "description": "A webhook endpoint id, `whe_` and a ULID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "The API version. The only version is the default.", "in": "header", "name": "Forgeling-Version", "required": false, "schema": { "enum": [ "2026-11-01" ] } }, { "description": "Comma-separated beta features to use, such as `runtime-next`. May be repeated.", "in": "header", "name": "Forgeling-Beta", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "OK", "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Sunset": { "$ref": "#/components/headers/Sunset" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "apiKey": [ "webhooks:read" ] } ], "summary": "Get a webhook endpoint", "tags": [ "Webhooks" ] }, "patch": { "operationId": "update_webhook_endpoint", "parameters": [ { "description": "A webhook endpoint id, `whe_` and a ULID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "The API version. The only version is the default.", "in": "header", "name": "Forgeling-Version", "required": false, "schema": { "enum": [ "2026-11-01" ] } }, { "description": "Comma-separated beta features to use, such as `runtime-next`. May be repeated.", "in": "header", "name": "Forgeling-Beta", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointPatch" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "OK", "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Sunset": { "$ref": "#/components/headers/Sunset" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "apiKey": [ "webhooks:write" ] } ], "summary": "Change a webhook endpoint, or enable it again", "tags": [ "Webhooks" ] } }, "/webhook_endpoints/{id}/rotate_secret": { "post": { "operationId": "rotate_webhook_endpoint_secret", "parameters": [ { "description": "A webhook endpoint id, `whe_` and a ULID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "The API version. The only version is the default.", "in": "header", "name": "Forgeling-Version", "required": false, "schema": { "enum": [ "2026-11-01" ] } }, { "description": "Comma-separated beta features to use, such as `runtime-next`. May be repeated.", "in": "header", "name": "Forgeling-Beta", "required": false, "schema": { "type": "string" } }, { "description": "Makes the request safe to retry: a repeat with the same key and body within 24 hours returns the original response with `Idempotent-Replayed: true`, and a different body is a 409 `idempotency_conflict`.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "minLength": 1, "pattern": "^[\\x21-\\x7e]+$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "OK", "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Sunset": { "$ref": "#/components/headers/Sunset" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "apiKey": [ "webhooks:write" ] } ], "summary": "Give a webhook endpoint a new secret; the old one signs for another 24 hours", "tags": [ "Webhooks" ] } }, "/webhook_endpoints/{id}/test": { "post": { "operationId": "send_webhook_test", "parameters": [ { "description": "A webhook endpoint id, `whe_` and a ULID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "The API version. The only version is the default.", "in": "header", "name": "Forgeling-Version", "required": false, "schema": { "enum": [ "2026-11-01" ] } }, { "description": "Comma-separated beta features to use, such as `runtime-next`. May be repeated.", "in": "header", "name": "Forgeling-Beta", "required": false, "schema": { "type": "string" } }, { "description": "Makes the request safe to retry: a repeat with the same key and body within 24 hours returns the original response with `Idempotent-Replayed: true`, and a different body is a 409 `idempotency_conflict`.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "minLength": 1, "pattern": "^[\\x21-\\x7e]+$", "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Accepted", "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Sunset": { "$ref": "#/components/headers/Sunset" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "apiKey": [ "webhooks:write" ] } ], "summary": "Send a ping event to this endpoint alone", "tags": [ "Webhooks" ] } }, "/workspaces": { "get": { "operationId": "list_workspaces", "parameters": [ { "in": "query", "name": "external_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, { "in": "query", "name": "after", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "The API version. The only version is the default.", "in": "header", "name": "Forgeling-Version", "required": false, "schema": { "enum": [ "2026-11-01" ] } }, { "description": "Comma-separated beta features to use, such as `runtime-next`. May be repeated.", "in": "header", "name": "Forgeling-Beta", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse" } } }, "description": "OK", "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Sunset": { "$ref": "#/components/headers/Sunset" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "apiKey": [ "workspaces:read" ] } ], "summary": "List workspaces", "tags": [ "Workspaces" ] }, "post": { "operationId": "create_workspace", "parameters": [ { "description": "The API version. The only version is the default.", "in": "header", "name": "Forgeling-Version", "required": false, "schema": { "enum": [ "2026-11-01" ] } }, { "description": "Comma-separated beta features to use, such as `runtime-next`. May be repeated.", "in": "header", "name": "Forgeling-Beta", "required": false, "schema": { "type": "string" } }, { "description": "Makes the request safe to retry: a repeat with the same key and body within 24 hours returns the original response with `Idempotent-Replayed: true`, and a different body is a 409 `idempotency_conflict`.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "minLength": 1, "pattern": "^[\\x21-\\x7e]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Created", "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Sunset": { "$ref": "#/components/headers/Sunset" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "apiKey": [ "workspaces:write" ] } ], "summary": "Create a workspace, or return the live one for its external_id", "tags": [ "Workspaces" ] } }, "/workspaces/{ws}": { "delete": { "operationId": "delete_workspace", "parameters": [ { "description": "A workspace id, `ws_` and a ULID.", "in": "path", "name": "ws", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "purge", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "The API version. The only version is the default.", "in": "header", "name": "Forgeling-Version", "required": false, "schema": { "enum": [ "2026-11-01" ] } }, { "description": "Comma-separated beta features to use, such as `runtime-next`. May be repeated.", "in": "header", "name": "Forgeling-Beta", "required": false, "schema": { "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Accepted", "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Sunset": { "$ref": "#/components/headers/Sunset" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "apiKey": [ "workspaces:write" ] } ], "summary": "Delete a workspace and everything in it", "tags": [ "Workspaces" ] }, "get": { "operationId": "get_workspace", "parameters": [ { "description": "A workspace id, `ws_` and a ULID.", "in": "path", "name": "ws", "required": true, "schema": { "type": "string" } }, { "description": "The API version. The only version is the default.", "in": "header", "name": "Forgeling-Version", "required": false, "schema": { "enum": [ "2026-11-01" ] } }, { "description": "Comma-separated beta features to use, such as `runtime-next`. May be repeated.", "in": "header", "name": "Forgeling-Beta", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "OK", "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Sunset": { "$ref": "#/components/headers/Sunset" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "apiKey": [ "workspaces:read" ] } ], "summary": "Get a workspace", "tags": [ "Workspaces" ] }, "patch": { "operationId": "update_workspace", "parameters": [ { "description": "A workspace id, `ws_` and a ULID.", "in": "path", "name": "ws", "required": true, "schema": { "type": "string" } }, { "description": "The API version. The only version is the default.", "in": "header", "name": "Forgeling-Version", "required": false, "schema": { "enum": [ "2026-11-01" ] } }, { "description": "Comma-separated beta features to use, such as `runtime-next`. May be repeated.", "in": "header", "name": "Forgeling-Beta", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspacePatch" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "OK", "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Sunset": { "$ref": "#/components/headers/Sunset" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "apiKey": [ "workspaces:write" ] } ], "summary": "Update a workspace's name, time zone or metadata", "tags": [ "Workspaces" ] } }, "/workspaces/{ws}/model_credential": { "delete": { "operationId": "delete_model_credential", "parameters": [ { "description": "A workspace id, `ws_` and a ULID.", "in": "path", "name": "ws", "required": true, "schema": { "type": "string" } }, { "description": "The API version. The only version is the default.", "in": "header", "name": "Forgeling-Version", "required": false, "schema": { "enum": [ "2026-11-01" ] } }, { "description": "Comma-separated beta features to use, such as `runtime-next`. May be repeated.", "in": "header", "name": "Forgeling-Beta", "required": false, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content", "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Sunset": { "$ref": "#/components/headers/Sunset" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "apiKey": [ "credentials:write" ] } ], "summary": "Remove a workspace's model credential", "tags": [ "Workspaces" ] }, "get": { "operationId": "get_model_credential", "parameters": [ { "description": "A workspace id, `ws_` and a ULID.", "in": "path", "name": "ws", "required": true, "schema": { "type": "string" } }, { "description": "The API version. The only version is the default.", "in": "header", "name": "Forgeling-Version", "required": false, "schema": { "enum": [ "2026-11-01" ] } }, { "description": "Comma-separated beta features to use, such as `runtime-next`. May be repeated.", "in": "header", "name": "Forgeling-Beta", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "OK", "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Sunset": { "$ref": "#/components/headers/Sunset" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "apiKey": [ "credentials:read" ] } ], "summary": "Get a workspace's model credential", "tags": [ "Workspaces" ] }, "put": { "operationId": "put_model_credential", "parameters": [ { "description": "A workspace id, `ws_` and a ULID.", "in": "path", "name": "ws", "required": true, "schema": { "type": "string" } }, { "description": "The API version. The only version is the default.", "in": "header", "name": "Forgeling-Version", "required": false, "schema": { "enum": [ "2026-11-01" ] } }, { "description": "Comma-separated beta features to use, such as `runtime-next`. May be repeated.", "in": "header", "name": "Forgeling-Beta", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialPut" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "OK", "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Sunset": { "$ref": "#/components/headers/Sunset" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "apiKey": [ "credentials:write" ] } ], "summary": "Set a workspace's model credential", "tags": [ "Workspaces" ] } }, "/workspaces/{ws}/resume": { "post": { "operationId": "resume_workspace", "parameters": [ { "description": "A workspace id, `ws_` and a ULID.", "in": "path", "name": "ws", "required": true, "schema": { "type": "string" } }, { "description": "The API version. The only version is the default.", "in": "header", "name": "Forgeling-Version", "required": false, "schema": { "enum": [ "2026-11-01" ] } }, { "description": "Comma-separated beta features to use, such as `runtime-next`. May be repeated.", "in": "header", "name": "Forgeling-Beta", "required": false, "schema": { "type": "string" } }, { "description": "Makes the request safe to retry: a repeat with the same key and body within 24 hours returns the original response with `Idempotent-Replayed: true`, and a different body is a 409 `idempotency_conflict`.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "minLength": 1, "pattern": "^[\\x21-\\x7e]+$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "OK", "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Sunset": { "$ref": "#/components/headers/Sunset" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "apiKey": [ "workspaces:write" ] } ], "summary": "Resume a suspended workspace", "tags": [ "Workspaces" ] } }, "/workspaces/{ws}/runs": { "get": { "operationId": "list_runs", "parameters": [ { "description": "A workspace id, `ws_` and a ULID.", "in": "path", "name": "ws", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "status", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, { "in": "query", "name": "after", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "The API version. The only version is the default.", "in": "header", "name": "Forgeling-Version", "required": false, "schema": { "enum": [ "2026-11-01" ] } }, { "description": "Comma-separated beta features to use, such as `runtime-next`. May be repeated.", "in": "header", "name": "Forgeling-Beta", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse" } } }, "description": "OK", "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Sunset": { "$ref": "#/components/headers/Sunset" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "apiKey": [ "runs:read" ] } ], "summary": "List a workspace's runs", "tags": [ "Runs" ] }, "post": { "operationId": "create_run", "parameters": [ { "description": "A workspace id, `ws_` and a ULID.", "in": "path", "name": "ws", "required": true, "schema": { "type": "string" } }, { "description": "The API version. The only version is the default.", "in": "header", "name": "Forgeling-Version", "required": false, "schema": { "enum": [ "2026-11-01" ] } }, { "description": "Comma-separated beta features to use, such as `runtime-next`. May be repeated.", "in": "header", "name": "Forgeling-Beta", "required": false, "schema": { "type": "string" } }, { "description": "Makes the request safe to retry: a repeat with the same key and body within 24 hours returns the original response with `Idempotent-Replayed: true`, and a different body is a 409 `idempotency_conflict`. Required here.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 255, "minLength": 1, "pattern": "^[\\x21-\\x7e]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunCreate" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Accepted", "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Sunset": { "$ref": "#/components/headers/Sunset" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "apiKey": [ "runs:write" ] } ], "summary": "Create a run", "tags": [ "Runs" ] } }, "/workspaces/{ws}/suspend": { "post": { "operationId": "suspend_workspace", "parameters": [ { "description": "A workspace id, `ws_` and a ULID.", "in": "path", "name": "ws", "required": true, "schema": { "type": "string" } }, { "description": "The API version. The only version is the default.", "in": "header", "name": "Forgeling-Version", "required": false, "schema": { "enum": [ "2026-11-01" ] } }, { "description": "Comma-separated beta features to use, such as `runtime-next`. May be repeated.", "in": "header", "name": "Forgeling-Beta", "required": false, "schema": { "type": "string" } }, { "description": "Makes the request safe to retry: a repeat with the same key and body within 24 hours returns the original response with `Idempotent-Replayed: true`, and a different body is a 409 `idempotency_conflict`.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "minLength": 1, "pattern": "^[\\x21-\\x7e]+$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "OK", "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Sunset": { "$ref": "#/components/headers/Sunset" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "apiKey": [ "workspaces:write" ] } ], "summary": "Suspend a workspace: no new runs, and its live runs end", "tags": [ "Workspaces" ] } } }, "servers": [ { "url": "https://api.forgeling.io/v1" } ], "tags": [ { "description": "Read the app the API key belongs to: its tier, quotas, usage and the key itself.", "name": "App" }, { "description": "Register the endpoints that receive signed events and the endpoint that refreshes run credentials, and inspect or retry deliveries.", "name": "Webhooks" }, { "description": "Publish, list and yank the versions of the agent bundles that runs are created from.", "name": "Bundles" }, { "description": "Create and manage the workspaces your end users work in, and the model credential each uses.", "name": "Workspaces" }, { "description": "Create a run in a workspace, follow it through its life, set its secrets and end it.", "name": "Runs" }, { "description": "Post work to a run, read what came of it and cancel it.", "name": "Turns" }, { "description": "List the tool uses that agents are waiting on, and allow or deny them.", "name": "Approvals" }, { "description": "Read a run's replayable event log or the app-wide feed, or stream a run's events live.", "name": "Events" }, { "description": "List the files a run produced and download them through short-lived signed links.", "name": "Files" }, { "description": "Read the model usage and cost of your app, by day or by run.", "name": "Usage" } ], "webhooks": { "approval.requested": { "post": { "operationId": "webhook_approval_requested", "parameters": [ { "description": "The event id (`evt_...`); `crf_...` for a credential-refresh call. The same on every attempt.", "in": "header", "name": "webhook-id", "required": true, "schema": { "type": "string" } }, { "description": "The time of this attempt, in Unix seconds.", "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "type": "string" } }, { "description": "`v1,` over `..` with the endpoint's secret (the base64 part of `whsec_...`). Two space-separated signatures during the day after a rotation.", "in": "header", "name": "webhook-signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/EventData.approval.requested" }, "type": { "const": "approval.requested" } }, "type": "object" } ] } } }, "required": true }, "responses": { "2XX": { "description": "Received. Any 2xx status acknowledges the event; the body is ignored." }, "410": { "description": "Gone. The endpoint is disabled and receives no more events." }, "default": { "description": "Not received. The delivery is retried on a schedule." } }, "summary": "The approval.requested event", "tags": [ "Webhooks" ] } }, "approval.resolved": { "post": { "operationId": "webhook_approval_resolved", "parameters": [ { "description": "The event id (`evt_...`); `crf_...` for a credential-refresh call. The same on every attempt.", "in": "header", "name": "webhook-id", "required": true, "schema": { "type": "string" } }, { "description": "The time of this attempt, in Unix seconds.", "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "type": "string" } }, { "description": "`v1,` over `..` with the endpoint's secret (the base64 part of `whsec_...`). Two space-separated signatures during the day after a rotation.", "in": "header", "name": "webhook-signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/EventData.approval.resolved" }, "type": { "const": "approval.resolved" } }, "type": "object" } ] } } }, "required": true }, "responses": { "2XX": { "description": "Received. Any 2xx status acknowledges the event; the body is ignored." }, "410": { "description": "Gone. The endpoint is disabled and receives no more events." }, "default": { "description": "Not received. The delivery is retried on a schedule." } }, "summary": "The approval.resolved event", "tags": [ "Webhooks" ] } }, "budget.warning": { "post": { "operationId": "webhook_budget_warning", "parameters": [ { "description": "The event id (`evt_...`); `crf_...` for a credential-refresh call. The same on every attempt.", "in": "header", "name": "webhook-id", "required": true, "schema": { "type": "string" } }, { "description": "The time of this attempt, in Unix seconds.", "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "type": "string" } }, { "description": "`v1,` over `..` with the endpoint's secret (the base64 part of `whsec_...`). Two space-separated signatures during the day after a rotation.", "in": "header", "name": "webhook-signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/EventData.budget.warning" }, "type": { "const": "budget.warning" } }, "type": "object" } ] } } }, "required": true }, "responses": { "2XX": { "description": "Received. Any 2xx status acknowledges the event; the body is ignored." }, "410": { "description": "Gone. The endpoint is disabled and receives no more events." }, "default": { "description": "Not received. The delivery is retried on a schedule." } }, "summary": "The budget.warning event", "tags": [ "Webhooks" ] } }, "bundle.version_ready": { "post": { "operationId": "webhook_bundle_version_ready", "parameters": [ { "description": "The event id (`evt_...`); `crf_...` for a credential-refresh call. The same on every attempt.", "in": "header", "name": "webhook-id", "required": true, "schema": { "type": "string" } }, { "description": "The time of this attempt, in Unix seconds.", "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "type": "string" } }, { "description": "`v1,` over `..` with the endpoint's secret (the base64 part of `whsec_...`). Two space-separated signatures during the day after a rotation.", "in": "header", "name": "webhook-signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/EventData.bundle.version_ready" }, "type": { "const": "bundle.version_ready" } }, "type": "object" } ] } } }, "required": true }, "responses": { "2XX": { "description": "Received. Any 2xx status acknowledges the event; the body is ignored." }, "410": { "description": "Gone. The endpoint is disabled and receives no more events." }, "default": { "description": "Not received. The delivery is retried on a schedule." } }, "summary": "The bundle.version_ready event", "tags": [ "Webhooks" ] } }, "bundle.version_rejected": { "post": { "operationId": "webhook_bundle_version_rejected", "parameters": [ { "description": "The event id (`evt_...`); `crf_...` for a credential-refresh call. The same on every attempt.", "in": "header", "name": "webhook-id", "required": true, "schema": { "type": "string" } }, { "description": "The time of this attempt, in Unix seconds.", "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "type": "string" } }, { "description": "`v1,` over `..` with the endpoint's secret (the base64 part of `whsec_...`). Two space-separated signatures during the day after a rotation.", "in": "header", "name": "webhook-signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/EventData.bundle.version_rejected" }, "type": { "const": "bundle.version_rejected" } }, "type": "object" } ] } } }, "required": true }, "responses": { "2XX": { "description": "Received. Any 2xx status acknowledges the event; the body is ignored." }, "410": { "description": "Gone. The endpoint is disabled and receives no more events." }, "default": { "description": "Not received. The delivery is retried on a schedule." } }, "summary": "The bundle.version_rejected event", "tags": [ "Webhooks" ] } }, "credential.refresh": { "post": { "operationId": "webhook_credential_refresh", "parameters": [ { "description": "The event id (`evt_...`); `crf_...` for a credential-refresh call. The same on every attempt.", "in": "header", "name": "webhook-id", "required": true, "schema": { "type": "string" } }, { "description": "The time of this attempt, in Unix seconds.", "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "type": "string" } }, { "description": "`v1,` over `..` with the endpoint's secret (the base64 part of `whsec_...`). Two space-separated signatures during the day after a rotation.", "in": "header", "name": "webhook-signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialRefreshRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialRefreshResponse" } } }, "description": "The new value of the secret and when it expires." }, "default": { "description": "Not refreshed. The call is retried until the secret expires." } }, "summary": "The credential.refresh call", "tags": [ "Webhooks" ] } }, "message.completed": { "post": { "operationId": "webhook_message_completed", "parameters": [ { "description": "The event id (`evt_...`); `crf_...` for a credential-refresh call. The same on every attempt.", "in": "header", "name": "webhook-id", "required": true, "schema": { "type": "string" } }, { "description": "The time of this attempt, in Unix seconds.", "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "type": "string" } }, { "description": "`v1,` over `..` with the endpoint's secret (the base64 part of `whsec_...`). Two space-separated signatures during the day after a rotation.", "in": "header", "name": "webhook-signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/EventData.message.completed" }, "type": { "const": "message.completed" } }, "type": "object" } ] } } }, "required": true }, "responses": { "2XX": { "description": "Received. Any 2xx status acknowledges the event; the body is ignored." }, "410": { "description": "Gone. The endpoint is disabled and receives no more events." }, "default": { "description": "Not received. The delivery is retried on a schedule." } }, "summary": "The message.completed event", "tags": [ "Webhooks" ] } }, "output.created": { "post": { "operationId": "webhook_output_created", "parameters": [ { "description": "The event id (`evt_...`); `crf_...` for a credential-refresh call. The same on every attempt.", "in": "header", "name": "webhook-id", "required": true, "schema": { "type": "string" } }, { "description": "The time of this attempt, in Unix seconds.", "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "type": "string" } }, { "description": "`v1,` over `..` with the endpoint's secret (the base64 part of `whsec_...`). Two space-separated signatures during the day after a rotation.", "in": "header", "name": "webhook-signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/EventData.output.created" }, "type": { "const": "output.created" } }, "type": "object" } ] } } }, "required": true }, "responses": { "2XX": { "description": "Received. Any 2xx status acknowledges the event; the body is ignored." }, "410": { "description": "Gone. The endpoint is disabled and receives no more events." }, "default": { "description": "Not received. The delivery is retried on a schedule." } }, "summary": "The output.created event", "tags": [ "Webhooks" ] } }, "ping": { "post": { "operationId": "webhook_ping", "parameters": [ { "description": "The event id (`evt_...`); `crf_...` for a credential-refresh call. The same on every attempt.", "in": "header", "name": "webhook-id", "required": true, "schema": { "type": "string" } }, { "description": "The time of this attempt, in Unix seconds.", "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "type": "string" } }, { "description": "`v1,` over `..` with the endpoint's secret (the base64 part of `whsec_...`). Two space-separated signatures during the day after a rotation.", "in": "header", "name": "webhook-signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/EventData.ping" }, "type": { "const": "ping" } }, "type": "object" } ] } } }, "required": true }, "responses": { "2XX": { "description": "Received. Any 2xx status acknowledges the event; the body is ignored." }, "410": { "description": "Gone. The endpoint is disabled and receives no more events." }, "default": { "description": "Not received. The delivery is retried on a schedule." } }, "summary": "The ping event", "tags": [ "Webhooks" ] } }, "run.cancelled": { "post": { "operationId": "webhook_run_cancelled", "parameters": [ { "description": "The event id (`evt_...`); `crf_...` for a credential-refresh call. The same on every attempt.", "in": "header", "name": "webhook-id", "required": true, "schema": { "type": "string" } }, { "description": "The time of this attempt, in Unix seconds.", "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "type": "string" } }, { "description": "`v1,` over `..` with the endpoint's secret (the base64 part of `whsec_...`). Two space-separated signatures during the day after a rotation.", "in": "header", "name": "webhook-signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/EventData.run.cancelled" }, "type": { "const": "run.cancelled" } }, "type": "object" } ] } } }, "required": true }, "responses": { "2XX": { "description": "Received. Any 2xx status acknowledges the event; the body is ignored." }, "410": { "description": "Gone. The endpoint is disabled and receives no more events." }, "default": { "description": "Not received. The delivery is retried on a schedule." } }, "summary": "The run.cancelled event", "tags": [ "Webhooks" ] } }, "run.completed": { "post": { "operationId": "webhook_run_completed", "parameters": [ { "description": "The event id (`evt_...`); `crf_...` for a credential-refresh call. The same on every attempt.", "in": "header", "name": "webhook-id", "required": true, "schema": { "type": "string" } }, { "description": "The time of this attempt, in Unix seconds.", "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "type": "string" } }, { "description": "`v1,` over `..` with the endpoint's secret (the base64 part of `whsec_...`). Two space-separated signatures during the day after a rotation.", "in": "header", "name": "webhook-signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/EventData.run.completed" }, "type": { "const": "run.completed" } }, "type": "object" } ] } } }, "required": true }, "responses": { "2XX": { "description": "Received. Any 2xx status acknowledges the event; the body is ignored." }, "410": { "description": "Gone. The endpoint is disabled and receives no more events." }, "default": { "description": "Not received. The delivery is retried on a schedule." } }, "summary": "The run.completed event", "tags": [ "Webhooks" ] } }, "run.expired": { "post": { "operationId": "webhook_run_expired", "parameters": [ { "description": "The event id (`evt_...`); `crf_...` for a credential-refresh call. The same on every attempt.", "in": "header", "name": "webhook-id", "required": true, "schema": { "type": "string" } }, { "description": "The time of this attempt, in Unix seconds.", "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "type": "string" } }, { "description": "`v1,` over `..` with the endpoint's secret (the base64 part of `whsec_...`). Two space-separated signatures during the day after a rotation.", "in": "header", "name": "webhook-signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/EventData.run.expired" }, "type": { "const": "run.expired" } }, "type": "object" } ] } } }, "required": true }, "responses": { "2XX": { "description": "Received. Any 2xx status acknowledges the event; the body is ignored." }, "410": { "description": "Gone. The endpoint is disabled and receives no more events." }, "default": { "description": "Not received. The delivery is retried on a schedule." } }, "summary": "The run.expired event", "tags": [ "Webhooks" ] } }, "run.failed": { "post": { "operationId": "webhook_run_failed", "parameters": [ { "description": "The event id (`evt_...`); `crf_...` for a credential-refresh call. The same on every attempt.", "in": "header", "name": "webhook-id", "required": true, "schema": { "type": "string" } }, { "description": "The time of this attempt, in Unix seconds.", "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "type": "string" } }, { "description": "`v1,` over `..` with the endpoint's secret (the base64 part of `whsec_...`). Two space-separated signatures during the day after a rotation.", "in": "header", "name": "webhook-signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/EventData.run.failed" }, "type": { "const": "run.failed" } }, "type": "object" } ] } } }, "required": true }, "responses": { "2XX": { "description": "Received. Any 2xx status acknowledges the event; the body is ignored." }, "410": { "description": "Gone. The endpoint is disabled and receives no more events." }, "default": { "description": "Not received. The delivery is retried on a schedule." } }, "summary": "The run.failed event", "tags": [ "Webhooks" ] } }, "run.idle": { "post": { "operationId": "webhook_run_idle", "parameters": [ { "description": "The event id (`evt_...`); `crf_...` for a credential-refresh call. The same on every attempt.", "in": "header", "name": "webhook-id", "required": true, "schema": { "type": "string" } }, { "description": "The time of this attempt, in Unix seconds.", "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "type": "string" } }, { "description": "`v1,` over `..` with the endpoint's secret (the base64 part of `whsec_...`). Two space-separated signatures during the day after a rotation.", "in": "header", "name": "webhook-signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/EventData.run.idle" }, "type": { "const": "run.idle" } }, "type": "object" } ] } } }, "required": true }, "responses": { "2XX": { "description": "Received. Any 2xx status acknowledges the event; the body is ignored." }, "410": { "description": "Gone. The endpoint is disabled and receives no more events." }, "default": { "description": "Not received. The delivery is retried on a schedule." } }, "summary": "The run.idle event", "tags": [ "Webhooks" ] } }, "run.provisioning": { "post": { "operationId": "webhook_run_provisioning", "parameters": [ { "description": "The event id (`evt_...`); `crf_...` for a credential-refresh call. The same on every attempt.", "in": "header", "name": "webhook-id", "required": true, "schema": { "type": "string" } }, { "description": "The time of this attempt, in Unix seconds.", "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "type": "string" } }, { "description": "`v1,` over `..` with the endpoint's secret (the base64 part of `whsec_...`). Two space-separated signatures during the day after a rotation.", "in": "header", "name": "webhook-signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/EventData.run.provisioning" }, "type": { "const": "run.provisioning" } }, "type": "object" } ] } } }, "required": true }, "responses": { "2XX": { "description": "Received. Any 2xx status acknowledges the event; the body is ignored." }, "410": { "description": "Gone. The endpoint is disabled and receives no more events." }, "default": { "description": "Not received. The delivery is retried on a schedule." } }, "summary": "The run.provisioning event", "tags": [ "Webhooks" ] } }, "run.queued": { "post": { "operationId": "webhook_run_queued", "parameters": [ { "description": "The event id (`evt_...`); `crf_...` for a credential-refresh call. The same on every attempt.", "in": "header", "name": "webhook-id", "required": true, "schema": { "type": "string" } }, { "description": "The time of this attempt, in Unix seconds.", "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "type": "string" } }, { "description": "`v1,` over `..` with the endpoint's secret (the base64 part of `whsec_...`). Two space-separated signatures during the day after a rotation.", "in": "header", "name": "webhook-signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/EventData.run.queued" }, "type": { "const": "run.queued" } }, "type": "object" } ] } } }, "required": true }, "responses": { "2XX": { "description": "Received. Any 2xx status acknowledges the event; the body is ignored." }, "410": { "description": "Gone. The endpoint is disabled and receives no more events." }, "default": { "description": "Not received. The delivery is retried on a schedule." } }, "summary": "The run.queued event", "tags": [ "Webhooks" ] } }, "run.ready": { "post": { "operationId": "webhook_run_ready", "parameters": [ { "description": "The event id (`evt_...`); `crf_...` for a credential-refresh call. The same on every attempt.", "in": "header", "name": "webhook-id", "required": true, "schema": { "type": "string" } }, { "description": "The time of this attempt, in Unix seconds.", "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "type": "string" } }, { "description": "`v1,` over `..` with the endpoint's secret (the base64 part of `whsec_...`). Two space-separated signatures during the day after a rotation.", "in": "header", "name": "webhook-signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/EventData.run.ready" }, "type": { "const": "run.ready" } }, "type": "object" } ] } } }, "required": true }, "responses": { "2XX": { "description": "Received. Any 2xx status acknowledges the event; the body is ignored." }, "410": { "description": "Gone. The endpoint is disabled and receives no more events." }, "default": { "description": "Not received. The delivery is retried on a schedule." } }, "summary": "The run.ready event", "tags": [ "Webhooks" ] } }, "run.resumed": { "post": { "operationId": "webhook_run_resumed", "parameters": [ { "description": "The event id (`evt_...`); `crf_...` for a credential-refresh call. The same on every attempt.", "in": "header", "name": "webhook-id", "required": true, "schema": { "type": "string" } }, { "description": "The time of this attempt, in Unix seconds.", "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "type": "string" } }, { "description": "`v1,` over `..` with the endpoint's secret (the base64 part of `whsec_...`). Two space-separated signatures during the day after a rotation.", "in": "header", "name": "webhook-signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/EventData.run.resumed" }, "type": { "const": "run.resumed" } }, "type": "object" } ] } } }, "required": true }, "responses": { "2XX": { "description": "Received. Any 2xx status acknowledges the event; the body is ignored." }, "410": { "description": "Gone. The endpoint is disabled and receives no more events." }, "default": { "description": "Not received. The delivery is retried on a schedule." } }, "summary": "The run.resumed event", "tags": [ "Webhooks" ] } }, "run.running": { "post": { "operationId": "webhook_run_running", "parameters": [ { "description": "The event id (`evt_...`); `crf_...` for a credential-refresh call. The same on every attempt.", "in": "header", "name": "webhook-id", "required": true, "schema": { "type": "string" } }, { "description": "The time of this attempt, in Unix seconds.", "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "type": "string" } }, { "description": "`v1,` over `..` with the endpoint's secret (the base64 part of `whsec_...`). Two space-separated signatures during the day after a rotation.", "in": "header", "name": "webhook-signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/EventData.run.running" }, "type": { "const": "run.running" } }, "type": "object" } ] } } }, "required": true }, "responses": { "2XX": { "description": "Received. Any 2xx status acknowledges the event; the body is ignored." }, "410": { "description": "Gone. The endpoint is disabled and receives no more events." }, "default": { "description": "Not received. The delivery is retried on a schedule." } }, "summary": "The run.running event", "tags": [ "Webhooks" ] } }, "run.suspended": { "post": { "operationId": "webhook_run_suspended", "parameters": [ { "description": "The event id (`evt_...`); `crf_...` for a credential-refresh call. The same on every attempt.", "in": "header", "name": "webhook-id", "required": true, "schema": { "type": "string" } }, { "description": "The time of this attempt, in Unix seconds.", "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "type": "string" } }, { "description": "`v1,` over `..` with the endpoint's secret (the base64 part of `whsec_...`). Two space-separated signatures during the day after a rotation.", "in": "header", "name": "webhook-signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/EventData.run.suspended" }, "type": { "const": "run.suspended" } }, "type": "object" } ] } } }, "required": true }, "responses": { "2XX": { "description": "Received. Any 2xx status acknowledges the event; the body is ignored." }, "410": { "description": "Gone. The endpoint is disabled and receives no more events." }, "default": { "description": "Not received. The delivery is retried on a schedule." } }, "summary": "The run.suspended event", "tags": [ "Webhooks" ] } }, "secret.refresh_failed": { "post": { "operationId": "webhook_secret_refresh_failed", "parameters": [ { "description": "The event id (`evt_...`); `crf_...` for a credential-refresh call. The same on every attempt.", "in": "header", "name": "webhook-id", "required": true, "schema": { "type": "string" } }, { "description": "The time of this attempt, in Unix seconds.", "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "type": "string" } }, { "description": "`v1,` over `..` with the endpoint's secret (the base64 part of `whsec_...`). Two space-separated signatures during the day after a rotation.", "in": "header", "name": "webhook-signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/EventData.secret.refresh_failed" }, "type": { "const": "secret.refresh_failed" } }, "type": "object" } ] } } }, "required": true }, "responses": { "2XX": { "description": "Received. Any 2xx status acknowledges the event; the body is ignored." }, "410": { "description": "Gone. The endpoint is disabled and receives no more events." }, "default": { "description": "Not received. The delivery is retried on a schedule." } }, "summary": "The secret.refresh_failed event", "tags": [ "Webhooks" ] } }, "tool.completed": { "post": { "operationId": "webhook_tool_completed", "parameters": [ { "description": "The event id (`evt_...`); `crf_...` for a credential-refresh call. The same on every attempt.", "in": "header", "name": "webhook-id", "required": true, "schema": { "type": "string" } }, { "description": "The time of this attempt, in Unix seconds.", "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "type": "string" } }, { "description": "`v1,` over `..` with the endpoint's secret (the base64 part of `whsec_...`). Two space-separated signatures during the day after a rotation.", "in": "header", "name": "webhook-signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/EventData.tool.completed" }, "type": { "const": "tool.completed" } }, "type": "object" } ] } } }, "required": true }, "responses": { "2XX": { "description": "Received. Any 2xx status acknowledges the event; the body is ignored." }, "410": { "description": "Gone. The endpoint is disabled and receives no more events." }, "default": { "description": "Not received. The delivery is retried on a schedule." } }, "summary": "The tool.completed event", "tags": [ "Webhooks" ] } }, "tool.started": { "post": { "operationId": "webhook_tool_started", "parameters": [ { "description": "The event id (`evt_...`); `crf_...` for a credential-refresh call. The same on every attempt.", "in": "header", "name": "webhook-id", "required": true, "schema": { "type": "string" } }, { "description": "The time of this attempt, in Unix seconds.", "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "type": "string" } }, { "description": "`v1,` over `..` with the endpoint's secret (the base64 part of `whsec_...`). Two space-separated signatures during the day after a rotation.", "in": "header", "name": "webhook-signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/EventData.tool.started" }, "type": { "const": "tool.started" } }, "type": "object" } ] } } }, "required": true }, "responses": { "2XX": { "description": "Received. Any 2xx status acknowledges the event; the body is ignored." }, "410": { "description": "Gone. The endpoint is disabled and receives no more events." }, "default": { "description": "Not received. The delivery is retried on a schedule." } }, "summary": "The tool.started event", "tags": [ "Webhooks" ] } }, "turn.cancelled": { "post": { "operationId": "webhook_turn_cancelled", "parameters": [ { "description": "The event id (`evt_...`); `crf_...` for a credential-refresh call. The same on every attempt.", "in": "header", "name": "webhook-id", "required": true, "schema": { "type": "string" } }, { "description": "The time of this attempt, in Unix seconds.", "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "type": "string" } }, { "description": "`v1,` over `..` with the endpoint's secret (the base64 part of `whsec_...`). Two space-separated signatures during the day after a rotation.", "in": "header", "name": "webhook-signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/EventData.turn.cancelled" }, "type": { "const": "turn.cancelled" } }, "type": "object" } ] } } }, "required": true }, "responses": { "2XX": { "description": "Received. Any 2xx status acknowledges the event; the body is ignored." }, "410": { "description": "Gone. The endpoint is disabled and receives no more events." }, "default": { "description": "Not received. The delivery is retried on a schedule." } }, "summary": "The turn.cancelled event", "tags": [ "Webhooks" ] } }, "turn.completed": { "post": { "operationId": "webhook_turn_completed", "parameters": [ { "description": "The event id (`evt_...`); `crf_...` for a credential-refresh call. The same on every attempt.", "in": "header", "name": "webhook-id", "required": true, "schema": { "type": "string" } }, { "description": "The time of this attempt, in Unix seconds.", "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "type": "string" } }, { "description": "`v1,` over `..` with the endpoint's secret (the base64 part of `whsec_...`). Two space-separated signatures during the day after a rotation.", "in": "header", "name": "webhook-signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/EventData.turn.completed" }, "type": { "const": "turn.completed" } }, "type": "object" } ] } } }, "required": true }, "responses": { "2XX": { "description": "Received. Any 2xx status acknowledges the event; the body is ignored." }, "410": { "description": "Gone. The endpoint is disabled and receives no more events." }, "default": { "description": "Not received. The delivery is retried on a schedule." } }, "summary": "The turn.completed event", "tags": [ "Webhooks" ] } }, "turn.failed": { "post": { "operationId": "webhook_turn_failed", "parameters": [ { "description": "The event id (`evt_...`); `crf_...` for a credential-refresh call. The same on every attempt.", "in": "header", "name": "webhook-id", "required": true, "schema": { "type": "string" } }, { "description": "The time of this attempt, in Unix seconds.", "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "type": "string" } }, { "description": "`v1,` over `..` with the endpoint's secret (the base64 part of `whsec_...`). Two space-separated signatures during the day after a rotation.", "in": "header", "name": "webhook-signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/EventData.turn.failed" }, "type": { "const": "turn.failed" } }, "type": "object" } ] } } }, "required": true }, "responses": { "2XX": { "description": "Received. Any 2xx status acknowledges the event; the body is ignored." }, "410": { "description": "Gone. The endpoint is disabled and receives no more events." }, "default": { "description": "Not received. The delivery is retried on a schedule." } }, "summary": "The turn.failed event", "tags": [ "Webhooks" ] } }, "turn.interrupted": { "post": { "operationId": "webhook_turn_interrupted", "parameters": [ { "description": "The event id (`evt_...`); `crf_...` for a credential-refresh call. The same on every attempt.", "in": "header", "name": "webhook-id", "required": true, "schema": { "type": "string" } }, { "description": "The time of this attempt, in Unix seconds.", "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "type": "string" } }, { "description": "`v1,` over `..` with the endpoint's secret (the base64 part of `whsec_...`). Two space-separated signatures during the day after a rotation.", "in": "header", "name": "webhook-signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/EventData.turn.interrupted" }, "type": { "const": "turn.interrupted" } }, "type": "object" } ] } } }, "required": true }, "responses": { "2XX": { "description": "Received. Any 2xx status acknowledges the event; the body is ignored." }, "410": { "description": "Gone. The endpoint is disabled and receives no more events." }, "default": { "description": "Not received. The delivery is retried on a schedule." } }, "summary": "The turn.interrupted event", "tags": [ "Webhooks" ] } }, "turn.queued": { "post": { "operationId": "webhook_turn_queued", "parameters": [ { "description": "The event id (`evt_...`); `crf_...` for a credential-refresh call. The same on every attempt.", "in": "header", "name": "webhook-id", "required": true, "schema": { "type": "string" } }, { "description": "The time of this attempt, in Unix seconds.", "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "type": "string" } }, { "description": "`v1,` over `..` with the endpoint's secret (the base64 part of `whsec_...`). Two space-separated signatures during the day after a rotation.", "in": "header", "name": "webhook-signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/EventData.turn.queued" }, "type": { "const": "turn.queued" } }, "type": "object" } ] } } }, "required": true }, "responses": { "2XX": { "description": "Received. Any 2xx status acknowledges the event; the body is ignored." }, "410": { "description": "Gone. The endpoint is disabled and receives no more events." }, "default": { "description": "Not received. The delivery is retried on a schedule." } }, "summary": "The turn.queued event", "tags": [ "Webhooks" ] } }, "turn.started": { "post": { "operationId": "webhook_turn_started", "parameters": [ { "description": "The event id (`evt_...`); `crf_...` for a credential-refresh call. The same on every attempt.", "in": "header", "name": "webhook-id", "required": true, "schema": { "type": "string" } }, { "description": "The time of this attempt, in Unix seconds.", "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "type": "string" } }, { "description": "`v1,` over `..` with the endpoint's secret (the base64 part of `whsec_...`). Two space-separated signatures during the day after a rotation.", "in": "header", "name": "webhook-signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/EventData.turn.started" }, "type": { "const": "turn.started" } }, "type": "object" } ] } } }, "required": true }, "responses": { "2XX": { "description": "Received. Any 2xx status acknowledges the event; the body is ignored." }, "410": { "description": "Gone. The endpoint is disabled and receives no more events." }, "default": { "description": "Not received. The delivery is retried on a schedule." } }, "summary": "The turn.started event", "tags": [ "Webhooks" ] } }, "workspace.credential_invalid": { "post": { "operationId": "webhook_workspace_credential_invalid", "parameters": [ { "description": "The event id (`evt_...`); `crf_...` for a credential-refresh call. The same on every attempt.", "in": "header", "name": "webhook-id", "required": true, "schema": { "type": "string" } }, { "description": "The time of this attempt, in Unix seconds.", "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "type": "string" } }, { "description": "`v1,` over `..` with the endpoint's secret (the base64 part of `whsec_...`). Two space-separated signatures during the day after a rotation.", "in": "header", "name": "webhook-signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/EventData.workspace.credential_invalid" }, "type": { "const": "workspace.credential_invalid" } }, "type": "object" } ] } } }, "required": true }, "responses": { "2XX": { "description": "Received. Any 2xx status acknowledges the event; the body is ignored." }, "410": { "description": "Gone. The endpoint is disabled and receives no more events." }, "default": { "description": "Not received. The delivery is retried on a schedule." } }, "summary": "The workspace.credential_invalid event", "tags": [ "Webhooks" ] } } } }