{ "components": { "schemas": { "CallbackDeliveryEnvelope": { "$schema": "https://json-schema.org/draft/2020-12/schema", "oneOf": [ { "type": "object", "properties": { "attempt": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "data": {}, "occurrenceId": { "type": "string", "pattern": "^occ_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "plannedFor": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "scheduleId": { "type": "string", "pattern": "^sch_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "type": { "type": "string", "const": "schedule.occurrence" }, "version": { "type": "string", "const": "2026-07-01" } }, "required": [ "attempt", "data", "occurrenceId", "plannedFor", "scheduleId", "type", "version" ] }, { "type": "object", "properties": { "attempt": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "data": {}, "occurrenceId": { "type": "string", "pattern": "^occ_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "plannedFor": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "scheduleId": { "type": "string", "pattern": "^sch_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "type": { "type": "string", "const": "schedule.occurrence" }, "completion": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1 }, "url": { "type": "string", "format": "uri" } }, "required": ["token", "url"] }, "trigger": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "automatic" } }, "required": ["kind"] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "redelivery" }, "sourceAttemptId": { "type": "string", "pattern": "^att_[0-9abcdefghjkmnpqrstvwxyz]{26}$" } }, "required": ["kind", "sourceAttemptId"] } ] }, "version": { "type": "string", "const": "2026-08-08" } }, "required": [ "attempt", "data", "occurrenceId", "plannedFor", "scheduleId", "type", "trigger", "version" ] }, { "type": "object", "properties": { "attempt": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "data": {}, "occurrenceId": { "type": "string", "pattern": "^occ_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "plannedFor": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "scheduleId": { "type": "string", "pattern": "^sch_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "type": { "type": "string", "const": "schedule.occurrence" }, "completion": { "type": "object", "properties": { "deadline": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "token": { "type": "string", "minLength": 1 }, "url": { "type": "string", "format": "uri" } }, "required": ["deadline", "token", "url"] }, "trigger": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "automatic" } }, "required": ["kind"] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "redelivery" }, "sourceAttemptId": { "type": "string", "pattern": "^att_[0-9abcdefghjkmnpqrstvwxyz]{26}$" } }, "required": ["kind", "sourceAttemptId"] } ] }, "version": { "type": "string", "const": "2026-08-23" } }, "required": [ "attempt", "data", "occurrenceId", "plannedFor", "scheduleId", "type", "completion", "trigger", "version" ] } ] } }, "securitySchemes": { "apiCredential": { "description": "Scoped API credential bound to one organization, project, and environment.", "scheme": "bearer", "type": "http" }, "memberSession": { "description": "A signed-in member's session token. Unlike a credential or an access token it carries no project or environment, so a request using it must also send the two headers below.", "scheme": "bearer", "type": "http" }, "memberSessionEnvironment": { "description": "Which environment of that project the request acts in: `test` or `live`.", "in": "header", "name": "Greatwait-Environment", "type": "apiKey" }, "memberSessionProject": { "description": "Which project in the member's organization the request acts in. Checked against that organization; a project belonging to another answers exactly as one that does not exist.", "in": "header", "name": "Greatwait-Project", "type": "apiKey" } } }, "info": { "description": "Generated from packages/contracts. Do not edit. This document describes the Greatwait API. NOTE: Zod refinements do not survive JSON Schema conversion, so a described schema is weaker than the one the service enforces — it accepts any string where the service requires a canonical IANA timezone or a real calendar date. Response schemas are described in output mode and request schemas in input mode. The contracts package is the validation authority in both directions.", "title": "Greatwait V1", "version": "2026-08-22" }, "openapi": "3.1.0", "paths": { "/v1/exports": { "post": { "description": "Starts an export for the authenticated project and environment. Records created or planned after cutoffAt are excluded; mutable fields have their current value when each part is read. Authority comes from the verified principal; no scope fields are accepted in the body.", "operationId": "exports.create", "parameters": [], "responses": { "201": { "content": { "application/json": { "example": { "createdAt": "2035-03-04T12:00:00.000Z", "consistency": "creation-cutoff-current-values", "cutoffAt": "2035-03-04T12:00:00.000Z", "id": "exp_0123456789abcdefghjkmnpqrs", "state": "active", "updatedAt": "2035-03-04T12:00:00.000Z" }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "createdAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "consistency": { "type": "string", "const": "creation-cutoff-current-values" }, "cutoffAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "id": { "type": "string", "pattern": "^exp_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "state": { "type": "string", "enum": ["active", "complete", "cancelled"] }, "updatedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, "required": [ "createdAt", "consistency", "cutoffAt", "id", "state", "updatedAt" ] } } }, "description": "Create a data export" }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "plan_limit_reached", "project_archived", "state_conflict" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: plan_limit_reached, project_archived, state_conflict." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Create a data export", "security": [ { "apiCredential": ["schedules:read", "endpoints:read"] }, { "memberSession": ["schedules:read", "endpoints:read"], "memberSessionEnvironment": [], "memberSessionProject": [] } ], "requestBody": { "content": { "application/json": { "example": {}, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } } }, "required": false } } }, "/v1/exports/{exportId}": { "get": { "description": "Reads export progress inside the authenticated authority tuple.", "operationId": "exports.read", "parameters": [ { "in": "path", "name": "exportId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "createdAt": "2035-03-04T12:00:00.000Z", "consistency": "creation-cutoff-current-values", "cutoffAt": "2035-03-04T12:00:00.000Z", "id": "exp_0123456789abcdefghjkmnpqrs", "state": "active", "updatedAt": "2035-03-04T12:00:00.000Z" }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "createdAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "consistency": { "type": "string", "const": "creation-cutoff-current-values" }, "cutoffAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "id": { "type": "string", "pattern": "^exp_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "state": { "type": "string", "enum": ["active", "complete", "cancelled"] }, "updatedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, "required": [ "createdAt", "consistency", "cutoffAt", "id", "state", "updatedAt" ] } } }, "description": "Read a data export" }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "404": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["not_found"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: not_found." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["project_archived", "state_conflict"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: project_archived, state_conflict." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Read a data export", "security": [ { "apiCredential": ["schedules:read", "endpoints:read"] }, { "memberSession": ["schedules:read", "endpoints:read"], "memberSessionEnvironment": [], "memberSessionProject": [] } ] } }, "/v1/exports/{exportId}/parts": { "get": { "description": "Returns one bounded NDJSON file part. Cursors are opaque, authenticated, and bound to this export job.", "operationId": "exports.part", "parameters": [ { "in": "path", "name": "exportId", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "content": { "application/json": { "example": { "content": "{\"kind\":\"schedule\",\"value\":{\"id\":\"sch_0123456789abcdefghjkmnpq\"}}\n", "fileName": "greatwait-export-exp_0123456789abcdefghjkmnpqrs.ndjson", "mediaType": "application/x-ndjson" }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "content": { "type": "string" }, "fileName": { "type": "string", "pattern": "^greatwait-export-exp_[0-9abcdefghjkmnpqrstvwxyz]{26}\\.ndjson$" }, "mediaType": { "type": "string", "const": "application/x-ndjson" }, "nextCursor": { "type": "string", "minLength": 1 } }, "required": ["content", "fileName", "mediaType"] } } }, "description": "Download a data export part" }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "404": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["not_found"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: not_found." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["project_archived", "state_conflict"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: project_archived, state_conflict." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Download a data export part", "security": [ { "apiCredential": ["schedules:read", "endpoints:read"] }, { "memberSession": ["schedules:read", "endpoints:read"], "memberSessionEnvironment": [], "memberSessionProject": [] } ] } }, "/v1/exports/{exportId}/cancel": { "post": { "description": "Permanently cancels an export job. Repeating cancellation is safe and cancelled jobs cannot serve file parts.", "operationId": "exports.cancel", "parameters": [ { "in": "path", "name": "exportId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "cancelled": true, "export": { "createdAt": "2035-03-04T12:00:00.000Z", "consistency": "creation-cutoff-current-values", "cutoffAt": "2035-03-04T12:00:00.000Z", "id": "exp_0123456789abcdefghjkmnpqrs", "state": "cancelled", "updatedAt": "2035-03-04T12:00:00.000Z" } }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cancelled": { "type": "boolean", "const": true }, "export": { "type": "object", "properties": { "createdAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "consistency": { "type": "string", "const": "creation-cutoff-current-values" }, "cutoffAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "id": { "type": "string", "pattern": "^exp_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "state": { "type": "string", "enum": ["active", "complete", "cancelled"] }, "updatedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, "required": [ "createdAt", "consistency", "cutoffAt", "id", "state", "updatedAt" ] } }, "required": ["cancelled", "export"] } } }, "description": "Cancel a data export" }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "404": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["not_found"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: not_found." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["project_archived", "state_conflict"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: project_archived, state_conflict." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Cancel a data export", "security": [ { "apiCredential": ["schedules:read", "endpoints:read"] }, { "memberSession": ["schedules:read", "endpoints:read"], "memberSessionEnvironment": [], "memberSessionProject": [] } ] } }, "/v1/organization/lifecycle": { "get": { "description": "Reads the signed-in administrator's organization closure generation and progress, including the reversible window. It remains available during closure so the administrator can request recovery.", "operationId": "organizations.lifecycle", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "organizationId": "org_01h8xyz9k2m4n6p8r0t2v4w6y8", "generation": 1, "phase": "closed", "requestedAt": "2026-09-12T12:00:00.000Z", "reversibleUntil": "2026-09-19T12:00:00.000Z", "purgeDeadline": "2026-10-12T12:00:00.000Z", "immediate": false, "converged": true }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "pattern": "^org_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "generation": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "phase": { "type": "string", "enum": [ "active", "closing", "closed", "restoring", "purging", "erased" ] }, "requestedAt": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, { "type": "null" } ] }, "reversibleUntil": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, { "type": "null" } ] }, "purgeDeadline": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, { "type": "null" } ] }, "immediate": { "type": "boolean" }, "converged": { "type": "boolean" } }, "required": [ "organizationId", "generation", "phase", "requestedAt", "reversibleUntil", "purgeDeadline", "immediate", "converged" ] } } }, "description": "Read organization closure progress" }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "404": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["not_found"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: not_found." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Read organization closure progress", "security": [ { "memberSession": ["projects:administer"] } ] } }, "/v1/organization/close": { "post": { "description": "Stops customer access, execution and new purchases across the organization. Ordinary closure can be reversed for seven days; immediate erasure skips that window. Non-financial erasure completes within thirty days unless suspended by an operator legal hold. Financial records remain under the configured retention policy. An interrupted request resumes under the same generation; closure is acknowledged only after every configured scheduling shard is fenced.", "operationId": "organizations.close", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "organizationId": "org_01h8xyz9k2m4n6p8r0t2v4w6y8", "generation": 1, "phase": "closed", "requestedAt": "2026-09-12T12:00:00.000Z", "reversibleUntil": "2026-09-19T12:00:00.000Z", "purgeDeadline": "2026-10-12T12:00:00.000Z", "immediate": false, "converged": true }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "pattern": "^org_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "generation": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "phase": { "type": "string", "enum": [ "active", "closing", "closed", "restoring", "purging", "erased" ] }, "requestedAt": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, { "type": "null" } ] }, "reversibleUntil": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, { "type": "null" } ] }, "purgeDeadline": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, { "type": "null" } ] }, "immediate": { "type": "boolean" }, "converged": { "type": "boolean" } }, "required": [ "organizationId", "generation", "phase", "requestedAt", "reversibleUntil", "purgeDeadline", "immediate", "converged" ] } } }, "description": "Close the organization and request erasure" }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "404": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["not_found"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: not_found." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["state_conflict", "version_conflict"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: state_conflict, version_conflict." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Close the organization and request erasure", "security": [ { "memberSession": ["projects:administer"] } ], "requestBody": { "content": { "application/json": { "example": { "expectedGeneration": 0, "immediate": false, "confirmation": "delete organization" }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "expectedGeneration": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "immediate": { "type": "boolean" }, "confirmation": { "type": "string", "const": "delete organization" } }, "required": ["expectedGeneration", "immediate", "confirmation"], "additionalProperties": false } } }, "required": true } } }, "/v1/organization/restore": { "post": { "description": "Restores access after every configured scheduling shard acknowledges the new generation. Immediate erasure and expired reversible windows cannot be restored. Recovery preserves each schedule's pause and lateness policy and does not reauthorize automatic top-up.", "operationId": "organizations.restore", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "organizationId": "org_01h8xyz9k2m4n6p8r0t2v4w6y8", "generation": 2, "phase": "active", "requestedAt": "2026-09-12T12:00:00.000Z", "reversibleUntil": "2026-09-19T12:00:00.000Z", "purgeDeadline": "2026-10-12T12:00:00.000Z", "immediate": false, "converged": true }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "pattern": "^org_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "generation": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "phase": { "type": "string", "enum": [ "active", "closing", "closed", "restoring", "purging", "erased" ] }, "requestedAt": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, { "type": "null" } ] }, "reversibleUntil": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, { "type": "null" } ] }, "purgeDeadline": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, { "type": "null" } ] }, "immediate": { "type": "boolean" }, "converged": { "type": "boolean" } }, "required": [ "organizationId", "generation", "phase", "requestedAt", "reversibleUntil", "purgeDeadline", "immediate", "converged" ] } } }, "description": "Cancel organization erasure during its reversible window" }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "404": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["not_found"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: not_found." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["state_conflict", "version_conflict"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: state_conflict, version_conflict." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Cancel organization erasure during its reversible window", "security": [ { "memberSession": ["projects:administer"] } ], "requestBody": { "content": { "application/json": { "example": { "expectedGeneration": 1 }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "expectedGeneration": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": ["expectedGeneration"], "additionalProperties": false } } }, "required": true } } }, "/__greatwait/version": { "get": { "description": "Reports the service, environment, and build the request reached. Unauthenticated: it carries no customer data and is used by canaries and deployment smoke checks.", "operationId": "meta.version", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "buildSha": "9f2c1ab", "environment": "development", "service": "@greatwait/api" }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "buildSha": { "type": "string", "minLength": 1 }, "environment": { "type": "string", "minLength": 1 }, "service": { "type": "string", "minLength": 1 } }, "required": ["buildSha", "environment", "service"] } } }, "description": "Read the deployed version" }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Read the deployed version" } }, "/_scaffold": { "get": { "description": "Reports the workspace layer this service occupies and the layers it may depend on. Exists so the architecture boundary is observable at runtime, not only at build time.", "operationId": "meta.scaffold", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "dependsOn": ["application", "contract", "platform"], "layer": "adapter", "service": "@greatwait/api" }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "dependsOn": { "type": "array", "items": { "type": "string", "enum": [ "contract", "platform", "domain", "application", "adapter", "test-support" ] } }, "layer": { "type": "string", "enum": [ "contract", "platform", "domain", "application", "adapter", "test-support" ] }, "service": { "type": "string", "minLength": 1 } }, "required": ["dependsOn", "layer", "service"] } } }, "description": "Read the workspace scaffold" }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Read the workspace scaffold" } }, "/v1/endpoints": { "post": { "description": "Creates a reusable callback endpoint in the caller's project and environment. The destination must be HTTPS on effective port 443, contain no URL credentials or fragment, and resolve only to public unicast addresses. The endpoint is active and usable the moment it exists; there is nothing to verify. A disabled endpoint is never delivered to, and a schedule write naming one answers not_found, because disabling is terminal rather than a state to recover from. The per-endpoint secret is returned in this response and nowhere else. The 50-record safety ceiling includes disabled endpoints because they remain readable for audit.", "operationId": "endpoints.create", "parameters": [], "responses": { "201": { "content": { "application/json": { "example": { "createdAt": "2026-08-05T15:00:00.000Z", "environmentKind": "test", "id": "ep_01h8xyz9k2m4n6p8r0t2v4w6y8", "project": "proj_01h8xyz9k2m4n6p8r0t2v4w6y8", "signingKeys": { "current": "csk_01h8xyz9k2m4n6p8r0t2v4w6y8" }, "status": "active", "updatedAt": "2026-08-05T15:00:00.000Z", "url": "https://hooks.example.com/greatwait", "version": 1, "keyId": "csk_01h8xyz9k2m4n6p8r0t2v4w6y8", "secret": "ptsk_test_", "shownOnce": true }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "createdAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "disabledAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "environmentKind": { "type": "string", "enum": ["test", "live"] }, "id": { "type": "string", "pattern": "^ep_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 2048 }, "project": { "type": "string", "pattern": "^proj_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "signingKeys": { "type": "object", "properties": { "current": { "type": "string", "pattern": "^csk_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "next": { "type": "object", "properties": { "acknowledgedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "id": { "type": "string", "pattern": "^csk_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "overlapEndsAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, "required": ["id", "overlapEndsAt"] } }, "required": ["current"] }, "status": { "type": "string", "enum": ["active", "disabled"] }, "updatedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "url": { "type": "string", "format": "uri" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "keyId": { "type": "string", "pattern": "^csk_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "secret": { "type": "string", "minLength": 1 }, "shownOnce": { "type": "boolean", "const": true } }, "required": [ "createdAt", "environmentKind", "id", "project", "signingKeys", "status", "updatedAt", "url", "version", "keyId", "secret", "shownOnce" ] } } }, "description": "Create a callback endpoint" }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "plan_limit_reached", "project_archived", "state_conflict" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: plan_limit_reached, project_archived, state_conflict." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Create a callback endpoint", "security": [ { "apiCredential": ["endpoints:write"] }, { "memberSession": ["endpoints:write"], "memberSessionEnvironment": [], "memberSessionProject": [] } ], "requestBody": { "content": { "application/json": { "example": { "url": "https://hooks.example.com/greatwait" }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 2048 }, "url": { "type": "string", "maxLength": 2048, "format": "uri" } }, "required": ["url"] } } }, "required": true } }, "get": { "description": "Lists the caller's callback endpoints for exactly its own project and environment. The result is authoritative and metadata-only: no signing secret or sealed key material has a field in this shape.", "operationId": "endpoints.list", "parameters": [ { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "createdAt": "2026-08-05T15:00:00.000Z", "environmentKind": "test", "id": "ep_01h8xyz9k2m4n6p8r0t2v4w6y8", "project": "proj_01h8xyz9k2m4n6p8r0t2v4w6y8", "signingKeys": { "current": "csk_01h8xyz9k2m4n6p8r0t2v4w6y8" }, "status": "active", "updatedAt": "2026-08-05T15:01:00.000Z", "url": "https://hooks.example.com/greatwait", "version": 2 } ], "freshness": { "kind": "authoritative" } }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "createdAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "disabledAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "environmentKind": { "type": "string", "enum": ["test", "live"] }, "id": { "type": "string", "pattern": "^ep_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 2048 }, "project": { "type": "string", "pattern": "^proj_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "signingKeys": { "type": "object", "properties": { "current": { "type": "string", "pattern": "^csk_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "next": { "type": "object", "properties": { "acknowledgedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "id": { "type": "string", "pattern": "^csk_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "overlapEndsAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, "required": ["id", "overlapEndsAt"] } }, "required": ["current"] }, "status": { "type": "string", "enum": ["active", "disabled"] }, "updatedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "url": { "type": "string", "format": "uri" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "createdAt", "environmentKind", "id", "project", "signingKeys", "status", "updatedAt", "url", "version" ] } }, "freshness": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "authoritative" } }, "required": ["kind"] }, { "type": "object", "properties": { "asOf": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "kind": { "type": "string", "const": "projected" }, "lagSeconds": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["asOf", "kind", "lagSeconds"] } ] }, "nextCursor": { "type": "string", "minLength": 1 } }, "required": ["data", "freshness"] } } }, "description": "List callback endpoints" }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["project_archived"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: project_archived." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "List callback endpoints", "security": [ { "apiCredential": ["endpoints:read"] }, { "memberSession": ["endpoints:read"], "memberSessionEnvironment": [], "memberSessionProject": [] } ] } }, "/v1/endpoints/{endpointId}": { "get": { "description": "Reads one callback endpoint from the caller's own project and environment. A well-formed identifier belonging to another authority is indistinguishable from an absent endpoint, and the response never contains secret material.", "operationId": "endpoints.read", "parameters": [ { "in": "path", "name": "endpointId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "createdAt": "2026-08-05T15:00:00.000Z", "environmentKind": "test", "id": "ep_01h8xyz9k2m4n6p8r0t2v4w6y8", "name": "https://hooks.example.com/greatwait", "project": "proj_01h8xyz9k2m4n6p8r0t2v4w6y8", "signingKeys": { "current": "csk_01h8xyz9k2m4n6p8r0t2v4w6y8" }, "status": "active", "updatedAt": "2026-08-05T15:01:00.000Z", "url": "https://hooks.example.com/greatwait", "version": 2 }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "createdAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "disabledAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "environmentKind": { "type": "string", "enum": ["test", "live"] }, "id": { "type": "string", "pattern": "^ep_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 2048 }, "project": { "type": "string", "pattern": "^proj_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "signingKeys": { "type": "object", "properties": { "current": { "type": "string", "pattern": "^csk_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "next": { "type": "object", "properties": { "acknowledgedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "id": { "type": "string", "pattern": "^csk_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "overlapEndsAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, "required": ["id", "overlapEndsAt"] } }, "required": ["current"] }, "status": { "type": "string", "enum": ["active", "disabled"] }, "updatedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "url": { "type": "string", "format": "uri" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "createdAt", "environmentKind", "id", "project", "signingKeys", "status", "updatedAt", "url", "version" ] } } }, "description": "Read a callback endpoint", "headers": { "ETag": { "required": true, "schema": { "type": "string", "pattern": "^\"([1-9][0-9]{0,18})\"$" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "404": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["not_found"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: not_found." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["project_archived"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: project_archived." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Read a callback endpoint", "security": [ { "apiCredential": ["endpoints:read"] }, { "memberSession": ["endpoints:read"], "memberSessionEnvironment": [], "memberSessionProject": [] } ] }, "put": { "description": "Replaces an endpoint's destination after applying the complete URL and DNS policy, and renames it when a name is given. Deliveries go to the new destination from the next one on. Disabled endpoints cannot be updated. Send If-Match with the version the endpoint was read at to be refused rather than overwrite a destination somebody else changed in the meantime.", "operationId": "endpoints.update", "parameters": [ { "in": "path", "name": "endpointId", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "If-Match", "required": false, "schema": { "type": "string", "pattern": "^\"([1-9][0-9]{0,18})\"$" } } ], "responses": { "200": { "content": { "application/json": { "example": { "createdAt": "2026-08-05T15:00:00.000Z", "environmentKind": "test", "id": "ep_01h8xyz9k2m4n6p8r0t2v4w6y8", "project": "proj_01h8xyz9k2m4n6p8r0t2v4w6y8", "signingKeys": { "current": "csk_01h8xyz9k2m4n6p8r0t2v4w6y8" }, "status": "active", "updatedAt": "2026-08-05T16:00:00.000Z", "url": "https://hooks.example.com/replacement", "version": 3 }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "createdAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "disabledAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "environmentKind": { "type": "string", "enum": ["test", "live"] }, "id": { "type": "string", "pattern": "^ep_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 2048 }, "project": { "type": "string", "pattern": "^proj_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "signingKeys": { "type": "object", "properties": { "current": { "type": "string", "pattern": "^csk_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "next": { "type": "object", "properties": { "acknowledgedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "id": { "type": "string", "pattern": "^csk_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "overlapEndsAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, "required": ["id", "overlapEndsAt"] } }, "required": ["current"] }, "status": { "type": "string", "enum": ["active", "disabled"] }, "updatedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "url": { "type": "string", "format": "uri" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "createdAt", "environmentKind", "id", "project", "signingKeys", "status", "updatedAt", "url", "version" ] } } }, "description": "Update a callback endpoint", "headers": { "ETag": { "required": true, "schema": { "type": "string", "pattern": "^\"([1-9][0-9]{0,18})\"$" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "404": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["not_found"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: not_found." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "project_archived", "state_conflict", "version_conflict" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: project_archived, state_conflict, version_conflict." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Update a callback endpoint", "security": [ { "apiCredential": ["endpoints:write"] }, { "memberSession": ["endpoints:write"], "memberSessionEnvironment": [], "memberSessionProject": [] } ], "requestBody": { "content": { "application/json": { "example": { "url": "https://hooks.example.com/replacement" }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 2048 }, "url": { "type": "string", "maxLength": 2048, "format": "uri" } }, "required": ["url"] } } }, "required": true } }, "delete": { "description": "Disables an endpoint immediately. It stays readable for audit but can no longer be updated or delivered to, and schedules pointed at it deliver nothing until `endpoints.enable` turns it back on. Repeating the disable is idempotent and does not write a second audit event, which is why it takes no precondition — the outcome does not depend on what else has changed.", "operationId": "endpoints.disable", "parameters": [ { "in": "path", "name": "endpointId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "createdAt": "2026-08-05T15:00:00.000Z", "disabledAt": "2026-08-05T17:00:00.000Z", "environmentKind": "test", "id": "ep_01h8xyz9k2m4n6p8r0t2v4w6y8", "project": "proj_01h8xyz9k2m4n6p8r0t2v4w6y8", "signingKeys": { "current": "csk_01h8xyz9k2m4n6p8r0t2v4w6y8" }, "status": "disabled", "updatedAt": "2026-08-05T17:00:00.000Z", "url": "https://hooks.example.com/greatwait", "version": 3 }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "createdAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "disabledAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "environmentKind": { "type": "string", "enum": ["test", "live"] }, "id": { "type": "string", "pattern": "^ep_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 2048 }, "project": { "type": "string", "pattern": "^proj_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "signingKeys": { "type": "object", "properties": { "current": { "type": "string", "pattern": "^csk_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "next": { "type": "object", "properties": { "acknowledgedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "id": { "type": "string", "pattern": "^csk_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "overlapEndsAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, "required": ["id", "overlapEndsAt"] } }, "required": ["current"] }, "status": { "type": "string", "enum": ["active", "disabled"] }, "updatedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "url": { "type": "string", "format": "uri" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "createdAt", "environmentKind", "id", "project", "signingKeys", "status", "updatedAt", "url", "version" ] } } }, "description": "Disable a callback endpoint", "headers": { "ETag": { "required": true, "schema": { "type": "string", "pattern": "^\"([1-9][0-9]{0,18})\"$" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "404": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["not_found"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: not_found." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["project_archived"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: project_archived." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Disable a callback endpoint", "security": [ { "apiCredential": ["endpoints:write"] }, { "memberSession": ["endpoints:write"], "memberSessionEnvironment": [], "memberSessionProject": [] } ] } }, "/v1/endpoints/{endpointId}/signing-keys/rotate": { "post": { "description": "Creates the next endpoint signing key and selects it immediately for new deliveries while retaining the current key in the receiver acceptance set for a bounded overlap. The overlap defaults to and cannot exceed 24 hours. A second rotation is refused until the current overlap ends. The new secret is returned once and has no recovery operation, so a call whose answer was never read may have rotated a key nobody holds: read the endpoint and compare its signing keys before repeating one. Send If-Match with the version the endpoint was read at to be refused rather than rotate an endpoint that has changed since.", "operationId": "endpoints.rotateSigningKey", "parameters": [ { "in": "path", "name": "endpointId", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "If-Match", "required": false, "schema": { "type": "string", "pattern": "^\"([1-9][0-9]{0,18})\"$" } } ], "responses": { "201": { "content": { "application/json": { "example": { "endpoint": { "createdAt": "2026-08-05T15:00:00.000Z", "environmentKind": "test", "id": "ep_01h8xyz9k2m4n6p8r0t2v4w6y8", "project": "proj_01h8xyz9k2m4n6p8r0t2v4w6y8", "signingKeys": { "current": "csk_01h8xyz9k2m4n6p8r0t2v4w6y8", "next": { "id": "csk_11h8xyz9k2m4n6p8r0t2v4w6y8", "overlapEndsAt": "2026-08-06T15:05:00.000Z" } }, "status": "active", "updatedAt": "2026-08-05T15:05:00.000Z", "url": "https://hooks.example.com/greatwait", "version": 3 }, "keyId": "csk_11h8xyz9k2m4n6p8r0t2v4w6y8", "secret": "ptsk_test_", "shownOnce": true }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "endpoint": { "type": "object", "properties": { "createdAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "disabledAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "environmentKind": { "type": "string", "enum": ["test", "live"] }, "id": { "type": "string", "pattern": "^ep_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 2048 }, "project": { "type": "string", "pattern": "^proj_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "signingKeys": { "type": "object", "properties": { "current": { "type": "string", "pattern": "^csk_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "next": { "type": "object", "properties": { "acknowledgedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "id": { "type": "string", "pattern": "^csk_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "overlapEndsAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, "required": ["id", "overlapEndsAt"] } }, "required": ["current"] }, "status": { "type": "string", "enum": ["active", "disabled"] }, "updatedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "url": { "type": "string", "format": "uri" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "createdAt", "environmentKind", "id", "project", "signingKeys", "status", "updatedAt", "url", "version" ] }, "keyId": { "type": "string", "pattern": "^csk_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "secret": { "type": "string", "minLength": 1 }, "shownOnce": { "type": "boolean", "const": true } }, "required": ["endpoint", "keyId", "secret", "shownOnce"] } } }, "description": "Rotate a callback endpoint signing key", "headers": { "ETag": { "required": true, "schema": { "type": "string", "pattern": "^\"([1-9][0-9]{0,18})\"$" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "404": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["not_found"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: not_found." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "project_archived", "state_conflict", "version_conflict" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: project_archived, state_conflict, version_conflict." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Rotate a callback endpoint signing key", "security": [ { "apiCredential": ["endpoints:write"] }, { "memberSession": ["endpoints:write"], "memberSessionEnvironment": [], "memberSessionProject": [] } ], "requestBody": { "content": { "application/json": { "example": { "overlapSeconds": 3600 }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "overlapSeconds": { "type": "integer", "minimum": 0, "maximum": 86400 } } } } }, "required": false } } }, "/v1/endpoints/{endpointId}/signing-keys/acknowledge": { "post": { "description": "Records that a person has updated their server to accept the next signing key during the active overlap. This only marks the reminder done: it does not retire either key, shorten the overlap, or change which key signs new deliveries. Send If-Match with the version the endpoint was read at so an acknowledgement cannot be applied to a different rotation.", "operationId": "endpoints.acknowledgeSigningKeyRotation", "parameters": [ { "in": "path", "name": "endpointId", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string", "pattern": "^\"([1-9][0-9]{0,18})\"$" } } ], "responses": { "200": { "content": { "application/json": { "example": { "createdAt": "2026-08-05T15:00:00.000Z", "environmentKind": "test", "id": "ep_01h8xyz9k2m4n6p8r0t2v4w6y8", "project": "proj_01h8xyz9k2m4n6p8r0t2v4w6y8", "signingKeys": { "current": "csk_01h8xyz9k2m4n6p8r0t2v4w6y8", "next": { "acknowledgedAt": "2026-08-05T15:10:00.000Z", "id": "csk_11h8xyz9k2m4n6p8r0t2v4w6y8", "overlapEndsAt": "2026-08-06T15:05:00.000Z" } }, "status": "active", "updatedAt": "2026-08-05T15:10:00.000Z", "url": "https://hooks.example.com/greatwait", "version": 4 }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "createdAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "disabledAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "environmentKind": { "type": "string", "enum": ["test", "live"] }, "id": { "type": "string", "pattern": "^ep_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 2048 }, "project": { "type": "string", "pattern": "^proj_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "signingKeys": { "type": "object", "properties": { "current": { "type": "string", "pattern": "^csk_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "next": { "type": "object", "properties": { "acknowledgedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "id": { "type": "string", "pattern": "^csk_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "overlapEndsAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, "required": ["id", "overlapEndsAt"] } }, "required": ["current"] }, "status": { "type": "string", "enum": ["active", "disabled"] }, "updatedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "url": { "type": "string", "format": "uri" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "createdAt", "environmentKind", "id", "project", "signingKeys", "status", "updatedAt", "url", "version" ] } } }, "description": "Mark a signing-key server update done", "headers": { "ETag": { "required": true, "schema": { "type": "string", "pattern": "^\"([1-9][0-9]{0,18})\"$" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "404": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["not_found"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: not_found." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "project_archived", "state_conflict", "version_conflict" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: project_archived, state_conflict, version_conflict." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Mark a signing-key server update done", "security": [ { "apiCredential": ["endpoints:write"] }, { "memberSession": ["endpoints:write"], "memberSessionEnvironment": [], "memberSessionProject": [] } ] } }, "/v1/endpoints/{endpointId}/signing-secret": { "get": { "description": "Reveals an endpoint's signing secret to a signed-in member: the value `endpoints.create` and `endpoints.rotateSigningKey` hand out once, readable again from the endpoint's own page. During a rotation both keys are returned, with the instant the overlap ends. Only a member session is accepted; an API credential or an OAuth token is refused, so an integration that needs the secret keeps the one the create or rotation that minted it returned. A disabled endpoint has nothing to reveal.", "operationId": "endpoints.revealSigningSecret", "parameters": [ { "in": "path", "name": "endpointId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "current": { "keyId": "csk_01h8xyz9k2m4n6p8r0t2v4w6y8", "secret": "ptsk_test_" }, "id": "ep_01h8xyz9k2m4n6p8r0t2v4w6y8" }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "current": { "type": "object", "properties": { "keyId": { "type": "string", "pattern": "^csk_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "secret": { "type": "string", "minLength": 1 } }, "required": ["keyId", "secret"] }, "id": { "type": "string", "pattern": "^ep_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "next": { "type": "object", "properties": { "keyId": { "type": "string", "pattern": "^csk_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "secret": { "type": "string", "minLength": 1 }, "overlapEndsAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, "required": ["keyId", "secret", "overlapEndsAt"] } }, "required": ["current", "id"] } } }, "description": "Reveal a callback endpoint signing secret" }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "404": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["not_found"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: not_found." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["project_archived", "state_conflict"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: project_archived, state_conflict." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Reveal a callback endpoint signing secret", "security": [ { "memberSession": ["endpoints:write"], "memberSessionEnvironment": [], "memberSessionProject": [] } ] } }, "/v1/endpoints/{endpointId}/enable": { "post": { "description": "Enables an endpoint that was disabled, so schedules pointed at it deliver again from the next occurrence on. Its address, name, signing keys and history are exactly as they were; nothing has to be created or re-pointed. Repeating the enable is idempotent and does not write a second audit event, so like `endpoints.disable` it takes no precondition. Somebody who disabled an endpoint by mistake, with many schedules pointed at it, gets it back with one call.", "operationId": "endpoints.enable", "parameters": [ { "in": "path", "name": "endpointId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "createdAt": "2026-08-05T15:00:00.000Z", "environmentKind": "test", "id": "ep_01h8xyz9k2m4n6p8r0t2v4w6y8", "name": "https://hooks.example.com/greatwait", "project": "proj_01h8xyz9k2m4n6p8r0t2v4w6y8", "signingKeys": { "current": "csk_01h8xyz9k2m4n6p8r0t2v4w6y8" }, "status": "active", "updatedAt": "2026-08-05T18:00:00.000Z", "url": "https://hooks.example.com/greatwait", "version": 4 }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "createdAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "disabledAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "environmentKind": { "type": "string", "enum": ["test", "live"] }, "id": { "type": "string", "pattern": "^ep_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 2048 }, "project": { "type": "string", "pattern": "^proj_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "signingKeys": { "type": "object", "properties": { "current": { "type": "string", "pattern": "^csk_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "next": { "type": "object", "properties": { "acknowledgedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "id": { "type": "string", "pattern": "^csk_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "overlapEndsAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, "required": ["id", "overlapEndsAt"] } }, "required": ["current"] }, "status": { "type": "string", "enum": ["active", "disabled"] }, "updatedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "url": { "type": "string", "format": "uri" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "createdAt", "environmentKind", "id", "project", "signingKeys", "status", "updatedAt", "url", "version" ] } } }, "description": "Enable a disabled callback endpoint", "headers": { "ETag": { "required": true, "schema": { "type": "string", "pattern": "^\"([1-9][0-9]{0,18})\"$" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "404": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["not_found"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: not_found." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["project_archived", "state_conflict"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: project_archived, state_conflict." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Enable a disabled callback endpoint", "security": [ { "apiCredential": ["endpoints:write"] }, { "memberSession": ["endpoints:write"], "memberSessionEnvironment": [], "memberSessionProject": [] } ] } }, "/v1/test-sinks": { "post": { "description": "Creates a deterministic receiver for one callback endpoint so failures can be rehearsed before they happen in production. Test environments only: a live principal has no such operation, and there is no request field that could widen the organization, project, or environment the sink belongs to. The sink verifies deliveries with the bound endpoint's own signing keys, so key rotation and a wrong key behave here exactly as they would at the customer's receiver. It receives and never sends: no field names a destination and no configuration makes it forward a delivery. Point the endpoint at the returned url, and every attempt lands here.", "operationId": "testsinks.create", "parameters": [], "responses": { "201": { "content": { "application/json": { "example": { "createdAt": "2026-08-07T15:00:00.000Z", "deliveryCount": 0, "endpoint": "ep_01h8xyz9k2m4n6p8r0t2v4w6y8", "environmentKind": "test", "id": "tsk_01h8xyz9k2m4n6p8r0t2v4w6y8", "program": { "behavior": "success" }, "project": "proj_01h8xyz9k2m4n6p8r0t2v4w6y8", "updatedAt": "2026-08-07T15:00:00.000Z", "url": "https://sink.greatwait.dev/__greatwait/test-sinks/tsk_01h8xyz9k2m4n6p8r0t2v4w6y8" }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "createdAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "deliveryCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "endpoint": { "type": "string", "pattern": "^ep_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "environmentKind": { "type": "string", "const": "test" }, "id": { "type": "string", "pattern": "^tsk_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "program": { "type": "object", "properties": { "behavior": { "type": "string", "enum": [ "client_error", "defer_abandon", "defer_fail", "defer_succeed", "delay", "disconnect", "duplicate", "invalid_signature", "rate_limited", "server_error", "success", "timeout" ] }, "completionDelayMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 5000 }, "delayMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 10000 }, "forDeliveries": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100 }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 300 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "then": { "type": "string", "enum": [ "client_error", "defer_abandon", "defer_fail", "defer_succeed", "delay", "disconnect", "duplicate", "invalid_signature", "rate_limited", "server_error", "success", "timeout" ] } }, "required": ["behavior"] }, "project": { "type": "string", "pattern": "^proj_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "updatedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "url": { "type": "string", "format": "uri" } }, "required": [ "createdAt", "deliveryCount", "endpoint", "environmentKind", "id", "program", "project", "updatedAt", "url" ] } } }, "description": "Create a test sink" }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "404": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["not_found"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: not_found." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "plan_limit_reached", "project_archived", "state_conflict" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: plan_limit_reached, project_archived, state_conflict." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Create a test sink", "security": [ { "apiCredential": ["endpoints:write"] }, { "memberSession": ["endpoints:write"], "memberSessionEnvironment": [], "memberSessionProject": [] } ], "requestBody": { "content": { "application/json": { "example": { "endpoint": "ep_01h8xyz9k2m4n6p8r0t2v4w6y8", "program": { "behavior": "server_error", "forDeliveries": 2, "then": "success" } }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "endpoint": { "type": "string", "pattern": "^ep_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "program": { "type": "object", "properties": { "behavior": { "type": "string", "enum": [ "client_error", "defer_abandon", "defer_fail", "defer_succeed", "delay", "disconnect", "duplicate", "invalid_signature", "rate_limited", "server_error", "success", "timeout" ] }, "completionDelayMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 5000 }, "delayMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 10000 }, "forDeliveries": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100 }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 300 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "then": { "type": "string", "enum": [ "client_error", "defer_abandon", "defer_fail", "defer_succeed", "delay", "disconnect", "duplicate", "invalid_signature", "rate_limited", "server_error", "success", "timeout" ] } }, "required": ["behavior"] } }, "required": ["endpoint"] } } }, "required": true } }, "get": { "description": "Lists the caller's test sinks for exactly its own project and test environment. A live principal receives an empty-handed refusal rather than another environment's sinks.", "operationId": "testsinks.list", "parameters": [ { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "createdAt": "2026-08-07T15:00:00.000Z", "deliveryCount": 3, "endpoint": "ep_01h8xyz9k2m4n6p8r0t2v4w6y8", "environmentKind": "test", "id": "tsk_01h8xyz9k2m4n6p8r0t2v4w6y8", "program": { "behavior": "success" }, "project": "proj_01h8xyz9k2m4n6p8r0t2v4w6y8", "updatedAt": "2026-08-07T15:02:00.000Z", "url": "https://sink.greatwait.dev/__greatwait/test-sinks/tsk_01h8xyz9k2m4n6p8r0t2v4w6y8" } ], "freshness": { "kind": "authoritative" } }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "createdAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "deliveryCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "endpoint": { "type": "string", "pattern": "^ep_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "environmentKind": { "type": "string", "const": "test" }, "id": { "type": "string", "pattern": "^tsk_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "program": { "type": "object", "properties": { "behavior": { "type": "string", "enum": [ "client_error", "defer_abandon", "defer_fail", "defer_succeed", "delay", "disconnect", "duplicate", "invalid_signature", "rate_limited", "server_error", "success", "timeout" ] }, "completionDelayMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 5000 }, "delayMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 10000 }, "forDeliveries": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100 }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 300 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "then": { "type": "string", "enum": [ "client_error", "defer_abandon", "defer_fail", "defer_succeed", "delay", "disconnect", "duplicate", "invalid_signature", "rate_limited", "server_error", "success", "timeout" ] } }, "required": ["behavior"] }, "project": { "type": "string", "pattern": "^proj_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "updatedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "url": { "type": "string", "format": "uri" } }, "required": [ "createdAt", "deliveryCount", "endpoint", "environmentKind", "id", "program", "project", "updatedAt", "url" ] } }, "freshness": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "authoritative" } }, "required": ["kind"] }, { "type": "object", "properties": { "asOf": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "kind": { "type": "string", "const": "projected" }, "lagSeconds": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["asOf", "kind", "lagSeconds"] } ] }, "nextCursor": { "type": "string", "minLength": 1 } }, "required": ["data", "freshness"] } } }, "description": "List test sinks" }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["project_archived", "state_conflict"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: project_archived, state_conflict." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "List test sinks", "security": [ { "apiCredential": ["endpoints:read"] }, { "memberSession": ["endpoints:read"], "memberSessionEnvironment": [], "memberSessionProject": [] } ] } }, "/v1/test-sinks/{sinkId}": { "get": { "description": "Reads one test sink from the caller's own project and test environment, including how many deliveries it has taken. A well-formed identifier belonging to another authority is indistinguishable from an absent sink.", "operationId": "testsinks.read", "parameters": [ { "in": "path", "name": "sinkId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "createdAt": "2026-08-07T15:00:00.000Z", "deliveryCount": 3, "endpoint": "ep_01h8xyz9k2m4n6p8r0t2v4w6y8", "environmentKind": "test", "id": "tsk_01h8xyz9k2m4n6p8r0t2v4w6y8", "program": { "behavior": "rate_limited", "retryAfterSeconds": 5 }, "project": "proj_01h8xyz9k2m4n6p8r0t2v4w6y8", "updatedAt": "2026-08-07T15:02:00.000Z", "url": "https://sink.greatwait.dev/__greatwait/test-sinks/tsk_01h8xyz9k2m4n6p8r0t2v4w6y8" }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "createdAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "deliveryCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "endpoint": { "type": "string", "pattern": "^ep_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "environmentKind": { "type": "string", "const": "test" }, "id": { "type": "string", "pattern": "^tsk_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "program": { "type": "object", "properties": { "behavior": { "type": "string", "enum": [ "client_error", "defer_abandon", "defer_fail", "defer_succeed", "delay", "disconnect", "duplicate", "invalid_signature", "rate_limited", "server_error", "success", "timeout" ] }, "completionDelayMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 5000 }, "delayMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 10000 }, "forDeliveries": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100 }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 300 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "then": { "type": "string", "enum": [ "client_error", "defer_abandon", "defer_fail", "defer_succeed", "delay", "disconnect", "duplicate", "invalid_signature", "rate_limited", "server_error", "success", "timeout" ] } }, "required": ["behavior"] }, "project": { "type": "string", "pattern": "^proj_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "updatedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "url": { "type": "string", "format": "uri" } }, "required": [ "createdAt", "deliveryCount", "endpoint", "environmentKind", "id", "program", "project", "updatedAt", "url" ] } } }, "description": "Read a test sink" }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "404": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["not_found"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: not_found." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["project_archived", "state_conflict"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: project_archived, state_conflict." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Read a test sink", "security": [ { "apiCredential": ["endpoints:read"] }, { "memberSession": ["endpoints:read"], "memberSessionEnvironment": [], "memberSessionProject": [] } ] }, "delete": { "description": "Deletes a sink and every delivery it recorded. The bound callback endpoint is untouched and keeps its signing keys; deliveries sent afterwards find nothing at the url and fail the way an unreachable receiver does.", "operationId": "testsinks.delete", "parameters": [ { "in": "path", "name": "sinkId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "createdAt": "2026-08-07T15:00:00.000Z", "deliveryCount": 3, "endpoint": "ep_01h8xyz9k2m4n6p8r0t2v4w6y8", "environmentKind": "test", "id": "tsk_01h8xyz9k2m4n6p8r0t2v4w6y8", "program": { "behavior": "success" }, "project": "proj_01h8xyz9k2m4n6p8r0t2v4w6y8", "updatedAt": "2026-08-07T15:04:00.000Z", "url": "https://sink.greatwait.dev/__greatwait/test-sinks/tsk_01h8xyz9k2m4n6p8r0t2v4w6y8" }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "createdAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "deliveryCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "endpoint": { "type": "string", "pattern": "^ep_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "environmentKind": { "type": "string", "const": "test" }, "id": { "type": "string", "pattern": "^tsk_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "program": { "type": "object", "properties": { "behavior": { "type": "string", "enum": [ "client_error", "defer_abandon", "defer_fail", "defer_succeed", "delay", "disconnect", "duplicate", "invalid_signature", "rate_limited", "server_error", "success", "timeout" ] }, "completionDelayMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 5000 }, "delayMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 10000 }, "forDeliveries": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100 }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 300 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "then": { "type": "string", "enum": [ "client_error", "defer_abandon", "defer_fail", "defer_succeed", "delay", "disconnect", "duplicate", "invalid_signature", "rate_limited", "server_error", "success", "timeout" ] } }, "required": ["behavior"] }, "project": { "type": "string", "pattern": "^proj_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "updatedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "url": { "type": "string", "format": "uri" } }, "required": [ "createdAt", "deliveryCount", "endpoint", "environmentKind", "id", "program", "project", "updatedAt", "url" ] } } }, "description": "Delete a test sink" }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "404": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["not_found"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: not_found." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["project_archived", "state_conflict"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: project_archived, state_conflict." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Delete a test sink", "security": [ { "apiCredential": ["endpoints:write"] }, { "memberSession": ["endpoints:write"], "memberSessionEnvironment": [], "memberSessionProject": [] } ] } }, "/v1/test-sinks/{sinkId}/program": { "put": { "description": "Replaces a sink's behavior program. The program is resolved against the number of deliveries the sink has already taken, so `forDeliveries` counts from the next delivery rather than from the sink's creation. Repeating the identical program is idempotent and changes nothing an integrator can observe.", "operationId": "testsinks.configure", "parameters": [ { "in": "path", "name": "sinkId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "createdAt": "2026-08-07T15:00:00.000Z", "deliveryCount": 3, "endpoint": "ep_01h8xyz9k2m4n6p8r0t2v4w6y8", "environmentKind": "test", "id": "tsk_01h8xyz9k2m4n6p8r0t2v4w6y8", "program": { "behavior": "timeout" }, "project": "proj_01h8xyz9k2m4n6p8r0t2v4w6y8", "updatedAt": "2026-08-07T15:03:00.000Z", "url": "https://sink.greatwait.dev/__greatwait/test-sinks/tsk_01h8xyz9k2m4n6p8r0t2v4w6y8" }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "createdAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "deliveryCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "endpoint": { "type": "string", "pattern": "^ep_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "environmentKind": { "type": "string", "const": "test" }, "id": { "type": "string", "pattern": "^tsk_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "program": { "type": "object", "properties": { "behavior": { "type": "string", "enum": [ "client_error", "defer_abandon", "defer_fail", "defer_succeed", "delay", "disconnect", "duplicate", "invalid_signature", "rate_limited", "server_error", "success", "timeout" ] }, "completionDelayMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 5000 }, "delayMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 10000 }, "forDeliveries": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100 }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 300 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "then": { "type": "string", "enum": [ "client_error", "defer_abandon", "defer_fail", "defer_succeed", "delay", "disconnect", "duplicate", "invalid_signature", "rate_limited", "server_error", "success", "timeout" ] } }, "required": ["behavior"] }, "project": { "type": "string", "pattern": "^proj_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "updatedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "url": { "type": "string", "format": "uri" } }, "required": [ "createdAt", "deliveryCount", "endpoint", "environmentKind", "id", "program", "project", "updatedAt", "url" ] } } }, "description": "Set a test sink behavior program" }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "404": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["not_found"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: not_found." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["project_archived", "state_conflict"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: project_archived, state_conflict." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Set a test sink behavior program", "security": [ { "apiCredential": ["endpoints:write"] }, { "memberSession": ["endpoints:write"], "memberSessionEnvironment": [], "memberSessionProject": [] } ], "requestBody": { "content": { "application/json": { "example": { "behavior": "timeout" }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "behavior": { "type": "string", "enum": [ "client_error", "defer_abandon", "defer_fail", "defer_succeed", "delay", "disconnect", "duplicate", "invalid_signature", "rate_limited", "server_error", "success", "timeout" ] }, "completionDelayMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 5000 }, "delayMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 10000 }, "forDeliveries": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100 }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 300 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "then": { "type": "string", "enum": [ "client_error", "defer_abandon", "defer_fail", "defer_succeed", "delay", "disconnect", "duplicate", "invalid_signature", "rate_limited", "server_error", "success", "timeout" ] } }, "required": ["behavior"] } } }, "required": true } } }, "/v1/test-sinks/{sinkId}/deliveries": { "get": { "description": "Lists what the sink received, most recent first with the record identifier breaking a tie, bounded by the retained-delivery ceiling. Metadata only: the identifiers, the signing key that authenticated the delivery, how the receiver disposed of it, and what it answered. The delivered body is not in this shape.", "operationId": "sinkdeliveries.list", "parameters": [ { "in": "path", "name": "sinkId", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "behavior": "success", "disposition": "processed", "delivery": "dlv_01h8xyz9k2m4n6p8r0t2v4w6y8", "id": "tsd_01h8xyz9k2m4n6p8r0t2v4w6y8", "keyId": "csk_01h8xyz9k2m4n6p8r0t2v4w6y8", "occurrenceId": "occ_01h8xyz9k2m4n6p8r0t2v4w6y8", "receivedAt": "2026-08-07T15:02:00.000Z", "respondedWith": 200, "scheduleId": "sch_01h8xyz9k2m4n6p8r0t2v4w6y8", "sink": "tsk_01h8xyz9k2m4n6p8r0t2v4w6y8" } ], "freshness": { "kind": "authoritative" } }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "behavior": { "type": "string", "enum": [ "client_error", "defer_abandon", "defer_fail", "defer_succeed", "delay", "disconnect", "duplicate", "invalid_signature", "rate_limited", "server_error", "success", "timeout" ] }, "disposition": { "type": "string", "enum": [ "body_too_large", "duplicate", "handler_failed", "in_flight", "invalid_envelope", "invalid_headers", "invalid_signature", "processed", "replay", "stale_timestamp", "connection_dropped" ] }, "delivery": { "type": "string", "pattern": "^dlv_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "id": { "type": "string", "pattern": "^tsd_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "keyId": { "type": "string", "pattern": "^csk_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "occurrenceId": { "type": "string", "pattern": "^occ_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "receivedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "respondedWith": { "type": "integer", "minimum": 100, "maximum": 599 }, "scheduleId": { "type": "string", "pattern": "^sch_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "sink": { "type": "string", "pattern": "^tsk_[0-9abcdefghjkmnpqrstvwxyz]{26}$" } }, "required": [ "behavior", "disposition", "delivery", "id", "receivedAt", "sink" ] } }, "freshness": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "authoritative" } }, "required": ["kind"] }, { "type": "object", "properties": { "asOf": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "kind": { "type": "string", "const": "projected" }, "lagSeconds": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["asOf", "kind", "lagSeconds"] } ] }, "nextCursor": { "type": "string", "minLength": 1 } }, "required": ["data", "freshness"] } } }, "description": "List test sink deliveries" }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "404": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["not_found"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: not_found." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["project_archived", "state_conflict"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: project_archived, state_conflict." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "List test sink deliveries", "security": [ { "apiCredential": ["endpoints:read"] }, { "memberSession": ["endpoints:read"], "memberSessionEnvironment": [], "memberSessionProject": [] } ] } }, "/v1/test-sinks/{sinkId}/deliveries/{deliveryRecordId}": { "get": { "description": "Reads one recorded delivery including the exact bytes that arrived, truncated at the published cap with the original length stated. This is the one place a callback body is readable, and it is narrow on purpose: a test environment only, the creating authority only, a single record rather than a listing, and never a log. The signature is included because a MAC is not secret and comparing it against a locally computed one is how a body-mutation bug is found; no signing key appears in this shape.", "operationId": "sinkdeliveries.read", "parameters": [ { "in": "path", "name": "sinkId", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "deliveryRecordId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "behavior": "success", "disposition": "processed", "delivery": "dlv_01h8xyz9k2m4n6p8r0t2v4w6y8", "id": "tsd_01h8xyz9k2m4n6p8r0t2v4w6y8", "keyId": "csk_01h8xyz9k2m4n6p8r0t2v4w6y8", "occurrenceId": "occ_01h8xyz9k2m4n6p8r0t2v4w6y8", "receivedAt": "2026-08-07T15:02:00.000Z", "respondedWith": 200, "scheduleId": "sch_01h8xyz9k2m4n6p8r0t2v4w6y8", "sink": "tsk_01h8xyz9k2m4n6p8r0t2v4w6y8", "body": "{\"version\":\"2026-08-08\",\"type\":\"schedule.occurrence\",\"scheduleId\":\"sch_01h8xyz9k2m4n6p8r0t2v4w6y8\",\"occurrenceId\":\"occ_01h8xyz9k2m4n6p8r0t2v4w6y8\",\"plannedFor\":\"2026-08-07T15:00:00.000Z\",\"attempt\":1,\"trigger\":{\"kind\":\"automatic\"},\"data\":{}}", "bodyTruncated": false, "receivedBytes": 240, "signature": "v1=11135fdfc0bc5d49ebcc9d3a0d8df1116179097cefe961c6eca281339e5cfab3" }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "behavior": { "type": "string", "enum": [ "client_error", "defer_abandon", "defer_fail", "defer_succeed", "delay", "disconnect", "duplicate", "invalid_signature", "rate_limited", "server_error", "success", "timeout" ] }, "disposition": { "type": "string", "enum": [ "body_too_large", "duplicate", "handler_failed", "in_flight", "invalid_envelope", "invalid_headers", "invalid_signature", "processed", "replay", "stale_timestamp", "connection_dropped" ] }, "delivery": { "type": "string", "pattern": "^dlv_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "id": { "type": "string", "pattern": "^tsd_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "keyId": { "type": "string", "pattern": "^csk_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "occurrenceId": { "type": "string", "pattern": "^occ_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "receivedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "respondedWith": { "type": "integer", "minimum": 100, "maximum": 599 }, "scheduleId": { "type": "string", "pattern": "^sch_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "sink": { "type": "string", "pattern": "^tsk_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "body": { "type": "string" }, "bodyTruncated": { "type": "boolean" }, "receivedBytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "signature": { "type": "string", "pattern": "^v1=[0-9a-f]{64}$" } }, "required": [ "behavior", "disposition", "delivery", "id", "receivedAt", "sink", "body", "bodyTruncated", "receivedBytes" ] } } }, "description": "Read a test sink delivery" }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "404": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["not_found"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: not_found." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["project_archived", "state_conflict"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: project_archived, state_conflict." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Read a test sink delivery", "security": [ { "apiCredential": ["endpoints:read"] }, { "memberSession": ["endpoints:read"], "memberSessionEnvironment": [], "memberSessionProject": [] } ] } }, "/v1/context": { "get": { "description": "Reports the authority the presented credential carries: the project it acts in, which of that project's two environments, and the scopes the service will enforce for it. The answer comes entirely from the verified principal, so there is no parameter that could name another project and no way for the reply to describe anything but the caller itself. It requires a principal and no scope, because every value in it is a property of the credential being presented rather than of anything the credential may reach: a caller that could not read this could still act, and would simply be acting without being able to say where. A signed-in member is not accepted — a session's authority is an organization and it names its project per request, so there is no single answer to give one.", "operationId": "context.read", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "environmentKind": "test", "principal": "api-credential", "project": "proj_01h8xyz9k2m4n6p8r0t2v4w6y8", "scopes": ["schedules:read", "schedules:write"] }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "environmentKind": { "type": "string", "enum": ["test", "live"] }, "principal": { "type": "string", "enum": ["api-credential", "oauth"] }, "project": { "type": "string", "pattern": "^proj_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "scopes": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "credentials:administer", "billing:write", "credentials:read", "credentials:write", "endpoints:read", "endpoints:write", "forecast:read", "grants:read", "grants:write", "occurrences:read", "occurrences:redeliver", "projects:administer", "projects:read", "projects:write", "schedules:read", "schedules:write", "usage:read" ] } } }, "required": [ "environmentKind", "principal", "project", "scopes" ] } } }, "description": "Read this credential's authority" }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["project_archived"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: project_archived." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Read this credential's authority", "security": [ { "apiCredential": [] } ] } }, "/v1/credentials": { "post": { "description": "Issues an API credential bound to one project and environment, with scopes capped by the issuing member's current role. The full secret is in this response and in no other, is not recoverable afterwards, and there is deliberately no reveal endpoint. The value is the sixteen-character display prefix followed immediately by thirty-two more characters; the example below is a visible placeholder rather than that shape, because a realistic credential in a committed file is one the repository's own secret scanner refuses.", "operationId": "credentials.create", "parameters": [], "responses": { "201": { "content": { "application/json": { "example": { "createdAt": "2026-07-28T15:00:00.000Z", "displayPrefix": "pt_test_a1b2c3d4", "environmentKind": "test", "id": "ak_01h8xyz9k2m4n6p8r0t2v4w6y8", "project": "proj_01h8xyz9k2m4n6p8r0t2v4w6y8", "scopes": ["schedules:write"], "secret": "pt_test_a1b2c3d4", "shownOnce": true }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "createdAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "displayPrefix": { "type": "string", "pattern": "^pt_(?:live|test)_[0-9a-z]{8}$" }, "environmentKind": { "type": "string", "enum": ["test", "live"] }, "expiresAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "id": { "type": "string", "pattern": "^ak_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "issuedBy": { "type": "string", "minLength": 1 }, "lastUsedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "project": { "type": "string", "pattern": "^proj_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "revokedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "supersededBy": { "type": "string", "pattern": "^ak_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "scopes": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "credentials:administer", "billing:write", "credentials:read", "credentials:write", "endpoints:read", "endpoints:write", "forecast:read", "grants:read", "grants:write", "occurrences:read", "occurrences:redeliver", "projects:administer", "projects:read", "projects:write", "schedules:read", "schedules:write", "usage:read" ] } }, "secret": { "type": "string", "minLength": 48 }, "shownOnce": { "type": "boolean", "const": true } }, "required": [ "createdAt", "displayPrefix", "environmentKind", "id", "project", "scopes", "secret", "shownOnce" ] } } }, "description": "Issue an API credential" }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "404": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["not_found"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: not_found." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["project_archived"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: project_archived." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Issue an API credential", "security": [ { "memberSession": ["credentials:write"] } ], "requestBody": { "content": { "application/json": { "example": { "environmentKind": "test", "project": "proj_01h8xyz9k2m4n6p8r0t2v4w6y8", "scopes": ["schedules:write"] }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "environmentKind": { "type": "string", "enum": ["test", "live"] }, "project": { "type": "string", "pattern": "^proj_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "scopes": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "credentials:administer", "billing:write", "credentials:read", "credentials:write", "endpoints:read", "endpoints:write", "forecast:read", "grants:read", "grants:write", "occurrences:read", "occurrences:redeliver", "projects:administer", "projects:read", "projects:write", "schedules:read", "schedules:write", "usage:read" ] } } }, "required": ["environmentKind", "project", "scopes"] } } }, "required": true } }, "get": { "description": "Lists the credentials issued for the caller's own project and environment, oldest first, one page at a time. The authority tuple comes from the verified principal, so there is no parameter that could name another project — a listing is the caller's own book or nothing. Revoked and rotated credentials stay in the listing and carry the fields that say so; a credential nobody can see is a credential nobody can audit. `limit` is bounded by the contract and `cursor` is the opaque value the previous page returned. No page carries a secret: the item is the read shape, which has no field one could be put in.", "operationId": "credentials.list", "parameters": [ { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "createdAt": "2026-07-28T15:00:00.000Z", "displayPrefix": "pt_test_a1b2c3d4", "environmentKind": "test", "id": "ak_01h8xyz9k2m4n6p8r0t2v4w6y8", "lastUsedAt": "2026-07-28T15:04:00.000Z", "project": "proj_01h8xyz9k2m4n6p8r0t2v4w6y8", "scopes": ["schedules:write"] } ], "freshness": { "kind": "authoritative" }, "nextCursor": "eyJhIjoxNzg1MjUwODAwMDAwLCJpIjoiYWtfMDFoOHh5ejlrMm00bjZwOHIwdDJ2NHc2eTgiLCJrIjoiOTUxMzU0NmYifQ" }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "createdAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "displayPrefix": { "type": "string", "pattern": "^pt_(?:live|test)_[0-9a-z]{8}$" }, "environmentKind": { "type": "string", "enum": ["test", "live"] }, "expiresAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "id": { "type": "string", "pattern": "^ak_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "issuedBy": { "type": "string", "minLength": 1 }, "lastUsedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "project": { "type": "string", "pattern": "^proj_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "revokedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "supersededBy": { "type": "string", "pattern": "^ak_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "scopes": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "credentials:administer", "billing:write", "credentials:read", "credentials:write", "endpoints:read", "endpoints:write", "forecast:read", "grants:read", "grants:write", "occurrences:read", "occurrences:redeliver", "projects:administer", "projects:read", "projects:write", "schedules:read", "schedules:write", "usage:read" ] } } }, "required": [ "createdAt", "displayPrefix", "environmentKind", "id", "project", "scopes" ] } }, "freshness": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "authoritative" } }, "required": ["kind"] }, { "type": "object", "properties": { "asOf": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "kind": { "type": "string", "const": "projected" }, "lagSeconds": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["asOf", "kind", "lagSeconds"] } ] }, "nextCursor": { "type": "string", "minLength": 1 } }, "required": ["data", "freshness"] } } }, "description": "List API credentials" }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["project_archived"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: project_archived." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "List API credentials", "security": [ { "apiCredential": ["credentials:read"] }, { "memberSession": ["credentials:read"], "memberSessionEnvironment": [], "memberSessionProject": [] } ] } }, "/v1/credentials/{credentialId}/connection": { "get": { "description": "Reads what a key this project issued should be able to do over MCP: the endpoint to point a client at, the discovery document beside it, the scopes fixed into the key when it was made, and the MCP tool names those scopes authorize. It returns no secret and cannot: the transient value is shown once at creation and is never sent here. The credential is addressed by identifier and re-resolved against the signed-in member's own project and environment, so a key belonging to another project answers exactly as one that does not exist. `state` distinguishes a key that still verifies from one that was revoked and one whose rotation overlap has run out, because a client configured with either fails identically and the remedies differ.", "operationId": "credentials.connection", "parameters": [ { "in": "path", "name": "credentialId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "discovery": "https://api.greatwait.dev/.well-known/oauth-protected-resource/mcp", "displayPrefix": "pt_test_a1b2c3d4", "endpoint": "https://api.greatwait.dev/mcp", "id": "ak_01h8xyz9k2m4n6p8r0t2v4w6y8", "scopes": [ "occurrences:read", "schedules:read", "schedules:write" ], "state": "usable", "tools": [ "occurrences_list", "occurrences_read", "schedules_cancel", "schedules_create", "schedules_list", "schedules_read" ] }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "discovery": { "type": "string", "format": "uri" }, "displayPrefix": { "type": "string", "pattern": "^pt_(?:live|test)_[0-9a-z]{8}$" }, "endpoint": { "type": "string", "format": "uri" }, "id": { "type": "string", "pattern": "^ak_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "credentials:administer", "billing:write", "credentials:read", "credentials:write", "endpoints:read", "endpoints:write", "forecast:read", "grants:read", "grants:write", "occurrences:read", "occurrences:redeliver", "projects:administer", "projects:read", "projects:write", "schedules:read", "schedules:write", "usage:read" ] } }, "state": { "type": "string", "enum": ["usable", "revoked", "expired"] }, "tools": { "type": "array", "items": { "type": "string" } } }, "required": [ "discovery", "displayPrefix", "endpoint", "id", "scopes", "state", "tools" ] } } }, "description": "Read a credential's MCP connection" }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "404": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["not_found"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: not_found." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["project_archived"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: project_archived." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Read a credential's MCP connection", "security": [ { "memberSession": ["credentials:read"], "memberSessionEnvironment": [], "memberSessionProject": [] } ] } }, "/v1/projects": { "get": { "description": "Lists the active and archived projects in the signed-in member's organization, with the environment kinds, lifecycle state, version and deletion-preview counts each one has. Active and archived rows both occupy a plan slot; deleted projects are absent. Archived rows are management targets rather than projects work may run inside, so a picker must not offer them as switch targets. The result is a display aid rather than an authorization control — naming a project on a later request re-resolves it against the member's own organization, and a project that is not theirs answers exactly as one that does not exist.", "operationId": "projects.list", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "createdAt": "2026-08-14T11:00:00.000Z", "deletionCounts": { "endpoints": 2, "keys": 4, "runs": 37, "schedules": 5 }, "environmentKinds": ["test", "live"], "id": "proj_01h8xyz9k2m4n6p8r0t2v4w6y8", "name": "Billing reminders", "status": "active", "version": 1 } ], "total": 1 }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "createdAt": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, { "type": "null" } ] }, "deletionCounts": { "type": "object", "properties": { "endpoints": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "keys": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "runs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "schedules": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "endpoints", "keys", "runs", "schedules" ] }, "environmentKinds": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "string", "enum": ["test", "live"] } }, "id": { "type": "string", "pattern": "^proj_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "status": { "type": "string", "enum": ["active", "archived"] }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "createdAt", "deletionCounts", "environmentKinds", "id", "name", "status", "version" ] } }, "total": { "type": "integer", "minimum": 0, "maximum": 200 } }, "required": ["data", "total"] } } }, "description": "List the member's projects" }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "List the member's projects", "security": [ { "memberSession": ["projects:read"] } ] }, "post": { "description": "Creates a project in the signed-in member's organization, with both of its environments. This is the first call a new customer makes: an organization has no project until somebody makes one, and every other operation on this surface acts inside one. The `test` and `live` environments are provisioned with it in a single transaction rather than asked for, so a project is never observable in a half-provisioned state. The organization comes from the verified session and is never read from the request — a member who belongs to one organization cannot create a project in another. `PROJECT_LIST_LIMIT` bounds how many an organization may hold, and it is the same ceiling the listing publishes: a create that would take an organization past a list it can no longer return is refused rather than silently truncating a later read. A name is unique within the organization, compared ignoring case and surrounding or repeated spaces; a second project with a name already taken is refused with `state_conflict`, and the refusal says nothing about any other organization's names.", "operationId": "projects.create", "parameters": [], "responses": { "201": { "content": { "application/json": { "example": { "createdAt": null, "deletionCounts": { "endpoints": 0, "keys": 0, "runs": 0, "schedules": 0 }, "environmentKinds": ["test", "live"], "id": "proj_01h8xyz9k2m4n6p8r0t2v4w6y8", "name": "Billing reminders", "status": "active", "version": 1 }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "createdAt": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, { "type": "null" } ] }, "deletionCounts": { "type": "object", "properties": { "endpoints": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "keys": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "runs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "schedules": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["endpoints", "keys", "runs", "schedules"] }, "environmentKinds": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "string", "enum": ["test", "live"] } }, "id": { "type": "string", "pattern": "^proj_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "status": { "type": "string", "enum": ["active", "archived"] }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "createdAt", "deletionCounts", "environmentKinds", "id", "name", "status", "version" ] } } }, "description": "Create a project" }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "plan_limit_reached", "state_conflict" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: plan_limit_reached, state_conflict." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Create a project", "security": [ { "memberSession": ["projects:write"] } ], "requestBody": { "content": { "application/json": { "example": { "name": "Billing reminders" }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 } }, "required": ["name"] } } }, "required": true } } }, "/v1/projects/{projectId}": { "patch": { "description": "Renames one project in the caller's own organization without changing its opaque identifier. Names remain unique within the organization ignoring ASCII case and surrounding or repeated whitespace. Send If-Match with the project's current version; a stale version is refused rather than silently overwriting somebody else's change. Members and administrators may rename because the change is cosmetic and reversible.", "operationId": "projects.rename", "parameters": [ { "in": "path", "name": "projectId", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string", "pattern": "^\"([1-9][0-9]{0,18})\"$" } } ], "responses": { "200": { "content": { "application/json": { "example": { "createdAt": "2026-08-14T11:00:00.000Z", "deletionCounts": { "endpoints": 2, "keys": 4, "runs": 37, "schedules": 5 }, "environmentKinds": ["test", "live"], "id": "proj_01h8xyz9k2m4n6p8r0t2v4w6y8", "name": "Customer reminders", "status": "active", "version": 2 }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "createdAt": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, { "type": "null" } ] }, "deletionCounts": { "type": "object", "properties": { "endpoints": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "keys": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "runs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "schedules": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["endpoints", "keys", "runs", "schedules"] }, "environmentKinds": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "string", "enum": ["test", "live"] } }, "id": { "type": "string", "pattern": "^proj_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "status": { "type": "string", "enum": ["active", "archived"] }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "createdAt", "deletionCounts", "environmentKinds", "id", "name", "status", "version" ] } } }, "description": "Rename a project", "headers": { "ETag": { "required": true, "schema": { "type": "string", "pattern": "^\"([1-9][0-9]{0,18})\"$" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "404": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["not_found"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: not_found." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["state_conflict", "version_conflict"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: state_conflict, version_conflict." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Rename a project", "security": [ { "apiCredential": ["projects:write"] }, { "memberSession": ["projects:write"], "memberSessionEnvironment": [], "memberSessionProject": [] } ], "requestBody": { "content": { "application/json": { "example": { "name": "Customer reminders" }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 } }, "required": ["name"] } } }, "required": true } }, "delete": { "description": "Permanently deletes an archived project and everything it owns immediately: schedules and encrypted payloads, occurrences and delivery attempts, endpoints and their signing keys, API credentials and their audit events, OAuth grants and tokens, test sinks, and control-plane projections. The operation is refused while the project is active and names archiving as the required first move. Its response reports the schedules, endpoints, keys and runs destroyed. Only organization administrators may perform it, and there is no restore operation.", "operationId": "projects.delete", "parameters": [ { "in": "path", "name": "projectId", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string", "pattern": "^\"([1-9][0-9]{0,18})\"$" } } ], "responses": { "200": { "content": { "application/json": { "example": { "deleted": true, "destroyed": { "endpoints": 2, "keys": 4, "runs": 37, "schedules": 5 } }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deleted": { "type": "boolean", "const": true }, "destroyed": { "type": "object", "properties": { "endpoints": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "keys": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "runs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "schedules": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["endpoints", "keys", "runs", "schedules"] } }, "required": ["deleted", "destroyed"] } } }, "description": "Delete an archived project" }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "404": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["not_found"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: not_found." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["state_conflict", "version_conflict"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: state_conflict, version_conflict." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Delete an archived project", "security": [ { "apiCredential": ["projects:administer"] }, { "memberSession": ["projects:administer"], "memberSessionEnvironment": [], "memberSessionProject": [] } ] } }, "/v1/projects/{projectId}/archive": { "post": { "description": "Archives or restores the caller's project. Archiving parks the complete project: no new occurrence is dispatched, while schedules, endpoints, keys, grants and retained history remain intact. Restoring clears that project-wide hold without rewriting any schedule; an occurrence whose instant passed while archived becomes due, matching schedule pause and resume. Only organization administrators may make this project-wide change.", "operationId": "projects.archive", "parameters": [ { "in": "path", "name": "projectId", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string", "pattern": "^\"([1-9][0-9]{0,18})\"$" } } ], "responses": { "200": { "content": { "application/json": { "example": { "createdAt": "2026-08-14T11:00:00.000Z", "deletionCounts": { "endpoints": 2, "keys": 4, "runs": 37, "schedules": 5 }, "environmentKinds": ["test", "live"], "id": "proj_01h8xyz9k2m4n6p8r0t2v4w6y8", "name": "Customer reminders", "status": "archived", "version": 2 }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "createdAt": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, { "type": "null" } ] }, "deletionCounts": { "type": "object", "properties": { "endpoints": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "keys": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "runs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "schedules": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["endpoints", "keys", "runs", "schedules"] }, "environmentKinds": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "string", "enum": ["test", "live"] } }, "id": { "type": "string", "pattern": "^proj_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "status": { "type": "string", "enum": ["active", "archived"] }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "createdAt", "deletionCounts", "environmentKinds", "id", "name", "status", "version" ] } } }, "description": "Archive or restore a project", "headers": { "ETag": { "required": true, "schema": { "type": "string", "pattern": "^\"([1-9][0-9]{0,18})\"$" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "404": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["not_found"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: not_found." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["state_conflict", "version_conflict"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: state_conflict, version_conflict." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Archive or restore a project", "security": [ { "apiCredential": ["projects:administer"] }, { "memberSession": ["projects:administer"], "memberSessionEnvironment": [], "memberSessionProject": [] } ], "requestBody": { "content": { "application/json": { "example": { "archived": true }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "archived": { "type": "boolean" } }, "required": ["archived"] } } }, "required": true } } }, "/v1/grants": { "get": { "description": "Lists the applications this member has connected to their own account, newest first, across every project in their organization — because a person connects an application, not a project. Revoked connections stay in the listing with the instant and the reason they ended: a connection nobody can see is one nobody can audit. This is a signed-in member's view of their own delegations. An application holding a grant cannot read it, which is why the operation accepts no API credential and no access token, and why it is on no agent's tool list.", "operationId": "grants.list", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "client": { "id": "oc_01h8xyz9k2m4n6p8r0t2v4w6y8", "name": "Flow XO" }, "createdAt": "2026-08-14T11:00:00.000Z", "environmentKind": "test", "id": "og_01h8xyz9k2m4n6p8r0t2v4w6y8", "lastUsedAt": "2026-08-15T09:12:00.000Z", "project": "proj_01h8xyz9k2m4n6p8r0t2v4w6y8", "scopes": ["schedules:read", "schedules:write"], "status": "active" } ] }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "client": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^oc_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "name": { "type": "string" } }, "required": ["id", "name"] }, "createdAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "environmentKind": { "type": "string", "enum": ["test", "live"] }, "id": { "type": "string", "pattern": "^og_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "lastUsedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "project": { "type": "string", "pattern": "^proj_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "revocationReason": { "type": "string", "enum": [ "authorization-code-replayed", "client-revoked", "member-revoked", "refresh-token-replayed" ] }, "revokedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "scopes": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "credentials:administer", "billing:write", "credentials:read", "credentials:write", "endpoints:read", "endpoints:write", "forecast:read", "grants:read", "grants:write", "occurrences:read", "occurrences:redeliver", "projects:administer", "projects:read", "projects:write", "schedules:read", "schedules:write", "usage:read" ] } }, "status": { "type": "string", "enum": ["active", "revoked"] } }, "required": [ "client", "createdAt", "environmentKind", "id", "project", "scopes", "status" ] } } }, "required": ["data"] } } }, "description": "List the member's connected applications" }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "List the member's connected applications", "security": [ { "memberSession": ["grants:read"] } ] } }, "/v1/grants/{grantId}": { "delete": { "description": "Disconnects one application, ending every token that grant ever issued — the access tokens and the refresh token together. The grant stays readable afterwards with the instant and the reason it ended. Only the member who granted it can disconnect it, and a grant belonging to somebody else answers exactly as one that does not exist.", "operationId": "grants.revoke", "parameters": [ { "in": "path", "name": "grantId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "grant": { "client": { "id": "oc_01h8xyz9k2m4n6p8r0t2v4w6y8", "name": "Flow XO" }, "createdAt": "2026-08-14T11:00:00.000Z", "environmentKind": "test", "id": "og_01h8xyz9k2m4n6p8r0t2v4w6y8", "project": "proj_01h8xyz9k2m4n6p8r0t2v4w6y8", "revocationReason": "member-revoked", "revokedAt": "2026-08-15T10:00:00.000Z", "scopes": ["schedules:read", "schedules:write"], "status": "revoked" } }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "grant": { "type": "object", "properties": { "client": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^oc_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "name": { "type": "string" } }, "required": ["id", "name"] }, "createdAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "environmentKind": { "type": "string", "enum": ["test", "live"] }, "id": { "type": "string", "pattern": "^og_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "lastUsedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "project": { "type": "string", "pattern": "^proj_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "revocationReason": { "type": "string", "enum": [ "authorization-code-replayed", "client-revoked", "member-revoked", "refresh-token-replayed" ] }, "revokedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "scopes": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "credentials:administer", "billing:write", "credentials:read", "credentials:write", "endpoints:read", "endpoints:write", "forecast:read", "grants:read", "grants:write", "occurrences:read", "occurrences:redeliver", "projects:administer", "projects:read", "projects:write", "schedules:read", "schedules:write", "usage:read" ] } }, "status": { "type": "string", "enum": ["active", "revoked"] } }, "required": [ "client", "createdAt", "environmentKind", "id", "project", "scopes", "status" ] } }, "required": ["grant"] } } }, "description": "Disconnect an application" }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "404": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["not_found"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: not_found." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Disconnect an application", "security": [ { "memberSession": ["grants:write"] } ] } }, "/v1/credentials/{credentialId}/rotate": { "post": { "description": "Replaces a credential with a new one and gives the original a deadline, so consumers can pick up the new secret before the old stops working. The replacement is a new credential with its own identifier and the same authority and scopes; the original keeps working until it expires, then refuses with `credential_expired` rather than `credential_revoked`. `overlapSeconds` may only shorten the window — the default is also the maximum — and zero retires the original immediately. The new secret is in this response and in no other. Some calls need more: credentials:administer is required as well when the target was not created by the caller, and the call is refused `scope_missing` without it.", "operationId": "credentials.rotate", "parameters": [ { "in": "path", "name": "credentialId", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "content": { "application/json": { "example": { "credential": { "createdAt": "2026-07-28T15:00:00.000Z", "displayPrefix": "pt_test_e5f6g7h8", "environmentKind": "test", "id": "ak_01h8xyz9k2m4n6p8r0t2v4w6y9", "project": "proj_01h8xyz9k2m4n6p8r0t2v4w6y8", "scopes": ["schedules:write"], "secret": "pt_test_e5f6g7h8", "shownOnce": true }, "retired": { "createdAt": "2026-07-28T15:00:00.000Z", "displayPrefix": "pt_test_a1b2c3d4", "environmentKind": "test", "expiresAt": "2026-07-29T15:00:00.000Z", "id": "ak_01h8xyz9k2m4n6p8r0t2v4w6y8", "project": "proj_01h8xyz9k2m4n6p8r0t2v4w6y8", "supersededBy": "ak_01h8xyz9k2m4n6p8r0t2v4w6y9", "scopes": ["schedules:write"] } }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "credential": { "type": "object", "properties": { "createdAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "displayPrefix": { "type": "string", "pattern": "^pt_(?:live|test)_[0-9a-z]{8}$" }, "environmentKind": { "type": "string", "enum": ["test", "live"] }, "expiresAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "id": { "type": "string", "pattern": "^ak_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "issuedBy": { "type": "string", "minLength": 1 }, "lastUsedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "project": { "type": "string", "pattern": "^proj_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "revokedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "supersededBy": { "type": "string", "pattern": "^ak_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "scopes": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "credentials:administer", "billing:write", "credentials:read", "credentials:write", "endpoints:read", "endpoints:write", "forecast:read", "grants:read", "grants:write", "occurrences:read", "occurrences:redeliver", "projects:administer", "projects:read", "projects:write", "schedules:read", "schedules:write", "usage:read" ] } }, "secret": { "type": "string", "minLength": 48 }, "shownOnce": { "type": "boolean", "const": true } }, "required": [ "createdAt", "displayPrefix", "environmentKind", "id", "project", "scopes", "secret", "shownOnce" ] }, "retired": { "type": "object", "properties": { "createdAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "displayPrefix": { "type": "string", "pattern": "^pt_(?:live|test)_[0-9a-z]{8}$" }, "environmentKind": { "type": "string", "enum": ["test", "live"] }, "expiresAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "id": { "type": "string", "pattern": "^ak_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "issuedBy": { "type": "string", "minLength": 1 }, "lastUsedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "project": { "type": "string", "pattern": "^proj_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "revokedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "supersededBy": { "type": "string", "pattern": "^ak_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "scopes": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "credentials:administer", "billing:write", "credentials:read", "credentials:write", "endpoints:read", "endpoints:write", "forecast:read", "grants:read", "grants:write", "occurrences:read", "occurrences:redeliver", "projects:administer", "projects:read", "projects:write", "schedules:read", "schedules:write", "usage:read" ] } } }, "required": [ "createdAt", "displayPrefix", "environmentKind", "id", "project", "scopes" ] } }, "required": ["credential", "retired"] } } }, "description": "Rotate an API credential" }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "404": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["not_found"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: not_found." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["project_archived"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: project_archived." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Rotate an API credential", "security": [ { "apiCredential": ["credentials:write"] }, { "memberSession": ["credentials:write"], "memberSessionEnvironment": [], "memberSessionProject": [] } ], "requestBody": { "content": { "application/json": { "example": { "overlapSeconds": 3600 }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "overlapSeconds": { "type": "integer", "minimum": 0, "maximum": 86400 } } } } }, "required": false } } }, "/v1/credentials/{credentialId}": { "delete": { "description": "Revokes a credential immediately, with no overlap. The credential stops verifying on the next request and refuses with `credential_revoked`. The row survives its revocation so the credential's history remains answerable, and revoking a credential that is already revoked reports the original revocation rather than moving it. A credential belonging to another project is indistinguishable from one that does not exist. Some calls need more: credentials:administer is required as well when the target was not created by the caller, and the call is refused `scope_missing` without it.", "operationId": "credentials.revoke", "parameters": [ { "in": "path", "name": "credentialId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "credential": { "createdAt": "2026-07-28T15:00:00.000Z", "displayPrefix": "pt_test_a1b2c3d4", "environmentKind": "test", "id": "ak_01h8xyz9k2m4n6p8r0t2v4w6y8", "project": "proj_01h8xyz9k2m4n6p8r0t2v4w6y8", "revokedAt": "2026-07-28T16:00:00.000Z", "scopes": ["schedules:write"] } }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "credential": { "type": "object", "properties": { "createdAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "displayPrefix": { "type": "string", "pattern": "^pt_(?:live|test)_[0-9a-z]{8}$" }, "environmentKind": { "type": "string", "enum": ["test", "live"] }, "expiresAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "id": { "type": "string", "pattern": "^ak_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "issuedBy": { "type": "string", "minLength": 1 }, "lastUsedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "project": { "type": "string", "pattern": "^proj_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "revokedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "supersededBy": { "type": "string", "pattern": "^ak_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "scopes": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "credentials:administer", "billing:write", "credentials:read", "credentials:write", "endpoints:read", "endpoints:write", "forecast:read", "grants:read", "grants:write", "occurrences:read", "occurrences:redeliver", "projects:administer", "projects:read", "projects:write", "schedules:read", "schedules:write", "usage:read" ] } } }, "required": [ "createdAt", "displayPrefix", "environmentKind", "id", "project", "scopes" ] } }, "required": ["credential"] } } }, "description": "Revoke an API credential" }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "404": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["not_found"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: not_found." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["project_archived"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: project_archived." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Revoke an API credential", "security": [ { "apiCredential": ["credentials:write"] }, { "memberSession": ["credentials:write"], "memberSessionEnvironment": [], "memberSessionProject": [] } ] } }, "/v1/schedules": { "post": { "description": "Creates a schedule and returns it together with its first planned occurrence. Give exactly one of `at`, `delaySeconds`, `everySeconds` and `cron`. An optional `partitionKey` selects a fairness lane inside this project and environment; it is fixed after create. Add a verified `endpoint` to deliver each occurrence there; optional JSON `data` is encrypted before PostgreSQL persistence, placed in the signed callback, and returned as given by a schedule read. `at` and `delaySeconds` fire once; a delay is converted to an absolute instant when the request is accepted, so a schedule created either way reads back the same afterwards. `everySeconds` is a fixed duration and its first occurrence falls one interval after acceptance — it stays the same length across a daylight-saving change, and takes no timezone for that reason. `cron` is a wall clock: it is read against the IANA `timeZone` sent with it, `UTC` when none is, and the first occurrence is the first instant the expression names after acceptance. Where the clocks go forward and the wall time named does not exist that day, the occurrence falls at the first instant after the gap; where they go back and it happens twice, it falls once, at the earlier of the two. A recurring schedule is materialized one occurrence at a time: the next one is planned once the current one is due, so a read always shows one occurrence still to come. `lateness.policy` decides what happens when an occurrence reaches its first attempt after its planned instant: `skipAhead` never carries a recurring arrival across its next scheduled instant (and a shorter custom window may retire it earlier), while `catchUp` admits one arrival within `maxStalenessSeconds` even after later recurrence instants passed. A one-shot has no next recurrence, so either explicit policy uses its window and the default is `catchUp` with 24 hours; recurring schedules default to `skipAhead`, and a `catchUp` without an override has a one-interval window. A retry already in progress is exempt because it arrived and failed; its retry and give-up policy still decide the outcome. The organization, project and environment come from the verified principal; a body cannot name them, and the endpoint must belong to the same tuple, so a credential issued for one project can only ever create schedules in that project. Send an `Idempotency-Key` to make a retry safe: the identical request returns the schedule that key already created, marked `Idempotency-Replayed: true`, and creates nothing further; the same key with a different request is refused `idempotency_key_reused`. A replay reports the schedule **as it stands now**, not a frozen copy of the first response — if it was paused in between, the replay says so.", "operationId": "schedules.create", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string", "minLength": 16, "maxLength": 255, "pattern": "^[\\x20-\\x7e]+$" } } ], "responses": { "201": { "content": { "application/json": { "example": { "occurrence": { "attemptCount": 0, "generation": 1, "id": "occ_01h8xyz9k2m4n6p8r0t2v4w6y8", "plannedFor": "2026-07-28T15:00:00.000Z", "schedule": "sch_01h8xyz9k2m4n6p8r0t2v4w6y8", "sequence": 1, "state": "planned" }, "schedule": { "createdAt": "2026-07-28T14:59:00.000Z", "endpoint": "ep_01h8xyz9k2m4n6p8r0t2v4w6y8", "generation": 1, "id": "sch_01h8xyz9k2m4n6p8r0t2v4w6y8", "latencyClass": "realtime", "lateness": { "policy": "catchUp" }, "partitionKey": "campaign.spring", "recurrence": { "kind": "at" }, "status": "active", "updatedAt": "2026-07-28T14:59:00.000Z", "version": 1 } }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "occurrence": { "type": "object", "properties": { "attemptCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "firstAttemptLatenessMs": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "firstAttemptStartedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "timingEligibility": { "type": "string", "enum": [ "eligible", "customer_blocked", "platform_blocked" ] }, "timingEligibilityReason": { "type": "string", "minLength": 1, "maxLength": 128 }, "timingPolicyVersion": { "type": "string", "minLength": 1, "maxLength": 64 }, "generation": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "id": { "type": "string", "pattern": "^occ_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "plannedFor": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "schedule": { "type": "string", "pattern": "^sch_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "sequence": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "settledAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "state": { "type": "string", "enum": [ "planned", "due", "dispatching", "retry_wait", "ambiguous", "succeeded", "terminal_failed", "cancelled", "skipped_stale" ] } }, "required": [ "attemptCount", "generation", "id", "plannedFor", "schedule", "sequence", "state" ] }, "schedule": { "type": "object", "properties": { "archivedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "data": { "$ref": "#/$defs/__schema0" }, "createdAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "delivery": { "type": "object", "properties": { "completion": { "type": "string", "enum": ["response", "callback"] }, "maxDurationSeconds": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "onOverlap": { "type": "string", "enum": ["skip", "queue"] } }, "required": [ "completion", "maxDurationSeconds", "onOverlap" ] }, "endpoint": { "type": "string", "pattern": "^ep_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "endpointUrl": { "type": "string", "format": "uri" }, "generation": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "id": { "type": "string", "pattern": "^sch_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "latencyClass": { "type": "string", "enum": ["realtime", "bulk"] }, "lateness": { "type": "object", "properties": { "maxStalenessSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "policy": { "type": "string", "enum": ["skipAhead", "catchUp"] } }, "required": ["policy"] }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "partitionKey": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9._:-]+$" }, "nextDueAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "recurrence": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "at" } }, "required": ["kind"] }, { "type": "object", "properties": { "everySeconds": { "type": "integer", "minimum": 60, "maximum": 31536000 }, "kind": { "type": "string", "const": "every" } }, "required": ["everySeconds", "kind"] }, { "type": "object", "properties": { "cron": { "type": "string", "minLength": 1, "maxLength": 120 }, "kind": { "type": "string", "const": "cron" }, "timeZone": {} }, "required": ["cron", "kind", "timeZone"] } ] }, "status": { "type": "string", "enum": ["active", "paused", "cancelled", "completed"] }, "updatedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "createdAt", "generation", "id", "latencyClass", "lateness", "recurrence", "status", "updatedAt", "version" ] } }, "required": ["occurrence", "schedule"], "$defs": { "__schema0": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/$defs/__schema0" } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/$defs/__schema0" } } ] } } } } }, "description": "Create a schedule", "headers": { "ETag": { "required": true, "schema": { "type": "string", "pattern": "^\"([1-9][0-9]{0,18})\"$" } }, "Idempotency-Replayed": { "required": false, "schema": { "type": "string", "const": "true" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "404": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["not_found"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: not_found." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "idempotency_key_reused", "plan_limit_reached", "project_archived", "state_conflict" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: idempotency_key_reused, plan_limit_reached, project_archived, state_conflict." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Create a schedule", "security": [ { "apiCredential": ["schedules:write"] }, { "memberSession": ["schedules:write"], "memberSessionEnvironment": [], "memberSessionProject": [] } ], "requestBody": { "content": { "application/json": { "example": { "cron": "0 9 * * 1-5", "data": { "report": "daily" }, "endpoint": "ep_01h8xyz9k2m4n6p8r0t2v4w6y8", "lateness": { "maxStalenessSeconds": 3600, "policy": "catchUp" }, "partitionKey": "campaign.spring", "timeZone": "Europe/London" }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "at": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "cron": { "type": "string", "minLength": 1, "maxLength": 120 }, "data": { "$ref": "#/$defs/__schema0" }, "delaySeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 158000000 }, "delivery": { "type": "object", "properties": { "onOverlap": { "type": "string", "enum": ["skip", "queue"] }, "completion": { "type": "string", "enum": ["response", "callback"] }, "maxDurationSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 86400, "description": "How long the receiver may take to answer, in seconds" } }, "additionalProperties": false }, "everySeconds": { "type": "integer", "minimum": 60, "maximum": 31536000 }, "endpoint": { "type": "string", "pattern": "^ep_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "latencyClass": { "type": "string", "enum": ["realtime", "bulk"] }, "lateness": { "type": "object", "properties": { "maxStalenessSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "policy": { "type": "string", "enum": ["skipAhead", "catchUp"] } }, "additionalProperties": false }, "partitionKey": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9._:-]+$" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "timeZone": { "type": "string", "minLength": 1 } }, "additionalProperties": false, "$defs": { "__schema0": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/$defs/__schema0" } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/$defs/__schema0" } } ] } } } } }, "required": true } }, "get": { "description": "Lists the caller's own schedules, oldest first, one page at a time. Archived schedules are left out: archiving is how a schedule leaves the working set, and a listing that still carried them would make the operation pointless. Give `endpoint` to keep the page to the schedules that deliver to that endpoint — the way back from a destination to everything pointed at it, which is what somebody who disabled or is about to move an endpoint needs to see. Items are schedules rather than schedules-with-occurrences, because a cross-partition listing is served from a projection that holds a summary; read a schedule to get its authoritative next occurrence. Every page states whether it is authoritative or projected.", "operationId": "schedules.list", "parameters": [ { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "in": "query", "name": "dueBefore", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, { "in": "query", "name": "endpoint", "required": false, "schema": { "type": "string", "pattern": "^ep_[0-9abcdefghjkmnpqrstvwxyz]{26}$" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 } }, { "in": "query", "name": "order", "required": false, "schema": { "default": "created", "type": "string", "enum": ["created", "due"] } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "createdAt": "2026-07-28T14:59:00.000Z", "endpoint": "ep_01h8xyz9k2m4n6p8r0t2v4w6y8", "generation": 1, "id": "sch_01h8xyz9k2m4n6p8r0t2v4w6y8", "latencyClass": "realtime", "lateness": { "policy": "catchUp" }, "recurrence": { "kind": "at" }, "status": "active", "updatedAt": "2026-07-28T14:59:00.000Z", "version": 1 } ], "freshness": { "asOf": "2026-07-28T15:00:00.000Z", "kind": "projected", "lagSeconds": 0 }, "nextCursor": "eyJhIjoxNzg1MjUwODAwMDAwLCJpIjoic2NoXzAxaDh4eXo5azJtNG42cDhyMHQydjR3Nnk4IiwiayI6Ijk1MTM1NDZmIn0" }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "archivedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "data": { "$ref": "#/$defs/__schema0" }, "createdAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "delivery": { "type": "object", "properties": { "completion": { "type": "string", "enum": ["response", "callback"] }, "maxDurationSeconds": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "onOverlap": { "type": "string", "enum": ["skip", "queue"] } }, "required": [ "completion", "maxDurationSeconds", "onOverlap" ] }, "endpoint": { "type": "string", "pattern": "^ep_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "endpointUrl": { "type": "string", "format": "uri" }, "generation": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "id": { "type": "string", "pattern": "^sch_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "latencyClass": { "type": "string", "enum": ["realtime", "bulk"] }, "lateness": { "type": "object", "properties": { "maxStalenessSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "policy": { "type": "string", "enum": ["skipAhead", "catchUp"] } }, "required": ["policy"] }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "partitionKey": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9._:-]+$" }, "nextDueAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "recurrence": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "at" } }, "required": ["kind"] }, { "type": "object", "properties": { "everySeconds": { "type": "integer", "minimum": 60, "maximum": 31536000 }, "kind": { "type": "string", "const": "every" } }, "required": ["everySeconds", "kind"] }, { "type": "object", "properties": { "cron": { "type": "string", "minLength": 1, "maxLength": 120 }, "kind": { "type": "string", "const": "cron" }, "timeZone": {} }, "required": ["cron", "kind", "timeZone"] } ] }, "status": { "type": "string", "enum": [ "active", "paused", "cancelled", "completed" ] }, "updatedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "createdAt", "generation", "id", "latencyClass", "lateness", "recurrence", "status", "updatedAt", "version" ] } }, "freshness": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "authoritative" } }, "required": ["kind"] }, { "type": "object", "properties": { "asOf": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "kind": { "type": "string", "const": "projected" }, "lagSeconds": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["asOf", "kind", "lagSeconds"] } ] }, "nextCursor": { "type": "string", "minLength": 1 } }, "required": ["data", "freshness"], "$defs": { "__schema0": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/$defs/__schema0" } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/$defs/__schema0" } } ] } } } } }, "description": "List schedules" }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["project_archived"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: project_archived." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "List schedules", "security": [ { "apiCredential": ["schedules:read"] }, { "memberSession": ["schedules:read"], "memberSessionEnvironment": [], "memberSessionProject": [] } ] } }, "/v1/schedules/{scheduleId}": { "get": { "description": "Reads one schedule and its next occurrence from the partition that owns it. A schedule belonging to another organization, project or environment answers not_found rather than a refusal that would confirm it exists. The response carries the schedule's version as a strong ETag; send it back in `If-Match` to make a later write conditional on nothing having changed in between. The response carries the schedule's `data` when it has one, exactly as it was given; the listing leaves it off.", "operationId": "schedules.read", "parameters": [ { "in": "path", "name": "scheduleId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "occurrence": { "attemptCount": 0, "generation": 1, "id": "occ_01h8xyz9k2m4n6p8r0t2v4w6y8", "plannedFor": "2026-07-28T15:00:00.000Z", "schedule": "sch_01h8xyz9k2m4n6p8r0t2v4w6y8", "sequence": 1, "state": "planned" }, "schedule": { "data": { "report": "daily" }, "createdAt": "2026-07-28T14:59:00.000Z", "endpoint": "ep_01h8xyz9k2m4n6p8r0t2v4w6y8", "generation": 1, "id": "sch_01h8xyz9k2m4n6p8r0t2v4w6y8", "latencyClass": "realtime", "lateness": { "policy": "catchUp" }, "partitionKey": "campaign.spring", "recurrence": { "kind": "at" }, "status": "active", "updatedAt": "2026-07-28T14:59:00.000Z", "version": 1 } }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "occurrence": { "type": "object", "properties": { "attemptCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "firstAttemptLatenessMs": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "firstAttemptStartedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "timingEligibility": { "type": "string", "enum": [ "eligible", "customer_blocked", "platform_blocked" ] }, "timingEligibilityReason": { "type": "string", "minLength": 1, "maxLength": 128 }, "timingPolicyVersion": { "type": "string", "minLength": 1, "maxLength": 64 }, "generation": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "id": { "type": "string", "pattern": "^occ_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "plannedFor": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "schedule": { "type": "string", "pattern": "^sch_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "sequence": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "settledAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "state": { "type": "string", "enum": [ "planned", "due", "dispatching", "retry_wait", "ambiguous", "succeeded", "terminal_failed", "cancelled", "skipped_stale" ] } }, "required": [ "attemptCount", "generation", "id", "plannedFor", "schedule", "sequence", "state" ] }, "schedule": { "type": "object", "properties": { "archivedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "data": { "$ref": "#/$defs/__schema0" }, "createdAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "delivery": { "type": "object", "properties": { "completion": { "type": "string", "enum": ["response", "callback"] }, "maxDurationSeconds": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "onOverlap": { "type": "string", "enum": ["skip", "queue"] } }, "required": [ "completion", "maxDurationSeconds", "onOverlap" ] }, "endpoint": { "type": "string", "pattern": "^ep_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "endpointUrl": { "type": "string", "format": "uri" }, "generation": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "id": { "type": "string", "pattern": "^sch_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "latencyClass": { "type": "string", "enum": ["realtime", "bulk"] }, "lateness": { "type": "object", "properties": { "maxStalenessSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "policy": { "type": "string", "enum": ["skipAhead", "catchUp"] } }, "required": ["policy"] }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "partitionKey": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9._:-]+$" }, "nextDueAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "recurrence": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "at" } }, "required": ["kind"] }, { "type": "object", "properties": { "everySeconds": { "type": "integer", "minimum": 60, "maximum": 31536000 }, "kind": { "type": "string", "const": "every" } }, "required": ["everySeconds", "kind"] }, { "type": "object", "properties": { "cron": { "type": "string", "minLength": 1, "maxLength": 120 }, "kind": { "type": "string", "const": "cron" }, "timeZone": {} }, "required": ["cron", "kind", "timeZone"] } ] }, "status": { "type": "string", "enum": ["active", "paused", "cancelled", "completed"] }, "updatedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "createdAt", "generation", "id", "latencyClass", "lateness", "recurrence", "status", "updatedAt", "version" ] } }, "required": ["occurrence", "schedule"], "$defs": { "__schema0": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/$defs/__schema0" } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/$defs/__schema0" } } ] } } } } }, "description": "Read a schedule", "headers": { "ETag": { "required": true, "schema": { "type": "string", "pattern": "^\"([1-9][0-9]{0,18})\"$" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "404": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["not_found"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: not_found." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["project_archived"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: project_archived." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Read a schedule", "security": [ { "apiCredential": ["schedules:read"] }, { "memberSession": ["schedules:read"], "memberSessionEnvironment": [], "memberSessionProject": [] } ] }, "put": { "description": "Replaces a schedule's definition, starting a new generation. Takes the same four ways of saying when as a create, so a one-shot can be replaced by a recurring definition and the other way round. An omitted callback endpoint/data pair preserves the stored callback; sending `data` alone replaces the encrypted data for the current endpoint, and sending `endpoint` selects a verified endpoint in the same authority tuple. The occurrence planned under the old definition is settled `skipped_stale` and can never fire unless it was already in flight, in which case its immutable attempt is allowed to settle honestly; a fresh occurrence is planned under the new definition, and the old definition's series stops advancing. `lateness` is resolved afresh against the replacement recurrence: omit it for that kind's default, or state `skipAhead`, `catchUp`, and an optional `maxStalenessSeconds` override. The policy applies only before an occurrence's first attempt; a retry already in progress remains on its retry and give-up ladder. Send `If-Match` with the version you read to make this conditional; without it the replace is unconditional and the last writer wins. A cancelled or completed schedule cannot be replaced. `partitionKey` is fixed when the schedule is created: omit it to preserve the stored value or echo that exact value in a GET → modify → PUT flow. Adding, changing, or clearing it is refused as `invalid_request` with `/partitionKey` identified. `latencyClass` remains derived from the replacement recurrence when the caller omits it.", "operationId": "schedules.replace", "parameters": [ { "in": "path", "name": "scheduleId", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "If-Match", "required": false, "schema": { "type": "string", "pattern": "^\"([1-9][0-9]{0,18})\"$" } } ], "responses": { "200": { "content": { "application/json": { "example": { "occurrence": { "attemptCount": 0, "generation": 2, "id": "occ_01h8xyz9k2m4n6p8r0t2v4w6y9", "plannedFor": "2026-07-28T16:00:00.000Z", "schedule": "sch_01h8xyz9k2m4n6p8r0t2v4w6y8", "sequence": 1, "state": "planned" }, "schedule": { "createdAt": "2026-07-28T14:59:00.000Z", "endpoint": "ep_01h8xyz9k2m4n6p8r0t2v4w6y8", "generation": 2, "id": "sch_01h8xyz9k2m4n6p8r0t2v4w6y8", "latencyClass": "realtime", "lateness": { "policy": "catchUp" }, "partitionKey": "campaign.spring", "recurrence": { "kind": "at" }, "status": "active", "updatedAt": "2026-07-28T15:10:00.000Z", "version": 2 } }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "occurrence": { "type": "object", "properties": { "attemptCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "firstAttemptLatenessMs": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "firstAttemptStartedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "timingEligibility": { "type": "string", "enum": [ "eligible", "customer_blocked", "platform_blocked" ] }, "timingEligibilityReason": { "type": "string", "minLength": 1, "maxLength": 128 }, "timingPolicyVersion": { "type": "string", "minLength": 1, "maxLength": 64 }, "generation": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "id": { "type": "string", "pattern": "^occ_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "plannedFor": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "schedule": { "type": "string", "pattern": "^sch_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "sequence": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "settledAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "state": { "type": "string", "enum": [ "planned", "due", "dispatching", "retry_wait", "ambiguous", "succeeded", "terminal_failed", "cancelled", "skipped_stale" ] } }, "required": [ "attemptCount", "generation", "id", "plannedFor", "schedule", "sequence", "state" ] }, "schedule": { "type": "object", "properties": { "archivedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "data": { "$ref": "#/$defs/__schema0" }, "createdAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "delivery": { "type": "object", "properties": { "completion": { "type": "string", "enum": ["response", "callback"] }, "maxDurationSeconds": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "onOverlap": { "type": "string", "enum": ["skip", "queue"] } }, "required": [ "completion", "maxDurationSeconds", "onOverlap" ] }, "endpoint": { "type": "string", "pattern": "^ep_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "endpointUrl": { "type": "string", "format": "uri" }, "generation": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "id": { "type": "string", "pattern": "^sch_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "latencyClass": { "type": "string", "enum": ["realtime", "bulk"] }, "lateness": { "type": "object", "properties": { "maxStalenessSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "policy": { "type": "string", "enum": ["skipAhead", "catchUp"] } }, "required": ["policy"] }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "partitionKey": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9._:-]+$" }, "nextDueAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "recurrence": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "at" } }, "required": ["kind"] }, { "type": "object", "properties": { "everySeconds": { "type": "integer", "minimum": 60, "maximum": 31536000 }, "kind": { "type": "string", "const": "every" } }, "required": ["everySeconds", "kind"] }, { "type": "object", "properties": { "cron": { "type": "string", "minLength": 1, "maxLength": 120 }, "kind": { "type": "string", "const": "cron" }, "timeZone": {} }, "required": ["cron", "kind", "timeZone"] } ] }, "status": { "type": "string", "enum": ["active", "paused", "cancelled", "completed"] }, "updatedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "createdAt", "generation", "id", "latencyClass", "lateness", "recurrence", "status", "updatedAt", "version" ] } }, "required": ["occurrence", "schedule"], "$defs": { "__schema0": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/$defs/__schema0" } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/$defs/__schema0" } } ] } } } } }, "description": "Replace a schedule", "headers": { "ETag": { "required": true, "schema": { "type": "string", "pattern": "^\"([1-9][0-9]{0,18})\"$" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "404": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["not_found"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: not_found." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "plan_limit_reached", "project_archived", "state_conflict", "version_conflict" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: plan_limit_reached, project_archived, state_conflict, version_conflict." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Replace a schedule", "security": [ { "apiCredential": ["schedules:write"] }, { "memberSession": ["schedules:write"], "memberSessionEnvironment": [], "memberSessionProject": [] } ], "requestBody": { "content": { "application/json": { "example": { "data": { "report": "weekly" }, "everySeconds": 86400, "endpoint": "ep_01h8xyz9k2m4n6p8r0t2v4w6y8", "lateness": { "maxStalenessSeconds": 7200, "policy": "catchUp" }, "partitionKey": "campaign.spring" }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "at": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "cron": { "type": "string", "minLength": 1, "maxLength": 120 }, "data": { "$ref": "#/$defs/__schema0" }, "delaySeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 158000000 }, "delivery": { "type": "object", "properties": { "onOverlap": { "type": "string", "enum": ["skip", "queue"] }, "completion": { "type": "string", "enum": ["response", "callback"] }, "maxDurationSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 86400, "description": "How long the receiver may take to answer, in seconds" } }, "additionalProperties": false }, "everySeconds": { "type": "integer", "minimum": 60, "maximum": 31536000 }, "endpoint": { "type": "string", "pattern": "^ep_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "latencyClass": { "type": "string", "enum": ["realtime", "bulk"] }, "lateness": { "type": "object", "properties": { "maxStalenessSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "policy": { "type": "string", "enum": ["skipAhead", "catchUp"] } }, "additionalProperties": false }, "partitionKey": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9._:-]+$" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "timeZone": { "type": "string", "minLength": 1 } }, "additionalProperties": false, "$defs": { "__schema0": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/$defs/__schema0" } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/$defs/__schema0" } } ] } } } } }, "required": true } }, "delete": { "description": "Cancels a schedule and settles its occurrence `cancelled`, releasing the timer. Terminal: a cancelled schedule cannot be resumed or replaced, and cancelling one that is already cancelled changes nothing and returns the same version. A cancel that races its own occurrence becoming due still wins — the occurrence settles cancelled and no work is delivered — which is why this is a refusal-free retry rather than a race a client has to reason about. The schedule stays readable; archive it to take it out of the listing.", "operationId": "schedules.cancel", "parameters": [ { "in": "path", "name": "scheduleId", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "If-Match", "required": false, "schema": { "type": "string", "pattern": "^\"([1-9][0-9]{0,18})\"$" } } ], "responses": { "200": { "content": { "application/json": { "example": { "occurrence": { "attemptCount": 0, "generation": 1, "id": "occ_01h8xyz9k2m4n6p8r0t2v4w6y8", "plannedFor": "2026-07-28T15:00:00.000Z", "schedule": "sch_01h8xyz9k2m4n6p8r0t2v4w6y8", "sequence": 1, "settledAt": "2026-07-28T15:10:00.000Z", "state": "cancelled" }, "schedule": { "createdAt": "2026-07-28T14:59:00.000Z", "generation": 1, "id": "sch_01h8xyz9k2m4n6p8r0t2v4w6y8", "latencyClass": "realtime", "lateness": { "policy": "catchUp" }, "recurrence": { "kind": "at" }, "status": "cancelled", "updatedAt": "2026-07-28T15:10:00.000Z", "version": 2 } }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "occurrence": { "type": "object", "properties": { "attemptCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "firstAttemptLatenessMs": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "firstAttemptStartedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "timingEligibility": { "type": "string", "enum": [ "eligible", "customer_blocked", "platform_blocked" ] }, "timingEligibilityReason": { "type": "string", "minLength": 1, "maxLength": 128 }, "timingPolicyVersion": { "type": "string", "minLength": 1, "maxLength": 64 }, "generation": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "id": { "type": "string", "pattern": "^occ_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "plannedFor": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "schedule": { "type": "string", "pattern": "^sch_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "sequence": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "settledAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "state": { "type": "string", "enum": [ "planned", "due", "dispatching", "retry_wait", "ambiguous", "succeeded", "terminal_failed", "cancelled", "skipped_stale" ] } }, "required": [ "attemptCount", "generation", "id", "plannedFor", "schedule", "sequence", "state" ] }, "schedule": { "type": "object", "properties": { "archivedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "data": { "$ref": "#/$defs/__schema0" }, "createdAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "delivery": { "type": "object", "properties": { "completion": { "type": "string", "enum": ["response", "callback"] }, "maxDurationSeconds": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "onOverlap": { "type": "string", "enum": ["skip", "queue"] } }, "required": [ "completion", "maxDurationSeconds", "onOverlap" ] }, "endpoint": { "type": "string", "pattern": "^ep_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "endpointUrl": { "type": "string", "format": "uri" }, "generation": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "id": { "type": "string", "pattern": "^sch_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "latencyClass": { "type": "string", "enum": ["realtime", "bulk"] }, "lateness": { "type": "object", "properties": { "maxStalenessSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "policy": { "type": "string", "enum": ["skipAhead", "catchUp"] } }, "required": ["policy"] }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "partitionKey": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9._:-]+$" }, "nextDueAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "recurrence": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "at" } }, "required": ["kind"] }, { "type": "object", "properties": { "everySeconds": { "type": "integer", "minimum": 60, "maximum": 31536000 }, "kind": { "type": "string", "const": "every" } }, "required": ["everySeconds", "kind"] }, { "type": "object", "properties": { "cron": { "type": "string", "minLength": 1, "maxLength": 120 }, "kind": { "type": "string", "const": "cron" }, "timeZone": {} }, "required": ["cron", "kind", "timeZone"] } ] }, "status": { "type": "string", "enum": ["active", "paused", "cancelled", "completed"] }, "updatedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "createdAt", "generation", "id", "latencyClass", "lateness", "recurrence", "status", "updatedAt", "version" ] } }, "required": ["occurrence", "schedule"], "$defs": { "__schema0": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/$defs/__schema0" } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/$defs/__schema0" } } ] } } } } }, "description": "Cancel a schedule", "headers": { "ETag": { "required": true, "schema": { "type": "string", "pattern": "^\"([1-9][0-9]{0,18})\"$" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "404": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["not_found"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: not_found." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "project_archived", "state_conflict", "version_conflict" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: project_archived, state_conflict, version_conflict." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Cancel a schedule", "security": [ { "apiCredential": ["schedules:write"] }, { "memberSession": ["schedules:write"], "memberSessionEnvironment": [], "memberSessionProject": [] } ] } }, "/v1/forecast": { "get": { "description": "Counts the occurrences this project and environment expect to fire, in epoch-aligned time buckets, with a latency-class split on every bucket and an optional customer partition-key breakdown. A recurring series contributes every instant it fires inside the window rather than only its next one, and `nextFireCount` reports how many of a bucket's occurrences are a schedule's next firing. The answer states its own freshness and is refused rather than shortened when a partition cannot complete it. It carries counts only: no schedule identifier, callback destination, payload or endpoint detail has a field in the response.", "operationId": "forecast.read", "parameters": [ { "in": "query", "name": "breakdown", "required": false, "schema": { "default": "none", "type": "string", "enum": ["none", "partitionKey"] } }, { "in": "query", "name": "bucketSeconds", "required": false, "schema": { "default": 1800, "type": "integer", "minimum": 60, "maximum": 86400, "multipleOf": 60 } }, { "in": "query", "name": "from", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, { "in": "query", "name": "to", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } } ], "responses": { "200": { "content": { "application/json": { "example": { "buckets": [ { "byLatencyClass": { "bulk": 12, "realtime": 3 }, "byPartitionKey": { "campaign.spring": 9, "campaign.winter": 4 }, "count": 15, "nextFireCount": 4, "otherPartitionKeyCount": 2, "start": "2026-07-28T15:00:00.000Z" } ], "freshness": { "asOf": "2026-07-28T14:58:30.000Z", "kind": "projected", "lagSeconds": 90 }, "window": { "bucketSeconds": 1800, "from": "2026-07-28T15:00:00.000Z", "to": "2026-07-29T15:00:00.000Z" } }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "buckets": { "type": "array", "items": { "type": "object", "properties": { "byLatencyClass": { "type": "object", "properties": { "bulk": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "realtime": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["bulk", "realtime"] }, "byPartitionKey": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "count": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "nextFireCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "otherPartitionKeyCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "start": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, "required": [ "byLatencyClass", "count", "nextFireCount", "start" ] } }, "freshness": { "type": "object", "properties": { "asOf": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "kind": { "type": "string", "const": "projected" }, "lagSeconds": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["asOf", "kind", "lagSeconds"] }, "window": { "type": "object", "properties": { "bucketSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "to": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, "required": ["bucketSeconds", "from", "to"] } }, "required": ["buckets", "freshness", "window"] } } }, "description": "Forecast upcoming occurrences" }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["project_archived"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: project_archived." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Forecast upcoming occurrences", "security": [ { "apiCredential": ["forecast:read"] }, { "memberSession": ["forecast:read"], "memberSessionEnvironment": [], "memberSessionProject": [] } ] } }, "/v1/billing/summary": { "get": { "description": "Reads the verified principal's organization-wide prepaid execution position from the authoritative PostgreSQL ledger. Desired and effective revisions remain distinct, and pending stays true until D1 records PostgreSQL confirmation. Amounts are exact integer microdollars encoded as decimal strings; currency is USD and scale is six. Reserved credit has already been committed to a logical attempt but is not yet a settled debit. A missing hard cap means the customer elected no execution spending cap, never zero room. Shadow mode records what enforcement would have done without charging or blocking, and the activation boundary prevents retroactive charges.", "operationId": "billing.summary", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "activation": { "boundary": "2026-09-01T00:00:00.000Z", "mode": "shadow" }, "blockingReasons": [], "budgetPolicy": { "desired": { "advisoryBudget": null, "hardCap": null }, "desiredRevision": 0, "effectiveRevision": 0, "pending": false }, "credit": { "available": { "currency": "USD", "microdollars": "999980", "scale": 6 }, "consumed": { "currency": "USD", "microdollars": "10", "scale": 6 }, "reserved": { "currency": "USD", "microdollars": "10", "scale": 6 } }, "desiredRevision": 2, "effectiveRevision": 1, "freshness": { "kind": "authoritative" }, "includedProject": "proj_01h8xyz9k2m4n6p8r0t2v4w6y8", "period": { "automaticExecutionTopUp": { "pending": { "currency": "USD", "microdollars": "0", "scale": 6 }, "settled": { "currency": "USD", "microdollars": "0", "scale": 6 } }, "subscribedProjectFees": { "currency": "USD", "microdollars": "0", "scale": 6 }, "reservedUsage": { "currency": "USD", "microdollars": "10", "scale": 6 }, "settledUsage": { "currency": "USD", "microdollars": "10", "scale": 6 }, "start": "2026-09-01T00:00:00.000Z", "end": "2026-10-01T00:00:00.000Z" }, "pending": true, "priceVersion": "payg-v1", "trialExpiresAt": "2026-09-15T00:00:00.000Z" }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "activation": { "type": "object", "properties": { "boundary": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "mode": { "type": "string", "enum": ["disabled", "shadow", "enforced"] } }, "required": ["boundary", "mode"] }, "blockingReasons": { "type": "array", "items": { "type": "string", "enum": [ "billing-state-missing", "billing-account-closed", "project-ineligible", "insufficient-credit", "execution-cap-reached" ] } }, "budgetPolicy": { "type": "object", "properties": { "desired": { "type": "object", "properties": { "advisoryBudget": { "anyOf": [ { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] }, { "type": "null" } ] }, "hardCap": { "anyOf": [ { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] }, { "type": "null" } ] } }, "required": ["advisoryBudget", "hardCap"] }, "desiredRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "effectiveRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "pending": { "type": "boolean" } }, "required": [ "desired", "desiredRevision", "effectiveRevision", "pending" ] }, "closedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "credit": { "type": "object", "properties": { "available": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^-?(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "consumed": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "reserved": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] } }, "required": ["available", "consumed", "reserved"] }, "desiredRevision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "effectiveRevision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "freshness": { "type": "object", "properties": { "kind": { "type": "string", "const": "authoritative" } }, "required": ["kind"] }, "includedProject": { "type": "string", "pattern": "^proj_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "period": { "type": "object", "properties": { "advisoryBudget": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "hardCap": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "remainingToHardCap": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "advisoryBudgetProgress": { "type": "object", "properties": { "committed": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "remaining": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] } }, "required": ["committed", "remaining"] }, "automaticExecutionTopUp": { "type": "object", "properties": { "cap": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "pending": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "remainingToCap": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "settled": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] } }, "required": ["pending", "settled"] }, "subscribedProjectFees": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "reservedUsage": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "settledUsage": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "start": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "end": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, "required": [ "automaticExecutionTopUp", "subscribedProjectFees", "reservedUsage", "settledUsage", "start", "end" ] }, "pending": { "type": "boolean" }, "priceVersion": { "type": "string", "minLength": 1, "maxLength": 64 }, "trialExpiresAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, "required": [ "activation", "blockingReasons", "budgetPolicy", "credit", "desiredRevision", "effectiveRevision", "freshness", "pending", "priceVersion" ] } } }, "description": "Read exact execution-credit state" }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["project_archived"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: project_archived." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Read exact execution-credit state", "security": [ { "apiCredential": ["usage:read"] }, { "memberSession": ["usage:read"], "memberSessionEnvironment": [], "memberSessionProject": [] } ] } }, "/v1/billing/notices": { "get": { "description": "Lists the verified organization's durable billing notices with exact USD amounts, affected scope, payment state, a fixed same-page recovery path, and visible email delivery failure. Raw provider details, payment credentials, callback data and arbitrary URLs have no field.", "operationId": "billing.notices", "parameters": [ { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "amounts": { "available": { "currency": "USD", "microdollars": "1750000", "scale": 6 }, "threshold": { "currency": "USD", "microdollars": "2000000", "scale": 6 } }, "detail": "Available execution credit is below the configured USD 2.00 threshold.", "email": { "attempts": 3, "failureCode": "provider-unavailable", "lastAttemptAt": "2026-09-10T12:03:00.000Z", "state": "failed" }, "id": "billing-notice-example", "kind": "low-credit", "occurredAt": "2026-09-10T12:00:00.000Z", "payment": null, "recoveryPath": "#billing-funding", "resolvedAt": null, "scope": { "kind": "organization" }, "severity": "warning", "state": "active", "title": "Execution credit is low", "updatedAt": "2026-09-10T12:03:00.000Z" } ], "freshness": { "kind": "authoritative" } }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "amounts": { "type": "object", "properties": { "available": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] }, "gross": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] }, "limit": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] }, "threshold": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] } } }, "detail": { "type": "string", "minLength": 1, "maxLength": 512 }, "email": { "type": "object", "properties": { "attempts": { "type": "integer", "minimum": 0, "maximum": 100 }, "failureCode": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,127}$" }, "lastAttemptAt": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, { "type": "null" } ] }, "state": { "type": "string", "enum": [ "pending", "delivered", "failed", "suppressed" ] } }, "required": ["attempts", "lastAttemptAt", "state"] }, "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "kind": { "type": "string", "enum": [ "budget-warning", "budget-exhausted", "low-credit", "automatic-top-up-cap-reached", "funding-blocked", "payment-pending", "payment-succeeded", "payment-failed", "payment-authentication-required", "payment-outcome-unresolved", "service-restored" ] }, "occurredAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "payment": { "anyOf": [ { "type": "object", "properties": { "operation": { "type": "string", "minLength": 1, "maxLength": 255 }, "state": { "type": "string", "enum": [ "pending", "paid", "failed", "authentication-required", "action-required", "canceled", "refunded", "reversed", "disputed" ] } }, "required": ["operation", "state"] }, { "type": "null" } ] }, "recoveryPath": { "type": "string", "enum": [ "#billing", "#billing-funding", "#billing-notification-settings" ] }, "resolvedAt": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, { "type": "null" } ] }, "scope": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "organization" } }, "required": ["kind"] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "project" }, "project": { "type": "string", "pattern": "^proj_[0-9abcdefghjkmnpqrstvwxyz]{26}$" } }, "required": ["kind", "project"] } ] }, "severity": { "type": "string", "enum": ["warning", "critical", "recovery"] }, "state": { "type": "string", "enum": ["active", "resolved"] }, "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "updatedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, "required": [ "amounts", "detail", "email", "id", "kind", "occurredAt", "payment", "recoveryPath", "resolvedAt", "scope", "severity", "state", "title", "updatedAt" ] } }, "freshness": { "type": "object", "properties": { "kind": { "type": "string", "const": "authoritative" } }, "required": ["kind"] }, "nextCursor": { "type": "string", "minLength": 1 } }, "required": ["data", "freshness"] } } }, "description": "List persistent billing notices" }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["project_archived"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: project_archived." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "List persistent billing notices", "security": [ { "apiCredential": ["usage:read"] }, { "memberSession": ["usage:read"], "memberSessionEnvironment": [], "memberSessionProject": [] } ] } }, "/v1/billing/notification-settings": { "get": { "description": "Reads the USD 2.00 default low-credit threshold and optional-email choice. Critical email remains mandatory for owners and active billing-role members; addresses and contact management are absent.", "operationId": "billing.notificationsettings", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "criticalEmail": true, "freshness": { "kind": "authoritative" }, "lowCreditThreshold": { "currency": "USD", "microdollars": "2000000", "scale": 6 }, "noncriticalEmail": true, "recipients": { "billingContacts": "active-billing-role-members", "owners": true }, "revision": 1 }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "criticalEmail": { "type": "boolean", "const": true }, "freshness": { "type": "object", "properties": { "kind": { "type": "string", "const": "authoritative" } }, "required": ["kind"] }, "lowCreditThreshold": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "noncriticalEmail": { "type": "boolean" }, "recipients": { "type": "object", "properties": { "billingContacts": { "type": "string", "const": "active-billing-role-members" }, "owners": { "type": "boolean", "const": true } }, "required": ["billingContacts", "owners"] }, "revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "criticalEmail", "freshness", "lowCreditThreshold", "noncriticalEmail", "recipients", "revision" ] } } }, "description": "Read billing notification settings" }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["project_archived"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: project_archived." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Read billing notification settings", "security": [ { "apiCredential": ["usage:read"] }, { "memberSession": ["usage:read"], "memberSessionEnvironment": [], "memberSessionProject": [] } ] }, "patch": { "description": "Replaces the low-credit threshold and noncritical email choice at an expected revision. Critical email stays mandatory; idempotent retries converge and agents require explicit approval.", "operationId": "billing.notificationsettingsupdate", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "minLength": 16, "maxLength": 255, "pattern": "^[\\x20-\\x7e]+$" } } ], "responses": { "200": { "content": { "application/json": { "example": { "criticalEmail": true, "freshness": { "kind": "authoritative" }, "lowCreditThreshold": { "currency": "USD", "microdollars": "2000000", "scale": 6 }, "noncriticalEmail": true, "recipients": { "billingContacts": "active-billing-role-members", "owners": true }, "revision": 1 }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "criticalEmail": { "type": "boolean", "const": true }, "freshness": { "type": "object", "properties": { "kind": { "type": "string", "const": "authoritative" } }, "required": ["kind"] }, "lowCreditThreshold": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "noncriticalEmail": { "type": "boolean" }, "recipients": { "type": "object", "properties": { "billingContacts": { "type": "string", "const": "active-billing-role-members" }, "owners": { "type": "boolean", "const": true } }, "required": ["billingContacts", "owners"] }, "revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "criticalEmail", "freshness", "lowCreditThreshold", "noncriticalEmail", "recipients", "revision" ] } } }, "description": "Update billing notification settings", "headers": { "Idempotency-Replayed": { "required": false, "schema": { "type": "string", "const": "true" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "scope_missing", "test_to_live_escalation" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing, test_to_live_escalation." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "idempotency_key_reused", "project_archived", "revision_conflict" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: idempotency_key_reused, project_archived, revision_conflict." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Update billing notification settings", "security": [ { "apiCredential": ["billing:write"] }, { "memberSession": ["billing:write"], "memberSessionEnvironment": [], "memberSessionProject": [] } ], "requestBody": { "content": { "application/json": { "example": { "expectedRevision": 1, "lowCreditThreshold": { "currency": "USD", "microdollars": "2000000", "scale": 6 }, "noncriticalEmail": false }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "expectedRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "lowCreditThreshold": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "noncriticalEmail": { "type": "boolean" } }, "required": [ "expectedRevision", "lowCreditThreshold", "noncriticalEmail" ], "additionalProperties": false } } }, "required": true } } }, "/v1/billing/funding": { "get": { "description": "Reads the verified principal's authoritative execution-funding position, including available and reserved credit, amount owed, recurring project fees, the current UTC month's automatic-charge ceiling and its settled, pending and remaining gross authority, and bounded payment history. Manual purchases and project subscriptions are separately authorized and never consume the automatic ceiling. Pending gross charges include applicable tax; refunds never restore monthly automatic purchasing authority. Receipt and payment links are limited to supported provider-hosted HTTPS URLs.", "operationId": "billing.funding", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "automaticExecutionTopUp": { "ceiling": { "currency": "USD", "microdollars": "50000000", "scale": 6 }, "currentPeriod": { "end": "2026-10-01T00:00:00.000Z", "pending": { "currency": "USD", "microdollars": "10830000", "scale": 6 }, "remaining": { "currency": "USD", "microdollars": "29170000", "scale": 6 }, "settled": { "currency": "USD", "microdollars": "10000000", "scale": 6 }, "start": "2026-09-01T00:00:00.000Z" }, "rule": { "cooldownUntil": null, "desired": { "ceiling": { "currency": "USD", "microdollars": "50000000", "scale": 6 }, "credit": { "currency": "USD", "microdollars": "10000000", "scale": 6 }, "triggerBelow": { "currency": "USD", "microdollars": "2000000", "scale": 6 } }, "effective": { "ceiling": { "currency": "USD", "microdollars": "50000000", "scale": 6 }, "credit": { "currency": "USD", "microdollars": "10000000", "scale": 6 }, "triggerBelow": { "currency": "USD", "microdollars": "2000000", "scale": 6 } }, "state": "ready", "suspension": null }, "revision": 3 }, "credit": { "amountOwed": { "currency": "USD", "microdollars": "0", "scale": 6 }, "available": { "currency": "USD", "microdollars": "9000000", "scale": 6 }, "reserved": { "currency": "USD", "microdollars": "10", "scale": 6 } }, "freshness": { "kind": "authoritative" }, "paymentOperations": [ { "createdAt": "2026-09-10T12:00:00.000Z", "credit": { "currency": "USD", "microdollars": "10000000", "scale": 6 }, "gross": { "currency": "USD", "microdollars": "10830000", "scale": 6 }, "id": "funding-operation-example", "kind": "automatic", "paymentUrl": "https://pay.stripe.com/receipts/acct_example/example", "reason": "payment-required", "state": "pending", "tax": { "currency": "USD", "microdollars": "830000", "scale": 6 }, "taxStatus": "confirmed", "updatedAt": "2026-09-10T12:00:01.000Z" } ], "subscribedProjectFees": { "currency": "USD", "microdollars": "5000000", "scale": 6 } }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "automaticExecutionTopUp": { "type": "object", "properties": { "ceiling": { "anyOf": [ { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, { "type": "null" } ] }, "currentPeriod": { "type": "object", "properties": { "end": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "pending": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "remaining": { "anyOf": [ { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] }, { "type": "null" } ] }, "settled": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "start": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, "required": [ "end", "pending", "remaining", "settled", "start" ] }, "rule": { "type": "object", "properties": { "cooldownUntil": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, { "type": "null" } ] }, "desired": { "anyOf": [ { "type": "object", "properties": { "ceiling": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] }, "credit": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] }, "triggerBelow": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] } }, "required": [ "ceiling", "credit", "triggerBelow" ] }, { "type": "null" } ] }, "effective": { "anyOf": [ { "type": "object", "properties": { "ceiling": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] }, "credit": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] }, "triggerBelow": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] } }, "required": [ "ceiling", "credit", "triggerBelow" ] }, { "type": "null" } ] }, "setupUrl": { "type": "string", "maxLength": 4096, "format": "uri" }, "state": { "type": "string", "enum": [ "disabled", "payment-method-required", "ready" ] }, "suspension": { "anyOf": [ { "type": "object", "properties": { "at": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "reason": { "type": "string", "enum": [ "authentication-required", "payment-failed" ] } }, "required": ["at", "reason"] }, { "type": "null" } ] } }, "required": [ "cooldownUntil", "desired", "effective", "state", "suspension" ] }, "revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "ceiling", "currentPeriod", "rule", "revision" ] }, "credit": { "type": "object", "properties": { "amountOwed": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "available": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "reserved": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] } }, "required": ["amountOwed", "available", "reserved"] }, "freshness": { "type": "object", "properties": { "kind": { "type": "string", "const": "authoritative" } }, "required": ["kind"] }, "paymentOperations": { "maxItems": 25, "type": "array", "items": { "type": "object", "properties": { "createdAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "credit": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "gross": { "anyOf": [ { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] }, { "type": "null" } ] }, "id": { "type": "string", "minLength": 1, "maxLength": 255 }, "kind": { "type": "string", "enum": ["manual", "automatic"] }, "paymentUrl": { "type": "string", "maxLength": 4096, "format": "uri" }, "reason": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,127}$" }, "receiptUrl": { "type": "string", "maxLength": 4096, "format": "uri" }, "state": { "type": "string", "enum": [ "pending", "paid", "failed", "authentication-required", "action-required", "canceled", "refunded", "reversed", "disputed" ] }, "tax": { "anyOf": [ { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] }, { "type": "null" } ] }, "taxStatus": { "type": "string", "enum": ["calculated-at-checkout", "confirmed"] }, "updatedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, "required": [ "createdAt", "credit", "gross", "id", "kind", "state", "tax", "taxStatus", "updatedAt" ] } }, "subscribedProjectFees": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] } }, "required": [ "automaticExecutionTopUp", "credit", "freshness", "paymentOperations", "subscribedProjectFees" ] } } }, "description": "Read execution funding and payments" }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["project_archived"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: project_archived." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Read execution funding and payments", "security": [ { "apiCredential": ["usage:read"] }, { "memberSession": ["usage:read"], "memberSessionEnvironment": [], "memberSessionProject": [] } ] } }, "/v1/billing/funding/quote": { "post": { "description": "Previews an execution-credit purchase of at least USD 10 without creating a provider payment or granting credit. The quote binds its exact credit and current funding revision; tax and gross remain null with calculated-at-checkout status until an idempotent confirmed purchase creates authenticated hosted Checkout. This manual purchase has separate authority and never consumes the automatic execution top-up ceiling.", "operationId": "billing.fundingquote", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "credit": { "currency": "USD", "microdollars": "10000000", "scale": 6 }, "expectedRevision": 3, "expiresAt": "2026-09-10T12:05:00.000Z", "gross": null, "quote": "funding-quote-example", "tax": null, "taxStatus": "calculated-at-checkout" }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "credit": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "expectedRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "expiresAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "gross": { "type": "null", "const": null }, "quote": { "type": "string", "minLength": 1, "maxLength": 128 }, "tax": { "type": "null", "const": null }, "taxStatus": { "type": "string", "const": "calculated-at-checkout" } }, "required": [ "credit", "expectedRevision", "expiresAt", "gross", "quote", "tax", "taxStatus" ] } } }, "description": "Preview manual execution funding" }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "scope_missing", "test_to_live_escalation" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing, test_to_live_escalation." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "project_archived", "revision_conflict", "state_conflict" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: project_archived, revision_conflict, state_conflict." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Preview manual execution funding", "security": [ { "apiCredential": ["billing:write"] }, { "memberSession": ["billing:write"], "memberSessionEnvironment": [], "memberSessionProject": [] } ], "requestBody": { "content": { "application/json": { "example": { "credit": { "currency": "USD", "microdollars": "10000000", "scale": 6 } }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "credit": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] } }, "required": ["credit"], "additionalProperties": false } } }, "required": true } } }, "/v1/billing/funding/purchase": { "post": { "description": "Confirms one exact manual execution-credit quote and creates or replays its durable payment operation. Billing-owner authority and explicit agent approval apply; the Idempotency-Key preserves one payment identity across retries. Manual funding stays outside the automatic-charge ceiling. A browser redirect never grants credit: only authenticated provider reconciliation can move the operation to paid and grant its exact execution credit once, while the operation reports provider-confirmed tax and gross when known.", "operationId": "billing.purchase", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "minLength": 16, "maxLength": 255, "pattern": "^[\\x20-\\x7e]+$" } } ], "responses": { "201": { "content": { "application/json": { "example": { "automaticExecutionTopUp": { "ceiling": { "currency": "USD", "microdollars": "50000000", "scale": 6 }, "currentPeriod": { "end": "2026-10-01T00:00:00.000Z", "pending": { "currency": "USD", "microdollars": "10830000", "scale": 6 }, "remaining": { "currency": "USD", "microdollars": "29170000", "scale": 6 }, "settled": { "currency": "USD", "microdollars": "10000000", "scale": 6 }, "start": "2026-09-01T00:00:00.000Z" }, "rule": { "cooldownUntil": null, "desired": { "ceiling": { "currency": "USD", "microdollars": "50000000", "scale": 6 }, "credit": { "currency": "USD", "microdollars": "10000000", "scale": 6 }, "triggerBelow": { "currency": "USD", "microdollars": "2000000", "scale": 6 } }, "effective": { "ceiling": { "currency": "USD", "microdollars": "50000000", "scale": 6 }, "credit": { "currency": "USD", "microdollars": "10000000", "scale": 6 }, "triggerBelow": { "currency": "USD", "microdollars": "2000000", "scale": 6 } }, "state": "ready", "suspension": null }, "revision": 3 }, "credit": { "amountOwed": { "currency": "USD", "microdollars": "0", "scale": 6 }, "available": { "currency": "USD", "microdollars": "9000000", "scale": 6 }, "reserved": { "currency": "USD", "microdollars": "10", "scale": 6 } }, "freshness": { "kind": "authoritative" }, "paymentOperations": [ { "createdAt": "2026-09-10T12:00:00.000Z", "credit": { "currency": "USD", "microdollars": "10000000", "scale": 6 }, "gross": { "currency": "USD", "microdollars": "10830000", "scale": 6 }, "id": "funding-operation-example", "kind": "automatic", "paymentUrl": "https://pay.stripe.com/receipts/acct_example/example", "reason": "payment-required", "state": "pending", "tax": { "currency": "USD", "microdollars": "830000", "scale": 6 }, "taxStatus": "confirmed", "updatedAt": "2026-09-10T12:00:01.000Z" } ], "subscribedProjectFees": { "currency": "USD", "microdollars": "5000000", "scale": 6 } }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "automaticExecutionTopUp": { "type": "object", "properties": { "ceiling": { "anyOf": [ { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, { "type": "null" } ] }, "currentPeriod": { "type": "object", "properties": { "end": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "pending": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "remaining": { "anyOf": [ { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] }, { "type": "null" } ] }, "settled": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "start": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, "required": [ "end", "pending", "remaining", "settled", "start" ] }, "rule": { "type": "object", "properties": { "cooldownUntil": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, { "type": "null" } ] }, "desired": { "anyOf": [ { "type": "object", "properties": { "ceiling": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] }, "credit": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] }, "triggerBelow": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] } }, "required": [ "ceiling", "credit", "triggerBelow" ] }, { "type": "null" } ] }, "effective": { "anyOf": [ { "type": "object", "properties": { "ceiling": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] }, "credit": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] }, "triggerBelow": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] } }, "required": [ "ceiling", "credit", "triggerBelow" ] }, { "type": "null" } ] }, "setupUrl": { "type": "string", "maxLength": 4096, "format": "uri" }, "state": { "type": "string", "enum": [ "disabled", "payment-method-required", "ready" ] }, "suspension": { "anyOf": [ { "type": "object", "properties": { "at": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "reason": { "type": "string", "enum": [ "authentication-required", "payment-failed" ] } }, "required": ["at", "reason"] }, { "type": "null" } ] } }, "required": [ "cooldownUntil", "desired", "effective", "state", "suspension" ] }, "revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "ceiling", "currentPeriod", "rule", "revision" ] }, "credit": { "type": "object", "properties": { "amountOwed": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "available": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "reserved": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] } }, "required": ["amountOwed", "available", "reserved"] }, "freshness": { "type": "object", "properties": { "kind": { "type": "string", "const": "authoritative" } }, "required": ["kind"] }, "paymentOperations": { "maxItems": 25, "type": "array", "items": { "type": "object", "properties": { "createdAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "credit": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "gross": { "anyOf": [ { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] }, { "type": "null" } ] }, "id": { "type": "string", "minLength": 1, "maxLength": 255 }, "kind": { "type": "string", "enum": ["manual", "automatic"] }, "paymentUrl": { "type": "string", "maxLength": 4096, "format": "uri" }, "reason": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,127}$" }, "receiptUrl": { "type": "string", "maxLength": 4096, "format": "uri" }, "state": { "type": "string", "enum": [ "pending", "paid", "failed", "authentication-required", "action-required", "canceled", "refunded", "reversed", "disputed" ] }, "tax": { "anyOf": [ { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] }, { "type": "null" } ] }, "taxStatus": { "type": "string", "enum": ["calculated-at-checkout", "confirmed"] }, "updatedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, "required": [ "createdAt", "credit", "gross", "id", "kind", "state", "tax", "taxStatus", "updatedAt" ] } }, "subscribedProjectFees": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] } }, "required": [ "automaticExecutionTopUp", "credit", "freshness", "paymentOperations", "subscribedProjectFees" ] } } }, "description": "Confirm manual execution funding", "headers": { "Idempotency-Replayed": { "required": false, "schema": { "type": "string", "const": "true" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "scope_missing", "test_to_live_escalation" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing, test_to_live_escalation." }, "404": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["not_found"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: not_found." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "idempotency_key_reused", "project_archived", "revision_conflict", "state_conflict" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: idempotency_key_reused, project_archived, revision_conflict, state_conflict." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Confirm manual execution funding", "security": [ { "apiCredential": ["billing:write"] }, { "memberSession": ["billing:write"], "memberSessionEnvironment": [], "memberSessionProject": [] } ], "requestBody": { "content": { "application/json": { "example": { "confirmed": true, "expectedRevision": 3, "quote": "funding-quote-example" }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "confirmed": { "type": "boolean", "const": true }, "expectedRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "quote": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": ["confirmed", "expectedRevision", "quote"], "additionalProperties": false } } }, "required": true } } }, "/v1/billing/funding/ceiling": { "patch": { "description": "Replaces the billing owner's exact calendar-month ceiling for automatic execution-credit charges, or turns automatic payment authority off with null. The expected revision prevents stale authority changes, and the Idempotency-Key makes retries converge. This command requires explicit agent approval because it changes payment authority. Tax and pending gross commitments consume the ceiling; manual purchases and project subscriptions do not. Refunds do not restore authority already used in that UTC month. USD 50 is the suggested editable default, not a platform maximum.", "operationId": "billing.ceiling", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "minLength": 16, "maxLength": 255, "pattern": "^[\\x20-\\x7e]+$" } } ], "responses": { "200": { "content": { "application/json": { "example": { "automaticExecutionTopUp": { "ceiling": { "currency": "USD", "microdollars": "50000000", "scale": 6 }, "currentPeriod": { "end": "2026-10-01T00:00:00.000Z", "pending": { "currency": "USD", "microdollars": "10830000", "scale": 6 }, "remaining": { "currency": "USD", "microdollars": "29170000", "scale": 6 }, "settled": { "currency": "USD", "microdollars": "10000000", "scale": 6 }, "start": "2026-09-01T00:00:00.000Z" }, "rule": { "cooldownUntil": null, "desired": { "ceiling": { "currency": "USD", "microdollars": "50000000", "scale": 6 }, "credit": { "currency": "USD", "microdollars": "10000000", "scale": 6 }, "triggerBelow": { "currency": "USD", "microdollars": "2000000", "scale": 6 } }, "effective": { "ceiling": { "currency": "USD", "microdollars": "50000000", "scale": 6 }, "credit": { "currency": "USD", "microdollars": "10000000", "scale": 6 }, "triggerBelow": { "currency": "USD", "microdollars": "2000000", "scale": 6 } }, "state": "ready", "suspension": null }, "revision": 3 }, "credit": { "amountOwed": { "currency": "USD", "microdollars": "0", "scale": 6 }, "available": { "currency": "USD", "microdollars": "9000000", "scale": 6 }, "reserved": { "currency": "USD", "microdollars": "10", "scale": 6 } }, "freshness": { "kind": "authoritative" }, "paymentOperations": [ { "createdAt": "2026-09-10T12:00:00.000Z", "credit": { "currency": "USD", "microdollars": "10000000", "scale": 6 }, "gross": { "currency": "USD", "microdollars": "10830000", "scale": 6 }, "id": "funding-operation-example", "kind": "automatic", "paymentUrl": "https://pay.stripe.com/receipts/acct_example/example", "reason": "payment-required", "state": "pending", "tax": { "currency": "USD", "microdollars": "830000", "scale": 6 }, "taxStatus": "confirmed", "updatedAt": "2026-09-10T12:00:01.000Z" } ], "subscribedProjectFees": { "currency": "USD", "microdollars": "5000000", "scale": 6 } }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "automaticExecutionTopUp": { "type": "object", "properties": { "ceiling": { "anyOf": [ { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, { "type": "null" } ] }, "currentPeriod": { "type": "object", "properties": { "end": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "pending": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "remaining": { "anyOf": [ { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] }, { "type": "null" } ] }, "settled": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "start": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, "required": [ "end", "pending", "remaining", "settled", "start" ] }, "rule": { "type": "object", "properties": { "cooldownUntil": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, { "type": "null" } ] }, "desired": { "anyOf": [ { "type": "object", "properties": { "ceiling": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] }, "credit": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] }, "triggerBelow": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] } }, "required": [ "ceiling", "credit", "triggerBelow" ] }, { "type": "null" } ] }, "effective": { "anyOf": [ { "type": "object", "properties": { "ceiling": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] }, "credit": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] }, "triggerBelow": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] } }, "required": [ "ceiling", "credit", "triggerBelow" ] }, { "type": "null" } ] }, "setupUrl": { "type": "string", "maxLength": 4096, "format": "uri" }, "state": { "type": "string", "enum": [ "disabled", "payment-method-required", "ready" ] }, "suspension": { "anyOf": [ { "type": "object", "properties": { "at": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "reason": { "type": "string", "enum": [ "authentication-required", "payment-failed" ] } }, "required": ["at", "reason"] }, { "type": "null" } ] } }, "required": [ "cooldownUntil", "desired", "effective", "state", "suspension" ] }, "revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "ceiling", "currentPeriod", "rule", "revision" ] }, "credit": { "type": "object", "properties": { "amountOwed": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "available": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "reserved": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] } }, "required": ["amountOwed", "available", "reserved"] }, "freshness": { "type": "object", "properties": { "kind": { "type": "string", "const": "authoritative" } }, "required": ["kind"] }, "paymentOperations": { "maxItems": 25, "type": "array", "items": { "type": "object", "properties": { "createdAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "credit": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "gross": { "anyOf": [ { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] }, { "type": "null" } ] }, "id": { "type": "string", "minLength": 1, "maxLength": 255 }, "kind": { "type": "string", "enum": ["manual", "automatic"] }, "paymentUrl": { "type": "string", "maxLength": 4096, "format": "uri" }, "reason": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,127}$" }, "receiptUrl": { "type": "string", "maxLength": 4096, "format": "uri" }, "state": { "type": "string", "enum": [ "pending", "paid", "failed", "authentication-required", "action-required", "canceled", "refunded", "reversed", "disputed" ] }, "tax": { "anyOf": [ { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] }, { "type": "null" } ] }, "taxStatus": { "type": "string", "enum": ["calculated-at-checkout", "confirmed"] }, "updatedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, "required": [ "createdAt", "credit", "gross", "id", "kind", "state", "tax", "taxStatus", "updatedAt" ] } }, "subscribedProjectFees": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] } }, "required": [ "automaticExecutionTopUp", "credit", "freshness", "paymentOperations", "subscribedProjectFees" ] } } }, "description": "Set the automatic payment ceiling", "headers": { "Idempotency-Replayed": { "required": false, "schema": { "type": "string", "const": "true" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "scope_missing", "test_to_live_escalation" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing, test_to_live_escalation." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "idempotency_key_reused", "project_archived", "revision_conflict", "state_conflict" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: idempotency_key_reused, project_archived, revision_conflict, state_conflict." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Set the automatic payment ceiling", "security": [ { "apiCredential": ["billing:write"] }, { "memberSession": ["billing:write"], "memberSessionEnvironment": [], "memberSessionProject": [] } ], "requestBody": { "content": { "application/json": { "example": { "automaticExecutionTopUpCeiling": { "currency": "USD", "microdollars": "50000000", "scale": 6 }, "expectedRevision": 3 }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "automaticExecutionTopUpCeiling": { "anyOf": [ { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, { "type": "null" } ] }, "expectedRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "automaticExecutionTopUpCeiling", "expectedRevision" ], "additionalProperties": false } } }, "required": true } } }, "/v1/billing/funding/auto-top-up/preview": { "post": { "description": "Previews one complete automatic execution-credit top-up rule without changing payment authority or contacting the payment provider. Enable and edit replace the fixed credit amount, usable-balance trigger and UTC-month gross ceiling together; disable and resume name those exact intents. The preview reports the current and proposed rule, whether authority expands, existing monthly commitments and separate recurring project fees. USD 10 below USD 2 within USD 50 is a suggested editable rule, not a platform maximum or target-balance refill.", "operationId": "billing.autotopuppreview", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "action": "enable", "after": { "ceiling": { "currency": "USD", "microdollars": "50000000", "scale": 6 }, "credit": { "currency": "USD", "microdollars": "10000000", "scale": 6 }, "triggerBelow": { "currency": "USD", "microdollars": "2000000", "scale": 6 } }, "before": null, "currentPeriod": { "end": "2026-10-01T00:00:00.000Z", "pending": { "currency": "USD", "microdollars": "0", "scale": 6 }, "remaining": null, "settled": { "currency": "USD", "microdollars": "0", "scale": 6 }, "start": "2026-09-01T00:00:00.000Z" }, "expectedRevision": 3, "expandsAuthority": true, "expiresAt": "2026-09-10T12:05:00.000Z", "preview": "automatic-top-up-preview-example", "subscribedProjectFees": { "currency": "USD", "microdollars": "5000000", "scale": 6 } }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "enum": ["enable", "edit", "disable", "resume"] }, "after": { "anyOf": [ { "type": "object", "properties": { "ceiling": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "credit": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "triggerBelow": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] } }, "required": ["ceiling", "credit", "triggerBelow"] }, { "type": "null" } ] }, "before": { "anyOf": [ { "type": "object", "properties": { "ceiling": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "credit": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "triggerBelow": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] } }, "required": ["ceiling", "credit", "triggerBelow"] }, { "type": "null" } ] }, "currentPeriod": { "type": "object", "properties": { "end": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "pending": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "remaining": { "anyOf": [ { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, { "type": "null" } ] }, "settled": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "start": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, "required": [ "end", "pending", "remaining", "settled", "start" ] }, "expectedRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "expandsAuthority": { "type": "boolean" }, "expiresAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "preview": { "type": "string", "minLength": 1, "maxLength": 128 }, "subscribedProjectFees": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] } }, "required": [ "action", "after", "before", "currentPeriod", "expectedRevision", "expandsAuthority", "expiresAt", "preview", "subscribedProjectFees" ] } } }, "description": "Preview an automatic top-up rule" }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "scope_missing", "test_to_live_escalation" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing, test_to_live_escalation." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "project_archived", "revision_conflict", "state_conflict" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: project_archived, revision_conflict, state_conflict." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Preview an automatic top-up rule", "security": [ { "apiCredential": ["billing:write"] }, { "memberSession": ["billing:write"], "memberSessionEnvironment": [], "memberSessionProject": [] } ], "requestBody": { "content": { "application/json": { "example": { "action": "enable", "ceiling": { "currency": "USD", "microdollars": "50000000", "scale": 6 }, "credit": { "currency": "USD", "microdollars": "10000000", "scale": 6 }, "expectedRevision": 3, "triggerBelow": { "currency": "USD", "microdollars": "2000000", "scale": 6 } }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "enum": ["enable", "edit", "disable", "resume"] }, "ceiling": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "credit": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "expectedRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "triggerBelow": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] } }, "required": ["action", "expectedRevision"], "additionalProperties": false } } }, "required": true } } }, "/v1/billing/funding/auto-top-up": { "patch": { "description": "Applies the exact unexpired automatic top-up preview a billing owner confirmed. Enable or expanded limits require this explicit approval; edit and disable fence queued unsubmitted work, while submitted or uncertain payments retain their original identity and UTC authorization month. Resume may clear only an authenticated payment-method failure and never an unresolved provider outcome. Applying a rule creates no charge; later low-balance work remains bounded by the approved fixed amount, one outstanding operation, cooldown, usage cap and gross monthly ceiling.", "operationId": "billing.autotopup", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "minLength": 16, "maxLength": 255, "pattern": "^[\\x20-\\x7e]+$" } } ], "responses": { "200": { "content": { "application/json": { "example": { "automaticExecutionTopUp": { "ceiling": { "currency": "USD", "microdollars": "50000000", "scale": 6 }, "currentPeriod": { "end": "2026-10-01T00:00:00.000Z", "pending": { "currency": "USD", "microdollars": "10830000", "scale": 6 }, "remaining": { "currency": "USD", "microdollars": "29170000", "scale": 6 }, "settled": { "currency": "USD", "microdollars": "10000000", "scale": 6 }, "start": "2026-09-01T00:00:00.000Z" }, "rule": { "cooldownUntil": null, "desired": { "ceiling": { "currency": "USD", "microdollars": "50000000", "scale": 6 }, "credit": { "currency": "USD", "microdollars": "10000000", "scale": 6 }, "triggerBelow": { "currency": "USD", "microdollars": "2000000", "scale": 6 } }, "effective": { "ceiling": { "currency": "USD", "microdollars": "50000000", "scale": 6 }, "credit": { "currency": "USD", "microdollars": "10000000", "scale": 6 }, "triggerBelow": { "currency": "USD", "microdollars": "2000000", "scale": 6 } }, "state": "ready", "suspension": null }, "revision": 3 }, "credit": { "amountOwed": { "currency": "USD", "microdollars": "0", "scale": 6 }, "available": { "currency": "USD", "microdollars": "9000000", "scale": 6 }, "reserved": { "currency": "USD", "microdollars": "10", "scale": 6 } }, "freshness": { "kind": "authoritative" }, "paymentOperations": [ { "createdAt": "2026-09-10T12:00:00.000Z", "credit": { "currency": "USD", "microdollars": "10000000", "scale": 6 }, "gross": { "currency": "USD", "microdollars": "10830000", "scale": 6 }, "id": "funding-operation-example", "kind": "automatic", "paymentUrl": "https://pay.stripe.com/receipts/acct_example/example", "reason": "payment-required", "state": "pending", "tax": { "currency": "USD", "microdollars": "830000", "scale": 6 }, "taxStatus": "confirmed", "updatedAt": "2026-09-10T12:00:01.000Z" } ], "subscribedProjectFees": { "currency": "USD", "microdollars": "5000000", "scale": 6 } }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "automaticExecutionTopUp": { "type": "object", "properties": { "ceiling": { "anyOf": [ { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, { "type": "null" } ] }, "currentPeriod": { "type": "object", "properties": { "end": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "pending": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "remaining": { "anyOf": [ { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] }, { "type": "null" } ] }, "settled": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "start": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, "required": [ "end", "pending", "remaining", "settled", "start" ] }, "rule": { "type": "object", "properties": { "cooldownUntil": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, { "type": "null" } ] }, "desired": { "anyOf": [ { "type": "object", "properties": { "ceiling": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] }, "credit": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] }, "triggerBelow": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] } }, "required": [ "ceiling", "credit", "triggerBelow" ] }, { "type": "null" } ] }, "effective": { "anyOf": [ { "type": "object", "properties": { "ceiling": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] }, "credit": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] }, "triggerBelow": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] } }, "required": [ "ceiling", "credit", "triggerBelow" ] }, { "type": "null" } ] }, "setupUrl": { "type": "string", "maxLength": 4096, "format": "uri" }, "state": { "type": "string", "enum": [ "disabled", "payment-method-required", "ready" ] }, "suspension": { "anyOf": [ { "type": "object", "properties": { "at": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "reason": { "type": "string", "enum": [ "authentication-required", "payment-failed" ] } }, "required": ["at", "reason"] }, { "type": "null" } ] } }, "required": [ "cooldownUntil", "desired", "effective", "state", "suspension" ] }, "revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "ceiling", "currentPeriod", "rule", "revision" ] }, "credit": { "type": "object", "properties": { "amountOwed": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "available": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "reserved": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] } }, "required": ["amountOwed", "available", "reserved"] }, "freshness": { "type": "object", "properties": { "kind": { "type": "string", "const": "authoritative" } }, "required": ["kind"] }, "paymentOperations": { "maxItems": 25, "type": "array", "items": { "type": "object", "properties": { "createdAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "credit": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "gross": { "anyOf": [ { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] }, { "type": "null" } ] }, "id": { "type": "string", "minLength": 1, "maxLength": 255 }, "kind": { "type": "string", "enum": ["manual", "automatic"] }, "paymentUrl": { "type": "string", "maxLength": 4096, "format": "uri" }, "reason": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,127}$" }, "receiptUrl": { "type": "string", "maxLength": 4096, "format": "uri" }, "state": { "type": "string", "enum": [ "pending", "paid", "failed", "authentication-required", "action-required", "canceled", "refunded", "reversed", "disputed" ] }, "tax": { "anyOf": [ { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] }, { "type": "null" } ] }, "taxStatus": { "type": "string", "enum": ["calculated-at-checkout", "confirmed"] }, "updatedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, "required": [ "createdAt", "credit", "gross", "id", "kind", "state", "tax", "taxStatus", "updatedAt" ] } }, "subscribedProjectFees": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] } }, "required": [ "automaticExecutionTopUp", "credit", "freshness", "paymentOperations", "subscribedProjectFees" ] } } }, "description": "Apply an automatic top-up rule", "headers": { "Idempotency-Replayed": { "required": false, "schema": { "type": "string", "const": "true" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "scope_missing", "test_to_live_escalation" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing, test_to_live_escalation." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "idempotency_key_reused", "project_archived", "revision_conflict", "state_conflict" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: idempotency_key_reused, project_archived, revision_conflict, state_conflict." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Apply an automatic top-up rule", "security": [ { "apiCredential": ["billing:write"] }, { "memberSession": ["billing:write"], "memberSessionEnvironment": [], "memberSessionProject": [] } ], "requestBody": { "content": { "application/json": { "example": { "confirmed": true, "expectedRevision": 3, "preview": "automatic-top-up-preview-example" }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "confirmed": { "type": "boolean", "const": true }, "expectedRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "preview": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": ["confirmed", "expectedRevision", "preview"], "additionalProperties": false } } }, "required": true } } }, "/v1/billing/funding/refunds": { "post": { "description": "Records an explicitly approved billing-owner request for operator review of unused purchased execution credit. It never submits a refund, cashes out credit or grants an MCP cash-out path; the Idempotency-Key preserves one request across retries. Trial credit has no cash value, provider submission remains an operator action, and any later refund does not restore automatic purchasing authority for the month.", "operationId": "billing.refundrequest", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "minLength": 16, "maxLength": 255, "pattern": "^[\\x20-\\x7e]+$" } } ], "responses": { "201": { "content": { "application/json": { "example": { "amount": { "currency": "USD", "microdollars": "5000000", "scale": 6 }, "id": "refund-request-example", "paymentOperation": "funding-operation-example", "requestedAt": "2026-09-10T12:10:00.000Z", "state": "operator-review-pending" }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "amount": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "id": { "type": "string", "minLength": 1, "maxLength": 255 }, "paymentOperation": { "type": "string", "minLength": 1, "maxLength": 255 }, "requestedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "state": { "type": "string", "const": "operator-review-pending" } }, "required": [ "amount", "id", "paymentOperation", "requestedAt", "state" ] } } }, "description": "Request operator-reviewed refund", "headers": { "Idempotency-Replayed": { "required": false, "schema": { "type": "string", "const": "true" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "scope_missing", "test_to_live_escalation" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing, test_to_live_escalation." }, "404": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["not_found"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: not_found." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "idempotency_key_reused", "project_archived", "state_conflict" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: idempotency_key_reused, project_archived, state_conflict." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Request operator-reviewed refund", "security": [ { "apiCredential": ["billing:write"] }, { "memberSession": ["billing:write"], "memberSessionEnvironment": [], "memberSessionProject": [] } ], "requestBody": { "content": { "application/json": { "example": { "amount": { "currency": "USD", "microdollars": "5000000", "scale": 6 }, "confirmed": true, "paymentOperation": "funding-operation-example", "reason": "Duplicate manual purchase" }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "amount": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "confirmed": { "type": "boolean", "const": true }, "paymentOperation": { "type": "string", "minLength": 1, "maxLength": 255 }, "reason": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "amount", "confirmed", "paymentOperation", "reason" ], "additionalProperties": false } } }, "required": true } } }, "/v1/billing/funding/refunds/{refundRequest}": { "patch": { "description": "Records an already-made external operator decision on a pending unused-credit refund request. Completion verifies an existing Stripe refund by authenticated provider read before applying the exact credit, tax and gross adjustment; it never creates a provider refund. Decline releases the reserved credit without contacting the provider. The Idempotency-Key makes either decision converge across retries.", "operationId": "billing.refundresolution", "parameters": [ { "in": "path", "name": "refundRequest", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "minLength": 16, "maxLength": 255, "pattern": "^[\\x20-\\x7e]+$" } } ], "responses": { "200": { "content": { "application/json": { "example": { "automaticExecutionTopUp": { "ceiling": { "currency": "USD", "microdollars": "50000000", "scale": 6 }, "currentPeriod": { "end": "2026-10-01T00:00:00.000Z", "pending": { "currency": "USD", "microdollars": "10830000", "scale": 6 }, "remaining": { "currency": "USD", "microdollars": "29170000", "scale": 6 }, "settled": { "currency": "USD", "microdollars": "10000000", "scale": 6 }, "start": "2026-09-01T00:00:00.000Z" }, "rule": { "cooldownUntil": null, "desired": { "ceiling": { "currency": "USD", "microdollars": "50000000", "scale": 6 }, "credit": { "currency": "USD", "microdollars": "10000000", "scale": 6 }, "triggerBelow": { "currency": "USD", "microdollars": "2000000", "scale": 6 } }, "effective": { "ceiling": { "currency": "USD", "microdollars": "50000000", "scale": 6 }, "credit": { "currency": "USD", "microdollars": "10000000", "scale": 6 }, "triggerBelow": { "currency": "USD", "microdollars": "2000000", "scale": 6 } }, "state": "ready", "suspension": null }, "revision": 3 }, "credit": { "amountOwed": { "currency": "USD", "microdollars": "0", "scale": 6 }, "available": { "currency": "USD", "microdollars": "9000000", "scale": 6 }, "reserved": { "currency": "USD", "microdollars": "10", "scale": 6 } }, "freshness": { "kind": "authoritative" }, "paymentOperations": [ { "createdAt": "2026-09-10T12:00:00.000Z", "credit": { "currency": "USD", "microdollars": "10000000", "scale": 6 }, "gross": { "currency": "USD", "microdollars": "10830000", "scale": 6 }, "id": "funding-operation-example", "kind": "automatic", "paymentUrl": "https://pay.stripe.com/receipts/acct_example/example", "reason": "payment-required", "state": "pending", "tax": { "currency": "USD", "microdollars": "830000", "scale": 6 }, "taxStatus": "confirmed", "updatedAt": "2026-09-10T12:00:01.000Z" } ], "subscribedProjectFees": { "currency": "USD", "microdollars": "5000000", "scale": 6 } }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "automaticExecutionTopUp": { "type": "object", "properties": { "ceiling": { "anyOf": [ { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, { "type": "null" } ] }, "currentPeriod": { "type": "object", "properties": { "end": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "pending": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "remaining": { "anyOf": [ { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] }, { "type": "null" } ] }, "settled": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "start": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, "required": [ "end", "pending", "remaining", "settled", "start" ] }, "rule": { "type": "object", "properties": { "cooldownUntil": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, { "type": "null" } ] }, "desired": { "anyOf": [ { "type": "object", "properties": { "ceiling": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] }, "credit": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] }, "triggerBelow": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] } }, "required": [ "ceiling", "credit", "triggerBelow" ] }, { "type": "null" } ] }, "effective": { "anyOf": [ { "type": "object", "properties": { "ceiling": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] }, "credit": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] }, "triggerBelow": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] } }, "required": [ "ceiling", "credit", "triggerBelow" ] }, { "type": "null" } ] }, "setupUrl": { "type": "string", "maxLength": 4096, "format": "uri" }, "state": { "type": "string", "enum": [ "disabled", "payment-method-required", "ready" ] }, "suspension": { "anyOf": [ { "type": "object", "properties": { "at": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "reason": { "type": "string", "enum": [ "authentication-required", "payment-failed" ] } }, "required": ["at", "reason"] }, { "type": "null" } ] } }, "required": [ "cooldownUntil", "desired", "effective", "state", "suspension" ] }, "revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "ceiling", "currentPeriod", "rule", "revision" ] }, "credit": { "type": "object", "properties": { "amountOwed": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "available": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "reserved": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] } }, "required": ["amountOwed", "available", "reserved"] }, "freshness": { "type": "object", "properties": { "kind": { "type": "string", "const": "authoritative" } }, "required": ["kind"] }, "paymentOperations": { "maxItems": 25, "type": "array", "items": { "type": "object", "properties": { "createdAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "credit": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "gross": { "anyOf": [ { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] }, { "type": "null" } ] }, "id": { "type": "string", "minLength": 1, "maxLength": 255 }, "kind": { "type": "string", "enum": ["manual", "automatic"] }, "paymentUrl": { "type": "string", "maxLength": 4096, "format": "uri" }, "reason": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,127}$" }, "receiptUrl": { "type": "string", "maxLength": 4096, "format": "uri" }, "state": { "type": "string", "enum": [ "pending", "paid", "failed", "authentication-required", "action-required", "canceled", "refunded", "reversed", "disputed" ] }, "tax": { "anyOf": [ { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] }, { "type": "null" } ] }, "taxStatus": { "type": "string", "enum": ["calculated-at-checkout", "confirmed"] }, "updatedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, "required": [ "createdAt", "credit", "gross", "id", "kind", "state", "tax", "taxStatus", "updatedAt" ] } }, "subscribedProjectFees": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] } }, "required": [ "automaticExecutionTopUp", "credit", "freshness", "paymentOperations", "subscribedProjectFees" ] } } }, "description": "Record a reviewed refund decision", "headers": { "Idempotency-Replayed": { "required": false, "schema": { "type": "string", "const": "true" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "scope_missing", "test_to_live_escalation" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing, test_to_live_escalation." }, "404": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["not_found"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: not_found." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "idempotency_key_reused", "project_archived", "state_conflict" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: idempotency_key_reused, project_archived, state_conflict." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Record a reviewed refund decision", "security": [ { "apiCredential": ["billing:write"] }, { "memberSession": ["billing:write"], "memberSessionEnvironment": [], "memberSessionProject": [] } ], "requestBody": { "content": { "application/json": { "example": { "confirmed": true, "decision": "declined" }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "confirmed": { "type": "boolean", "const": true }, "decision": { "type": "string", "enum": ["completed", "declined"] }, "gross": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "providerRefund": { "type": "string", "maxLength": 255, "pattern": "^re_[A-Za-z0-9_]+$" }, "tax": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] } }, "required": ["confirmed", "decision"], "additionalProperties": false } } }, "required": true } } }, "/v1/billing/projects": { "get": { "description": "Reads named included and subscribed project access, paid-through and grace deadlines, separate monthly fees, pending provider actions and desired/effective revisions.", "operationId": "billing.projects", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "desiredRevision": 2, "effectiveRevision": 2, "pending": false, "recurringProjectFees": { "currency": "USD", "microdollars": "0", "scale": 6 }, "projects": [], "pendingOperations": [] }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "includedProject": { "type": "string", "pattern": "^proj_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "desiredRevision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "effectiveRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "pending": { "type": "boolean" }, "recurringProjectFees": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "projects": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "project": { "type": "string", "pattern": "^proj_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "access": { "type": "string", "enum": ["included", "paid", "blocked"] }, "paidThroughAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "renewalGraceUntil": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "cancellationAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "deleted": { "type": "boolean" } }, "required": ["name", "project", "access", "deleted"] } }, "pendingOperations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 255 }, "kind": { "type": "string", "enum": ["add", "cancel"] }, "project": { "type": "string", "pattern": "^proj_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "state": { "type": "string", "enum": ["pending", "action-required"] }, "paymentUrl": { "type": "string", "format": "uri" }, "reason": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": ["id", "kind", "project", "state"] } } }, "required": [ "desiredRevision", "effectiveRevision", "pending", "recurringProjectFees", "projects", "pendingOperations" ] } } }, "description": "Read named project billing access" }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "scope_missing", "test_to_live_escalation" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing, test_to_live_escalation." }, "404": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["not_found"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: not_found." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "project_archived", "revision_conflict", "state_conflict" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: project_archived, revision_conflict, state_conflict." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Read named project billing access", "security": [ { "apiCredential": ["usage:read"] }, { "memberSession": ["usage:read"], "memberSessionEnvironment": [], "memberSessionProject": [] } ] } }, "/v1/billing/projects/quote": { "post": { "description": "Previews one named project addition, paid-through cancellation or included-slot transfer without authorizing a charge. Quotes expire after five minutes and bind the current commercial revision. Amounts describe project fees; Stripe Checkout shows any applicable tax before confirmation.", "operationId": "billing.quote", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "action": "add", "project": "proj_00000000000000000000000000", "quote": "quote-example", "expectedRevision": 2, "expiresAt": "2026-09-10T12:05:00.000Z", "charge": { "currency": "USD", "microdollars": "5000000", "scale": 6 }, "monthlyProjectFees": { "currency": "USD", "microdollars": "5000000", "scale": 6 }, "effectiveAt": "2026-09-10T12:00:00.000Z", "formerIncludedWillBlock": false }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "enum": ["add", "cancel", "transfer-included"] }, "project": { "type": "string", "pattern": "^proj_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "fromProject": { "type": "string", "pattern": "^proj_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "quote": { "type": "string", "minLength": 1, "maxLength": 128 }, "expectedRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "expiresAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "charge": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "monthlyProjectFees": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "effectiveAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "formerIncludedWillBlock": { "type": "boolean" } }, "required": [ "action", "project", "quote", "expectedRevision", "expiresAt", "charge", "monthlyProjectFees", "effectiveAt", "formerIncludedWillBlock" ] } } }, "description": "Preview a named project billing change" }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "scope_missing", "test_to_live_escalation" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing, test_to_live_escalation." }, "404": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["not_found"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: not_found." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "project_archived", "revision_conflict", "state_conflict" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: project_archived, revision_conflict, state_conflict." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Preview a named project billing change", "security": [ { "apiCredential": ["billing:write"] }, { "memberSession": ["billing:write"], "memberSessionEnvironment": [], "memberSessionProject": [] } ], "requestBody": { "content": { "application/json": { "example": { "action": "add", "project": "proj_00000000000000000000000000" }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "enum": ["add", "cancel", "transfer-included"] }, "project": { "type": "string", "pattern": "^proj_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "fromProject": { "type": "string", "pattern": "^proj_[0-9abcdefghjkmnpqrstvwxyz]{26}$" } }, "required": ["action", "project"], "additionalProperties": false } } }, "required": true } } }, "/v1/billing/projects/change": { "post": { "description": "Confirms the exact named-project quote and recurring commitment. Additional access activates only after authenticated successful provider payment; cancellation preserves paid-through access without a refund or renewal grace. Included transfer never subscribes the formerly included project. Retries retain the same operation and payment identity.", "operationId": "billing.change", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "minLength": 16, "maxLength": 255, "pattern": "^[\\x20-\\x7e]+$" } } ], "responses": { "200": { "content": { "application/json": { "example": { "desiredRevision": 2, "effectiveRevision": 2, "pending": false, "recurringProjectFees": { "currency": "USD", "microdollars": "0", "scale": 6 }, "projects": [], "pendingOperations": [] }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "includedProject": { "type": "string", "pattern": "^proj_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "desiredRevision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "effectiveRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "pending": { "type": "boolean" }, "recurringProjectFees": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "projects": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "project": { "type": "string", "pattern": "^proj_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "access": { "type": "string", "enum": ["included", "paid", "blocked"] }, "paidThroughAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "renewalGraceUntil": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "cancellationAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "deleted": { "type": "boolean" } }, "required": ["name", "project", "access", "deleted"] } }, "pendingOperations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 255 }, "kind": { "type": "string", "enum": ["add", "cancel"] }, "project": { "type": "string", "pattern": "^proj_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "state": { "type": "string", "enum": ["pending", "action-required"] }, "paymentUrl": { "type": "string", "format": "uri" }, "reason": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": ["id", "kind", "project", "state"] } } }, "required": [ "desiredRevision", "effectiveRevision", "pending", "recurringProjectFees", "projects", "pendingOperations" ] } } }, "description": "Confirm a quoted project billing change" }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "scope_missing", "test_to_live_escalation" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing, test_to_live_escalation." }, "404": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["not_found"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: not_found." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "idempotency_key_reused", "project_archived", "revision_conflict", "state_conflict" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: idempotency_key_reused, project_archived, revision_conflict, state_conflict." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Confirm a quoted project billing change", "security": [ { "apiCredential": ["billing:write"] }, { "memberSession": ["billing:write"], "memberSessionEnvironment": [], "memberSessionProject": [] } ], "requestBody": { "content": { "application/json": { "example": { "quote": "quote-example", "expectedRevision": 2, "confirmed": true }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "quote": { "type": "string", "minLength": 1, "maxLength": 128 }, "expectedRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "confirmed": { "type": "boolean", "const": true } }, "required": ["quote", "expectedRevision", "confirmed"], "additionalProperties": false } } }, "required": true } } }, "/v1/billing/portal": { "post": { "description": "Creates a short-lived Stripe-hosted payment-method and invoice recovery session for the verified organization. It does not grant execution credit or additional project access.", "operationId": "billing.portal", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "url": "https://billing.stripe.com/p/session/example" }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "format": "uri" } }, "required": ["url"] } } }, "description": "Open hosted payment recovery" }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "scope_missing", "test_to_live_escalation" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing, test_to_live_escalation." }, "404": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["not_found"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: not_found." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "project_archived", "revision_conflict", "state_conflict" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: project_archived, revision_conflict, state_conflict." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Open hosted payment recovery", "security": [ { "apiCredential": ["billing:write"] }, { "memberSession": ["billing:write"], "memberSessionEnvironment": [], "memberSessionProject": [] } ] } }, "/v1/billing/reconcile": { "post": { "description": "Advances at most one due, already-authorized desired billing-policy revision for the caller's organization into PostgreSQL, then returns the same exact desired/effective summary as billing.summary. The command never changes the desired document. A transport failure is recorded for bounded retry and remains pending. Repeating the command may advance the next queued revision, so each call requires approval.", "operationId": "billing.reconcile", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "activation": { "boundary": "2026-09-01T00:00:00.000Z", "mode": "shadow" }, "blockingReasons": [], "budgetPolicy": { "desired": { "advisoryBudget": null, "hardCap": null }, "desiredRevision": 0, "effectiveRevision": 0, "pending": false }, "credit": { "available": { "currency": "USD", "microdollars": "999980", "scale": 6 }, "consumed": { "currency": "USD", "microdollars": "10", "scale": 6 }, "reserved": { "currency": "USD", "microdollars": "10", "scale": 6 } }, "desiredRevision": 2, "effectiveRevision": 1, "freshness": { "kind": "authoritative" }, "includedProject": "proj_01h8xyz9k2m4n6p8r0t2v4w6y8", "period": { "automaticExecutionTopUp": { "pending": { "currency": "USD", "microdollars": "0", "scale": 6 }, "settled": { "currency": "USD", "microdollars": "0", "scale": 6 } }, "subscribedProjectFees": { "currency": "USD", "microdollars": "0", "scale": 6 }, "reservedUsage": { "currency": "USD", "microdollars": "10", "scale": 6 }, "settledUsage": { "currency": "USD", "microdollars": "10", "scale": 6 }, "start": "2026-09-01T00:00:00.000Z", "end": "2026-10-01T00:00:00.000Z" }, "pending": true, "priceVersion": "payg-v1", "trialExpiresAt": "2026-09-15T00:00:00.000Z" }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "activation": { "type": "object", "properties": { "boundary": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "mode": { "type": "string", "enum": ["disabled", "shadow", "enforced"] } }, "required": ["boundary", "mode"] }, "blockingReasons": { "type": "array", "items": { "type": "string", "enum": [ "billing-state-missing", "billing-account-closed", "project-ineligible", "insufficient-credit", "execution-cap-reached" ] } }, "budgetPolicy": { "type": "object", "properties": { "desired": { "type": "object", "properties": { "advisoryBudget": { "anyOf": [ { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] }, { "type": "null" } ] }, "hardCap": { "anyOf": [ { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] }, { "type": "null" } ] } }, "required": ["advisoryBudget", "hardCap"] }, "desiredRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "effectiveRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "pending": { "type": "boolean" } }, "required": [ "desired", "desiredRevision", "effectiveRevision", "pending" ] }, "closedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "credit": { "type": "object", "properties": { "available": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^-?(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "consumed": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "reserved": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] } }, "required": ["available", "consumed", "reserved"] }, "desiredRevision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "effectiveRevision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "freshness": { "type": "object", "properties": { "kind": { "type": "string", "const": "authoritative" } }, "required": ["kind"] }, "includedProject": { "type": "string", "pattern": "^proj_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "period": { "type": "object", "properties": { "advisoryBudget": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "hardCap": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "remainingToHardCap": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "advisoryBudgetProgress": { "type": "object", "properties": { "committed": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "remaining": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] } }, "required": ["committed", "remaining"] }, "automaticExecutionTopUp": { "type": "object", "properties": { "cap": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "pending": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "remainingToCap": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "settled": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] } }, "required": ["pending", "settled"] }, "subscribedProjectFees": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "reservedUsage": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "settledUsage": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "start": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "end": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, "required": [ "automaticExecutionTopUp", "subscribedProjectFees", "reservedUsage", "settledUsage", "start", "end" ] }, "pending": { "type": "boolean" }, "priceVersion": { "type": "string", "minLength": 1, "maxLength": 64 }, "trialExpiresAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, "required": [ "activation", "blockingReasons", "budgetPolicy", "credit", "desiredRevision", "effectiveRevision", "freshness", "pending", "priceVersion" ] } } }, "description": "Advance one pending billing policy" }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "scope_missing", "test_to_live_escalation" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing, test_to_live_escalation." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["project_archived"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: project_archived." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Advance one pending billing policy", "security": [ { "apiCredential": ["billing:write"] }, { "memberSession": ["billing:write"], "memberSessionEnvironment": [], "memberSessionProject": [] } ] } }, "/v1/billing/budgets": { "patch": { "description": "Replaces the caller organization's advisory execution budget and optional hard execution-spend cap for the current UTC month. Values are exact whole cents encoded as integer microdollars. The expected budget-policy revision prevents a stale editor overwriting a newer choice, and Idempotency-Key makes retrying one intent safe. Null turns that setting off. This command records desired state durably; billing.reconcile advances it to PostgreSQL, and reads remain pending until PostgreSQL confirms it. It never changes automatic top-up authority, purchases credit, or counts subscription payments as execution usage.", "operationId": "billing.budgets", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "minLength": 16, "maxLength": 255, "pattern": "^[\\x20-\\x7e]+$" } } ], "responses": { "200": { "content": { "application/json": { "example": { "budgetPolicy": { "desired": { "advisoryBudget": { "currency": "USD", "microdollars": "25000000", "scale": 6 }, "hardCap": { "currency": "USD", "microdollars": "50000000", "scale": 6 } }, "desiredRevision": 2, "effectiveRevision": 1, "pending": true }, "freshness": { "kind": "authoritative" } }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "budgetPolicy": { "type": "object", "properties": { "desired": { "type": "object", "properties": { "advisoryBudget": { "anyOf": [ { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] }, { "type": "null" } ] }, "hardCap": { "anyOf": [ { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": [ "currency", "microdollars", "scale" ] }, { "type": "null" } ] } }, "required": ["advisoryBudget", "hardCap"] }, "desiredRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "effectiveRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "pending": { "type": "boolean" } }, "required": [ "desired", "desiredRevision", "effectiveRevision", "pending" ] }, "freshness": { "type": "object", "properties": { "kind": { "type": "string", "const": "authoritative" } }, "required": ["kind"] } }, "required": ["budgetPolicy", "freshness"] } } }, "description": "Set execution budgets", "headers": { "Idempotency-Replayed": { "required": false, "schema": { "type": "string", "const": "true" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "scope_missing", "test_to_live_escalation" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing, test_to_live_escalation." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "idempotency_key_reused", "project_archived", "revision_conflict" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: idempotency_key_reused, project_archived, revision_conflict." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Set execution budgets", "security": [ { "apiCredential": ["billing:write"] }, { "memberSession": ["billing:write"], "memberSessionEnvironment": [], "memberSessionProject": [] } ], "requestBody": { "content": { "application/json": { "example": { "advisoryBudget": { "currency": "USD", "microdollars": "25000000", "scale": 6 }, "expectedRevision": 1, "hardCap": { "currency": "USD", "microdollars": "50000000", "scale": 6 } }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "advisoryBudget": { "anyOf": [ { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, { "type": "null" } ] }, "expectedRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hardCap": { "anyOf": [ { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^(?:0|(?:[1-9]\\d{0,13}|[1-8]\\d{14}|9[01]\\d{13}|92[01]\\d{12}|922[0-2]\\d{11}|9223[0-2]\\d{10}|92233[0-6]\\d{9}|922337[01]\\d{8}|92233720[0-2]\\d{6}|922337203[0-5]\\d{5}|9223372036[0-7]\\d{4}|92233720368[0-4]\\d{3}|922337203685[0-3]\\d{2}|9223372036854[0-6]\\d|92233720368547[0-7])0000)$", "description": "A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.", "maxLength": 19 }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, { "type": "null" } ] } }, "required": ["advisoryBudget", "expectedRevision", "hardCap"] } } }, "required": true } } }, "/v1/billing/ledger": { "get": { "description": "Lists the verified principal's organization ledger in immutable sequence order. Each entry is one exact signed microdollar fact with safe attempt, lot, payment-operation and event references. Raw callback data, card data, internal causal keys and ledger detail have no field in the response. The opaque cursor is bound to the principal's organization, project and environment and cannot widen authority.", "operationId": "billing.ledger", "parameters": [ { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "amount": { "currency": "USD", "microdollars": "-10", "scale": 6 }, "kind": "attempt_debited", "period": "2026-09-01T00:00:00.000Z", "recordedAt": "2026-09-09T14:00:00.000Z", "reference": { "attempt": "att_01h8xyz9k2m4n6p8r0t2v4w6y8", "event": "billing-attempt-debited-1" }, "sequence": "42" } ], "freshness": { "kind": "authoritative" }, "nextCursor": "eyJhIjowLCJpIjoiNDIiLCJrIjoiOTUxMzU0NmYifQ" }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "microdollars": { "type": "string", "pattern": "^-?(?:0|[1-9]\\d*)$" }, "scale": { "type": "number", "const": 6 } }, "required": ["currency", "microdollars", "scale"] }, "kind": { "type": "string", "enum": [ "credit_granted", "credit_reversed", "attempt_debited", "attempt_released", "shadow_attempt_debited", "shadow_attempt_released", "late_evidence_waived", "policy_installed", "budget_policy_updated", "budget_threshold_reached", "budget_exhausted", "budget_recovered", "automatic_charge_ceiling_updated", "payment_reserved", "payment_submitted", "payment_pending", "payment_paid", "payment_failed", "payment_canceled", "payment_authentication_required", "payment_action_required", "payment_refunded", "payment_disputed", "payment_reversed", "payment_dispute_restored", "refund_requested", "payment_refund_canceled", "automatic_top_up_cap_reached", "automatic_charge_threshold_reached", "automatic_charge_threshold_recovered", "low_credit_reached", "low_credit_recovered", "notification_settings_updated", "service_blocked", "service_restored" ] }, "period": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "recordedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "reference": { "type": "object", "properties": { "attempt": { "type": "string", "pattern": "^att_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "creditLot": { "type": "string", "minLength": 1, "maxLength": 128 }, "event": { "type": "string", "minLength": 1, "maxLength": 255 }, "paymentOperation": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": ["event"] }, "sequence": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)$" } }, "required": [ "amount", "kind", "recordedAt", "reference", "sequence" ] } }, "freshness": { "type": "object", "properties": { "kind": { "type": "string", "const": "authoritative" } }, "required": ["kind"] }, "nextCursor": { "type": "string", "minLength": 1 } }, "required": ["data", "freshness"] } } }, "description": "List immutable billing entries" }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["project_archived"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: project_archived." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "List immutable billing entries", "security": [ { "apiCredential": ["usage:read"] }, { "memberSession": ["usage:read"], "memberSessionEnvironment": [], "memberSessionProject": [] } ] } }, "/v1/usage": { "get": { "description": "Legacy terminal-occurrence volume by UTC day from the authoritative scheduling model. This is an operational outcome aggregate retained for compatibility; it is not the PAYG invoice meter. Billing is per logical delivery attempt, including retries and redeliveries, and is exposed exactly by billing.summary and billing.ledger. Days with no terminal occurrence are absent rather than zero, and the window states which days the answer covers. `from` and `to` are snapped outward to UTC midnight, so an answer always covers whole days.", "operationId": "usage.read", "parameters": [ { "in": "query", "name": "bucketSeconds", "required": false, "schema": { "default": 86400, "type": "integer", "minimum": 3600, "maximum": 86400, "multipleOf": 3600 } }, { "in": "query", "name": "from", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, { "in": "query", "name": "to", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } } ], "responses": { "200": { "content": { "application/json": { "example": { "bucketSeconds": 86400, "days": [ { "billableOccurrences": 42, "byTerminalState": { "succeeded": 40, "terminal_failed": 2 }, "start": "2026-07-28T00:00:00.000Z" } ], "freshness": { "kind": "authoritative" }, "totalBillableOccurrences": 42, "window": { "from": "2026-07-28T00:00:00.000Z", "to": "2026-07-29T00:00:00.000Z" } }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "bucketSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "days": { "type": "array", "items": { "type": "object", "properties": { "billableOccurrences": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "byTerminalState": { "type": "object", "propertyNames": { "type": "string", "enum": [ "cancelled", "skipped_stale", "succeeded", "terminal_failed" ] }, "additionalProperties": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "start": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, "required": [ "billableOccurrences", "byTerminalState", "start" ] } }, "freshness": { "type": "object", "properties": { "kind": { "type": "string", "const": "authoritative" } }, "required": ["kind"] }, "plan": { "type": "object", "properties": { "attemptsToday": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "dailyAttemptCeiling": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "resetsAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "since": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, "required": [ "attemptsToday", "dailyAttemptCeiling", "resetsAt", "since" ] }, "totalBillableOccurrences": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "window": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "to": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, "required": ["from", "to"] } }, "required": [ "bucketSeconds", "days", "freshness", "totalBillableOccurrences", "window" ] } } }, "description": "Read terminal occurrence volume by day" }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["project_archived"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: project_archived." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Read terminal occurrence volume by day", "security": [ { "apiCredential": ["usage:read"] }, { "memberSession": ["usage:read"], "memberSessionEnvironment": [], "memberSessionProject": [] } ] } }, "/v1/timing/summary": { "get": { "description": "Reads the verified principal's project timing cohort over the authoritative rolling 24-hour due-time window. Exact 5,000ms and 15,000ms counters include eligible work that has not fired; customer blocks, platform blocks, skipped work and missing evidence stay visible beside the verdict. Values equal to a target meet it, and a threshold with no matured population is unknown. Delivered-sample p95 and p99 lateness are separate observations, including negative early-delivery defects. These are internal operating objectives, not a contractual SLA or service-credit promise.", "operationId": "timing.summary", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "customerBlockedCount": 2, "deliveredSampleCount": 98, "freshness": { "kind": "authoritative" }, "missingEvidenceCount": 1, "p95LatenessMs": 4200, "p99LatenessMs": 12000, "platformBlockedCount": 1, "policyVersion": "timing-v1", "skippedCount": 3, "targets": [ { "breachCount": 5, "customerBlockedCount": 2, "eligibleOutstandingBreachCount": 1, "maturedCount": 100, "targetMs": 5000, "verdict": "met", "withinTargetCount": 95 }, { "breachCount": 1, "customerBlockedCount": 2, "eligibleOutstandingBreachCount": 1, "maturedCount": 100, "targetMs": 15000, "verdict": "met", "withinTargetCount": 99 } ], "windowEnd": "2026-09-09T12:00:00.000Z", "windowStart": "2026-09-08T12:00:00.000Z" }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "customerBlockedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "deliveredSampleCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "freshness": { "type": "object", "properties": { "kind": { "type": "string", "const": "authoritative" } }, "required": ["kind"] }, "missingEvidenceCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "p95LatenessMs": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "p99LatenessMs": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "platformBlockedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "policyVersion": { "type": "string", "minLength": 1, "maxLength": 64 }, "skippedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "targets": { "type": "array", "prefixItems": [ { "type": "object", "properties": { "breachCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "customerBlockedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "eligibleOutstandingBreachCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "maturedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "targetMs": { "anyOf": [ { "type": "number", "const": 5000 }, { "type": "number", "const": 15000 } ] }, "verdict": { "type": "string", "enum": ["met", "missed", "unknown"] }, "withinTargetCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "breachCount", "customerBlockedCount", "eligibleOutstandingBreachCount", "maturedCount", "targetMs", "verdict", "withinTargetCount" ] }, { "type": "object", "properties": { "breachCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "customerBlockedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "eligibleOutstandingBreachCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "maturedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "targetMs": { "anyOf": [ { "type": "number", "const": 5000 }, { "type": "number", "const": 15000 } ] }, "verdict": { "type": "string", "enum": ["met", "missed", "unknown"] }, "withinTargetCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "breachCount", "customerBlockedCount", "eligibleOutstandingBreachCount", "maturedCount", "targetMs", "verdict", "withinTargetCount" ] } ] }, "windowEnd": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "windowStart": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, "required": [ "customerBlockedCount", "deliveredSampleCount", "freshness", "missingEvidenceCount", "platformBlockedCount", "policyVersion", "skippedCount", "targets", "windowEnd", "windowStart" ] } } }, "description": "Read rolling delivery timing" }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["project_archived"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: project_archived." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Read rolling delivery timing", "security": [ { "apiCredential": ["usage:read"] }, { "memberSession": ["usage:read"], "memberSessionEnvironment": [], "memberSessionProject": [] } ] } }, "/v1/forecast/windows": { "get": { "description": "The same forecast in the window shape the legacy scheduler's autoscaler already parses, published under a dated version so a consumer can pin it. It exists for one migration and is expected to be withdrawn once that migration completes; `forecast.read` is the shape this product publishes. `byTenant` is the customer partition-key breakdown under its legacy name, and `count` is always the bucket total rather than the named subtotal.", "operationId": "forecast.windows", "parameters": [ { "in": "query", "name": "breakdown", "required": false, "schema": { "default": "none", "type": "string", "enum": ["none", "partitionKey"] } }, { "in": "query", "name": "bucketSeconds", "required": false, "schema": { "default": 1800, "type": "integer", "minimum": 60, "maximum": 86400, "multipleOf": 60 } }, { "in": "query", "name": "from", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, { "in": "query", "name": "to", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } } ], "responses": { "200": { "content": { "application/json": { "example": { "bucketSeconds": 600, "buckets": [ { "byTenant": { "campaign.spring": 9, "campaign.winter": 4 }, "count": 15, "nextFireCount": 4, "otherCount": 2, "start": "2026-07-28T15:00:00.000Z" } ], "freshness": { "asOf": "2026-07-28T14:58:30.000Z", "kind": "projected", "lagSeconds": 90 }, "version": "2026-08-09" }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "bucketSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "buckets": { "type": "array", "items": { "type": "object", "properties": { "byTenant": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "count": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "nextFireCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "otherCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "start": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, "required": [ "byTenant", "count", "nextFireCount", "otherCount", "start" ] } }, "freshness": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "authoritative" } }, "required": ["kind"] }, { "type": "object", "properties": { "asOf": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "kind": { "type": "string", "const": "projected" }, "lagSeconds": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["asOf", "kind", "lagSeconds"] } ] }, "version": { "type": "string", "const": "2026-08-09" } }, "required": [ "bucketSeconds", "buckets", "freshness", "version" ] } } }, "description": "Forecast in the transitional window shape" }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["project_archived"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: project_archived." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Forecast in the transitional window shape", "security": [ { "apiCredential": ["forecast:read"] }, { "memberSession": ["forecast:read"], "memberSessionEnvironment": [], "memberSessionProject": [] } ] } }, "/v1/schedules/{scheduleId}/occurrences": { "get": { "description": "Lists the retained occurrences of one schedule from its authoritative Scheduler Partition, ordered by durable creation instant and occurrence identifier so tied timestamps never duplicate or omit a row — oldest first unless `order=newest`, which walks from the most recent. A run that an edit replaced before it ran is left out; a run skipped because the previous one was still going is listed. The cursor is opaque, scoped to the verified principal's organization, project and environment, and to the order it was issued under. Each item is metadata only: callback payloads, destinations, response bodies and signing material have no field in the response.", "operationId": "occurrences.list", "parameters": [ { "in": "path", "name": "scheduleId", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 } }, { "in": "query", "name": "order", "required": false, "schema": { "default": "oldest", "type": "string", "enum": ["oldest", "newest"] } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "attemptCount": 1, "generation": 1, "id": "occ_01h8xyz9k2m4n6p8r0t2v4w6y8", "plannedFor": "2026-07-28T15:00:00.000Z", "schedule": "sch_01h8xyz9k2m4n6p8r0t2v4w6y8", "sequence": 1, "state": "retry_wait" } ], "freshness": { "kind": "authoritative" }, "nextCursor": "eyJhIjoxNzg1MjUwODAwMDAwLCJpIjoib2NjXzAxaDh4eXo5azJtNG42cDhyMHQydjR3Nnk4IiwiayI6Ijk1MTM1NDZmIn0" }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "attemptCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "firstAttemptLatenessMs": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "firstAttemptStartedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "timingEligibility": { "type": "string", "enum": [ "eligible", "customer_blocked", "platform_blocked" ] }, "timingEligibilityReason": { "type": "string", "minLength": 1, "maxLength": 128 }, "timingPolicyVersion": { "type": "string", "minLength": 1, "maxLength": 64 }, "generation": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "id": { "type": "string", "pattern": "^occ_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "plannedFor": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "schedule": { "type": "string", "pattern": "^sch_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "sequence": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "settledAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "state": { "type": "string", "enum": [ "planned", "due", "dispatching", "retry_wait", "ambiguous", "succeeded", "terminal_failed", "cancelled", "skipped_stale" ] } }, "required": [ "attemptCount", "generation", "id", "plannedFor", "schedule", "sequence", "state" ] } }, "freshness": { "type": "object", "properties": { "kind": { "type": "string", "const": "authoritative" } }, "required": ["kind"] }, "nextCursor": { "type": "string", "minLength": 1 } }, "required": ["data", "freshness"] } } }, "description": "List retained occurrences" }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "404": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["not_found"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: not_found." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["project_archived"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: project_archived." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "List retained occurrences", "security": [ { "apiCredential": ["occurrences:read"] }, { "memberSession": ["occurrences:read"], "memberSessionEnvironment": [], "memberSessionProject": [] } ] } }, "/v1/occurrences": { "get": { "description": "Lists every retained occurrence in the verified principal's project and environment, newest first by planned instant with the occurrence identifier breaking millisecond ties. Optional endpoint, schedule, half-open date-range and outcome filters may be combined; the endpoint is resolved through the schedules that belong to the same authority. The opaque cursor belongs to this operation and the exact normalized filters that issued it, so it cannot be replayed under another view. Every page publishes the authoritative earliest retained instant for the caller's effective plan. Each item is metadata only: callback payloads, destinations, response bodies and signing material have no field in the response.", "operationId": "executions.list", "parameters": [ { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "in": "query", "name": "endpoint", "required": false, "schema": { "type": "string", "pattern": "^ep_[0-9abcdefghjkmnpqrstvwxyz]{26}$" } }, { "in": "query", "name": "from", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 } }, { "in": "query", "name": "outcome", "required": false, "schema": { "type": "string", "enum": [ "planned", "due", "dispatching", "retry_wait", "ambiguous", "succeeded", "terminal_failed", "cancelled", "skipped_stale" ] } }, { "in": "query", "name": "schedule", "required": false, "schema": { "type": "string", "pattern": "^sch_[0-9abcdefghjkmnpqrstvwxyz]{26}$" } }, { "in": "query", "name": "to", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "attemptCount": 1, "generation": 1, "id": "occ_01h8xyz9k2m4n6p8r0t2v4w6y8", "plannedFor": "2026-07-28T15:00:00.000Z", "schedule": "sch_01h8xyz9k2m4n6p8r0t2v4w6y8", "sequence": 1, "settledAt": "2026-07-28T15:00:01.000Z", "state": "succeeded" } ], "freshness": { "kind": "authoritative" }, "retention": { "from": "2026-07-21T15:00:00.000Z" } }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "attemptCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "firstAttemptLatenessMs": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "firstAttemptStartedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "timingEligibility": { "type": "string", "enum": [ "eligible", "customer_blocked", "platform_blocked" ] }, "timingEligibilityReason": { "type": "string", "minLength": 1, "maxLength": 128 }, "timingPolicyVersion": { "type": "string", "minLength": 1, "maxLength": 64 }, "generation": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "id": { "type": "string", "pattern": "^occ_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "plannedFor": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "schedule": { "type": "string", "pattern": "^sch_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "sequence": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "settledAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "state": { "type": "string", "enum": [ "planned", "due", "dispatching", "retry_wait", "ambiguous", "succeeded", "terminal_failed", "cancelled", "skipped_stale" ] } }, "required": [ "attemptCount", "generation", "id", "plannedFor", "schedule", "sequence", "state" ] } }, "freshness": { "type": "object", "properties": { "kind": { "type": "string", "const": "authoritative" } }, "required": ["kind"] }, "nextCursor": { "type": "string", "minLength": 1 }, "retention": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } }, "required": ["from"] } }, "required": ["data", "freshness", "retention"] } } }, "description": "List project executions" }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["project_archived"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: project_archived." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "List project executions", "security": [ { "apiCredential": ["occurrences:read"] }, { "memberSession": ["occurrences:read"], "memberSessionEnvironment": [], "memberSessionProject": [] } ] } }, "/v1/schedules/{scheduleId}/occurrences/{occurrenceId}": { "get": { "description": "Reads one retained occurrence from the PostgreSQL authority that owns its schedule. Trusted first-outbound timing is optional for records that predate substantiation; when present, firstAttemptLatenessMs is signed and a negative value exposes an early-delivery defect rather than being clamped to zero. Timing eligibility states whether a customer restriction excluded the occurrence from the internal target cohort. An identifier outside the verified principal's organization, project or environment is indistinguishable from an absent occurrence.", "operationId": "occurrences.read", "parameters": [ { "in": "path", "name": "scheduleId", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "occurrenceId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "freshness": { "kind": "authoritative" }, "occurrence": { "attemptCount": 2, "firstAttemptLatenessMs": 0, "firstAttemptStartedAt": "2026-07-28T15:00:00.000Z", "timingEligibility": "eligible", "timingPolicyVersion": "payg-v1", "generation": 1, "id": "occ_01h8xyz9k2m4n6p8r0t2v4w6y8", "plannedFor": "2026-07-28T15:00:00.000Z", "schedule": "sch_01h8xyz9k2m4n6p8r0t2v4w6y8", "sequence": 1, "settledAt": "2026-07-28T15:02:00.000Z", "state": "terminal_failed" } }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "freshness": { "type": "object", "properties": { "kind": { "type": "string", "const": "authoritative" } }, "required": ["kind"] }, "occurrence": { "type": "object", "properties": { "attemptCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "firstAttemptLatenessMs": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "firstAttemptStartedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "timingEligibility": { "type": "string", "enum": [ "eligible", "customer_blocked", "platform_blocked" ] }, "timingEligibilityReason": { "type": "string", "minLength": 1, "maxLength": 128 }, "timingPolicyVersion": { "type": "string", "minLength": 1, "maxLength": 64 }, "generation": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "id": { "type": "string", "pattern": "^occ_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "plannedFor": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "schedule": { "type": "string", "pattern": "^sch_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "sequence": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "settledAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "state": { "type": "string", "enum": [ "planned", "due", "dispatching", "retry_wait", "ambiguous", "succeeded", "terminal_failed", "cancelled", "skipped_stale" ] } }, "required": [ "attemptCount", "generation", "id", "plannedFor", "schedule", "sequence", "state" ] } }, "required": ["freshness", "occurrence"] } } }, "description": "Read an occurrence" }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "404": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["not_found"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: not_found." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["project_archived"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: project_archived." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Read an occurrence", "security": [ { "apiCredential": ["occurrences:read"] }, { "memberSession": ["occurrences:read"], "memberSessionEnvironment": [], "memberSessionProject": [] } ] } }, "/v1/schedules/{scheduleId}/occurrences/{occurrenceId}/attempts": { "get": { "description": "Lists the immutable attempts retained under one occurrence, ordered by start instant and attempt identifier so equal timestamps have a stable position. The PostgreSQL authority answers every page. Optional first-outbound fields carry trusted occurrence timing and its pinned policy; absence means unknown, never zero. Results expose only bounded outcome, response-status, duration, timing, diagnostic, remediation and redelivery-cause metadata; callback payloads, response bodies, destinations, signing material, secrets and transport traces are structurally absent.", "operationId": "attempts.list", "parameters": [ { "in": "path", "name": "scheduleId", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "occurrenceId", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "attemptNumber": 1, "classifiedAt": "2026-07-28T15:00:00.071Z", "delivery": "dlv_01h8xyz9k2m4n6p8r0t2v4w6y8", "diagnostic": "http_retryable", "durationMs": 71, "firstAttemptLatenessMs": 0, "firstAttemptStartedAt": "2026-07-28T15:00:00.000Z", "timingEligibility": "eligible", "timingPolicyVersion": "payg-v1", "id": "att_01h8xyz9k2m4n6p8r0t2v4w6y8", "occurrence": "occ_01h8xyz9k2m4n6p8r0t2v4w6y8", "remediation": "review_retry_policy", "responseStatus": 503, "startedAt": "2026-07-28T15:00:00.000Z", "state": "retryable_failure", "trigger": { "kind": "automatic" } } ], "freshness": { "kind": "authoritative" }, "nextCursor": "eyJhIjoxNzg1MjUwODAwMDAwLCJpIjoiYXR0XzAxaDh4eXo5azJtNG42cDhyMHQydjR3Nnk4IiwiayI6Ijk1MTM1NDZmIn0" }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "attemptNumber": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "classifiedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "delivery": { "type": "string", "pattern": "^dlv_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "diagnostic": { "type": "string", "x-callback-attempt-diagnostics": [ "completion_timed_out", "delivered", "duplicate_inflight", "endpoint_unavailable", "endpoint_unsafe", "http_refused", "http_retryable", "http_terminal", "identity_conflict", "network_ambiguous", "payload_unavailable", "rate_limited" ] }, "durationMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "firstAttemptLatenessMs": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "firstAttemptStartedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "timingEligibility": { "type": "string", "enum": [ "eligible", "customer_blocked", "platform_blocked" ] }, "timingEligibilityReason": { "type": "string", "minLength": 1, "maxLength": 128 }, "timingPolicyVersion": { "type": "string", "minLength": 1, "maxLength": 64 }, "id": { "type": "string", "pattern": "^att_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "occurrence": { "type": "string", "pattern": "^occ_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "remediation": { "type": "string", "enum": [ "none", "review_retry_policy", "inspect_receiver", "review_endpoint", "replace_payload", "contact_support", "review_before_redelivery" ] }, "failureSnippet": { "type": "object", "properties": { "contentType": { "type": "string", "minLength": 1, "maxLength": 128 }, "text": { "type": "string", "maxLength": 4096 }, "truncated": { "type": "boolean" } }, "required": ["contentType", "text", "truncated"] }, "responseHeaders": { "maxItems": 8, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64 }, "value": { "type": "string", "maxLength": 256 } }, "required": ["name", "value"] } }, "responseStatus": { "type": "integer", "minimum": 100, "maximum": 599 }, "startedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "state": { "type": "string", "enum": [ "succeeded", "retryable_failure", "terminal_failure", "ambiguous" ] }, "trigger": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "automatic" } }, "required": ["kind"] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "redelivery" }, "sourceAttemptId": { "type": "string", "pattern": "^att_[0-9abcdefghjkmnpqrstvwxyz]{26}$" } }, "required": ["kind", "sourceAttemptId"] } ] } }, "required": [ "attemptNumber", "delivery", "id", "occurrence", "startedAt", "trigger" ] } }, "freshness": { "type": "object", "properties": { "kind": { "type": "string", "const": "authoritative" } }, "required": ["kind"] }, "nextCursor": { "type": "string", "minLength": 1 } }, "required": ["data", "freshness"] } } }, "description": "List delivery attempts" }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "404": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["not_found"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: not_found." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["project_archived"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: project_archived." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "List delivery attempts", "security": [ { "apiCredential": ["occurrences:read"] }, { "memberSession": ["occurrences:read"], "memberSessionEnvironment": [], "memberSessionProject": [] } ] } }, "/v1/schedules/{scheduleId}/occurrences/{occurrenceId}/attempts/{attemptId}": { "get": { "description": "Reads one immutable delivery attempt from its occurrence's PostgreSQL authority. Ambiguous means the receiver may have acted and is never rewritten into certainty without durable result evidence. Optional first-outbound fields come only from trusted transport evidence and absence means unknown, never zero. The bounded response omits callback payloads, response bodies, destinations, signing material, secrets and raw transport failures by construction.", "operationId": "attempts.read", "parameters": [ { "in": "path", "name": "scheduleId", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "occurrenceId", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "attemptId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "attempt": { "attemptNumber": 2, "classifiedAt": "2026-07-28T15:02:00.000Z", "delivery": "dlv_11h8xyz9k2m4n6p8r0t2v4w6y8", "diagnostic": "network_ambiguous", "durationMs": 10000, "firstAttemptLatenessMs": 0, "firstAttemptStartedAt": "2026-07-28T15:00:00.000Z", "timingEligibility": "eligible", "timingPolicyVersion": "payg-v1", "id": "att_11h8xyz9k2m4n6p8r0t2v4w6y8", "occurrence": "occ_01h8xyz9k2m4n6p8r0t2v4w6y8", "remediation": "review_before_redelivery", "startedAt": "2026-07-28T15:01:50.000Z", "state": "ambiguous", "trigger": { "kind": "automatic" } }, "freshness": { "kind": "authoritative" } }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "attempt": { "type": "object", "properties": { "attemptNumber": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "classifiedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "delivery": { "type": "string", "pattern": "^dlv_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "diagnostic": { "type": "string", "x-callback-attempt-diagnostics": [ "completion_timed_out", "delivered", "duplicate_inflight", "endpoint_unavailable", "endpoint_unsafe", "http_refused", "http_retryable", "http_terminal", "identity_conflict", "network_ambiguous", "payload_unavailable", "rate_limited" ] }, "durationMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "firstAttemptLatenessMs": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "firstAttemptStartedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "timingEligibility": { "type": "string", "enum": [ "eligible", "customer_blocked", "platform_blocked" ] }, "timingEligibilityReason": { "type": "string", "minLength": 1, "maxLength": 128 }, "timingPolicyVersion": { "type": "string", "minLength": 1, "maxLength": 64 }, "id": { "type": "string", "pattern": "^att_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "occurrence": { "type": "string", "pattern": "^occ_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "remediation": { "type": "string", "enum": [ "none", "review_retry_policy", "inspect_receiver", "review_endpoint", "replace_payload", "contact_support", "review_before_redelivery" ] }, "failureSnippet": { "type": "object", "properties": { "contentType": { "type": "string", "minLength": 1, "maxLength": 128 }, "text": { "type": "string", "maxLength": 4096 }, "truncated": { "type": "boolean" } }, "required": ["contentType", "text", "truncated"] }, "responseHeaders": { "maxItems": 8, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64 }, "value": { "type": "string", "maxLength": 256 } }, "required": ["name", "value"] } }, "responseStatus": { "type": "integer", "minimum": 100, "maximum": 599 }, "startedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "state": { "type": "string", "enum": [ "succeeded", "retryable_failure", "terminal_failure", "ambiguous" ] }, "trigger": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "automatic" } }, "required": ["kind"] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "redelivery" }, "sourceAttemptId": { "type": "string", "pattern": "^att_[0-9abcdefghjkmnpqrstvwxyz]{26}$" } }, "required": ["kind", "sourceAttemptId"] } ] } }, "required": [ "attemptNumber", "delivery", "id", "occurrence", "startedAt", "trigger" ] }, "freshness": { "type": "object", "properties": { "kind": { "type": "string", "const": "authoritative" } }, "required": ["kind"] } }, "required": ["attempt", "freshness"] } } }, "description": "Read a delivery attempt" }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "404": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["not_found"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: not_found." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["project_archived"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: project_archived." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Read a delivery attempt", "security": [ { "apiCredential": ["occurrences:read"] }, { "memberSession": ["occurrences:read"], "memberSessionEnvironment": [], "memberSessionProject": [] } ] } }, "/v1/schedules/{scheduleId}/occurrences/{occurrenceId}/redeliver": { "post": { "description": "Creates one new immutable attempt under the same retained terminal occurrence and dispatches it through the ordinary delivery boundary. The required Idempotency-Key makes an identical replay converge on the same attempt and conflicting reuse is refused. The new attempt names the retained attempt that caused the redelivery; no earlier identity or outcome is changed. MCP marks this outbound mutation for explicit approval even though it is non-destructive.", "operationId": "occurrences.redeliver", "parameters": [ { "in": "path", "name": "scheduleId", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "occurrenceId", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "minLength": 16, "maxLength": 255, "pattern": "^[\\x20-\\x7e]+$" } } ], "responses": { "201": { "content": { "application/json": { "example": { "attempt": { "attemptNumber": 3, "delivery": "dlv_21h8xyz9k2m4n6p8r0t2v4w6y8", "id": "att_21h8xyz9k2m4n6p8r0t2v4w6y8", "occurrence": "occ_01h8xyz9k2m4n6p8r0t2v4w6y8", "startedAt": "2026-07-28T15:05:00.000Z", "trigger": { "kind": "redelivery", "sourceAttemptId": "att_11h8xyz9k2m4n6p8r0t2v4w6y8" } }, "freshness": { "kind": "authoritative" } }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "attempt": { "type": "object", "properties": { "attemptNumber": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "classifiedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "delivery": { "type": "string", "pattern": "^dlv_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "diagnostic": { "type": "string", "x-callback-attempt-diagnostics": [ "completion_timed_out", "delivered", "duplicate_inflight", "endpoint_unavailable", "endpoint_unsafe", "http_refused", "http_retryable", "http_terminal", "identity_conflict", "network_ambiguous", "payload_unavailable", "rate_limited" ] }, "durationMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "firstAttemptLatenessMs": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "firstAttemptStartedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "timingEligibility": { "type": "string", "enum": [ "eligible", "customer_blocked", "platform_blocked" ] }, "timingEligibilityReason": { "type": "string", "minLength": 1, "maxLength": 128 }, "timingPolicyVersion": { "type": "string", "minLength": 1, "maxLength": 64 }, "id": { "type": "string", "pattern": "^att_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "occurrence": { "type": "string", "pattern": "^occ_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "remediation": { "type": "string", "enum": [ "none", "review_retry_policy", "inspect_receiver", "review_endpoint", "replace_payload", "contact_support", "review_before_redelivery" ] }, "failureSnippet": { "type": "object", "properties": { "contentType": { "type": "string", "minLength": 1, "maxLength": 128 }, "text": { "type": "string", "maxLength": 4096 }, "truncated": { "type": "boolean" } }, "required": ["contentType", "text", "truncated"] }, "responseHeaders": { "maxItems": 8, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64 }, "value": { "type": "string", "maxLength": 256 } }, "required": ["name", "value"] } }, "responseStatus": { "type": "integer", "minimum": 100, "maximum": 599 }, "startedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "state": { "type": "string", "enum": [ "succeeded", "retryable_failure", "terminal_failure", "ambiguous" ] }, "trigger": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "automatic" } }, "required": ["kind"] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "redelivery" }, "sourceAttemptId": { "type": "string", "pattern": "^att_[0-9abcdefghjkmnpqrstvwxyz]{26}$" } }, "required": ["kind", "sourceAttemptId"] } ] } }, "required": [ "attemptNumber", "delivery", "id", "occurrence", "startedAt", "trigger" ] }, "freshness": { "type": "object", "properties": { "kind": { "type": "string", "const": "authoritative" } }, "required": ["kind"] } }, "required": ["attempt", "freshness"] } } }, "description": "Redeliver an occurrence", "headers": { "Idempotency-Replayed": { "required": false, "schema": { "type": "string", "const": "true" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "404": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["not_found"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: not_found." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "idempotency_key_reused", "project_archived", "state_conflict" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: idempotency_key_reused, project_archived, state_conflict." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Redeliver an occurrence", "security": [ { "apiCredential": ["occurrences:redeliver"] }, { "memberSession": ["occurrences:redeliver"], "memberSessionEnvironment": [], "memberSessionProject": [] } ] } }, "/v1/schedules/{scheduleId}/pause": { "post": { "description": "Suspends a schedule without discarding it: its occurrence stays planned, its timer is released, and resume re-arms the original planned instant rather than silently moving it. If that instant has passed, the schedule's lateness policy decides whether the first arrival becomes due or settles `skipped_stale`; a pause defers the decision, it does not promise delivery. A schedule with a dispatching or ambiguous callback is refused until that attempt settles, because pausing cannot strand its watchdog or turn a proven success into an unreachable completed state. Pausing an already paused schedule changes nothing and returns the same version, so a retry is free. A cancelled or completed schedule cannot be paused.", "operationId": "schedules.pause", "parameters": [ { "in": "path", "name": "scheduleId", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "If-Match", "required": false, "schema": { "type": "string", "pattern": "^\"([1-9][0-9]{0,18})\"$" } } ], "responses": { "200": { "content": { "application/json": { "example": { "occurrence": { "attemptCount": 0, "generation": 1, "id": "occ_01h8xyz9k2m4n6p8r0t2v4w6y8", "plannedFor": "2026-07-28T15:00:00.000Z", "schedule": "sch_01h8xyz9k2m4n6p8r0t2v4w6y8", "sequence": 1, "state": "planned" }, "schedule": { "createdAt": "2026-07-28T14:59:00.000Z", "generation": 1, "id": "sch_01h8xyz9k2m4n6p8r0t2v4w6y8", "latencyClass": "realtime", "lateness": { "policy": "catchUp" }, "recurrence": { "kind": "at" }, "status": "paused", "updatedAt": "2026-07-28T15:10:00.000Z", "version": 2 } }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "occurrence": { "type": "object", "properties": { "attemptCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "firstAttemptLatenessMs": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "firstAttemptStartedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "timingEligibility": { "type": "string", "enum": [ "eligible", "customer_blocked", "platform_blocked" ] }, "timingEligibilityReason": { "type": "string", "minLength": 1, "maxLength": 128 }, "timingPolicyVersion": { "type": "string", "minLength": 1, "maxLength": 64 }, "generation": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "id": { "type": "string", "pattern": "^occ_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "plannedFor": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "schedule": { "type": "string", "pattern": "^sch_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "sequence": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "settledAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "state": { "type": "string", "enum": [ "planned", "due", "dispatching", "retry_wait", "ambiguous", "succeeded", "terminal_failed", "cancelled", "skipped_stale" ] } }, "required": [ "attemptCount", "generation", "id", "plannedFor", "schedule", "sequence", "state" ] }, "schedule": { "type": "object", "properties": { "archivedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "data": { "$ref": "#/$defs/__schema0" }, "createdAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "delivery": { "type": "object", "properties": { "completion": { "type": "string", "enum": ["response", "callback"] }, "maxDurationSeconds": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "onOverlap": { "type": "string", "enum": ["skip", "queue"] } }, "required": [ "completion", "maxDurationSeconds", "onOverlap" ] }, "endpoint": { "type": "string", "pattern": "^ep_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "endpointUrl": { "type": "string", "format": "uri" }, "generation": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "id": { "type": "string", "pattern": "^sch_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "latencyClass": { "type": "string", "enum": ["realtime", "bulk"] }, "lateness": { "type": "object", "properties": { "maxStalenessSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "policy": { "type": "string", "enum": ["skipAhead", "catchUp"] } }, "required": ["policy"] }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "partitionKey": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9._:-]+$" }, "nextDueAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "recurrence": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "at" } }, "required": ["kind"] }, { "type": "object", "properties": { "everySeconds": { "type": "integer", "minimum": 60, "maximum": 31536000 }, "kind": { "type": "string", "const": "every" } }, "required": ["everySeconds", "kind"] }, { "type": "object", "properties": { "cron": { "type": "string", "minLength": 1, "maxLength": 120 }, "kind": { "type": "string", "const": "cron" }, "timeZone": {} }, "required": ["cron", "kind", "timeZone"] } ] }, "status": { "type": "string", "enum": ["active", "paused", "cancelled", "completed"] }, "updatedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "createdAt", "generation", "id", "latencyClass", "lateness", "recurrence", "status", "updatedAt", "version" ] } }, "required": ["occurrence", "schedule"], "$defs": { "__schema0": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/$defs/__schema0" } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/$defs/__schema0" } } ] } } } } }, "description": "Pause a schedule", "headers": { "ETag": { "required": true, "schema": { "type": "string", "pattern": "^\"([1-9][0-9]{0,18})\"$" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "404": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["not_found"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: not_found." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "project_archived", "state_conflict", "version_conflict" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: project_archived, state_conflict, version_conflict." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Pause a schedule", "security": [ { "apiCredential": ["schedules:write"] }, { "memberSession": ["schedules:write"], "memberSessionEnvironment": [], "memberSessionProject": [] } ] } }, "/v1/schedules/{scheduleId}/resume": { "post": { "description": "Returns a paused schedule to active and re-arms its original planned instant. When that instant passed during the pause, the schedule's lateness policy applies exactly as it does after an outage: `catchUp` makes an occurrence inside its window due, while `skipAhead` or an expired window settles it `skipped_stale`. An occurrence already on its retry ladder is exempt from this first-arrival decision. Resuming an already active schedule changes nothing and returns the same version.", "operationId": "schedules.resume", "parameters": [ { "in": "path", "name": "scheduleId", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "If-Match", "required": false, "schema": { "type": "string", "pattern": "^\"([1-9][0-9]{0,18})\"$" } } ], "responses": { "200": { "content": { "application/json": { "example": { "occurrence": { "attemptCount": 0, "generation": 1, "id": "occ_01h8xyz9k2m4n6p8r0t2v4w6y8", "plannedFor": "2026-07-28T15:00:00.000Z", "schedule": "sch_01h8xyz9k2m4n6p8r0t2v4w6y8", "sequence": 1, "state": "planned" }, "schedule": { "createdAt": "2026-07-28T14:59:00.000Z", "generation": 1, "id": "sch_01h8xyz9k2m4n6p8r0t2v4w6y8", "latencyClass": "realtime", "lateness": { "policy": "catchUp" }, "recurrence": { "kind": "at" }, "status": "active", "updatedAt": "2026-07-28T15:20:00.000Z", "version": 3 } }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "occurrence": { "type": "object", "properties": { "attemptCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "firstAttemptLatenessMs": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "firstAttemptStartedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "timingEligibility": { "type": "string", "enum": [ "eligible", "customer_blocked", "platform_blocked" ] }, "timingEligibilityReason": { "type": "string", "minLength": 1, "maxLength": 128 }, "timingPolicyVersion": { "type": "string", "minLength": 1, "maxLength": 64 }, "generation": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "id": { "type": "string", "pattern": "^occ_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "plannedFor": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "schedule": { "type": "string", "pattern": "^sch_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "sequence": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "settledAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "state": { "type": "string", "enum": [ "planned", "due", "dispatching", "retry_wait", "ambiguous", "succeeded", "terminal_failed", "cancelled", "skipped_stale" ] } }, "required": [ "attemptCount", "generation", "id", "plannedFor", "schedule", "sequence", "state" ] }, "schedule": { "type": "object", "properties": { "archivedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "data": { "$ref": "#/$defs/__schema0" }, "createdAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "delivery": { "type": "object", "properties": { "completion": { "type": "string", "enum": ["response", "callback"] }, "maxDurationSeconds": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "onOverlap": { "type": "string", "enum": ["skip", "queue"] } }, "required": [ "completion", "maxDurationSeconds", "onOverlap" ] }, "endpoint": { "type": "string", "pattern": "^ep_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "endpointUrl": { "type": "string", "format": "uri" }, "generation": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "id": { "type": "string", "pattern": "^sch_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "latencyClass": { "type": "string", "enum": ["realtime", "bulk"] }, "lateness": { "type": "object", "properties": { "maxStalenessSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "policy": { "type": "string", "enum": ["skipAhead", "catchUp"] } }, "required": ["policy"] }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "partitionKey": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9._:-]+$" }, "nextDueAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "recurrence": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "at" } }, "required": ["kind"] }, { "type": "object", "properties": { "everySeconds": { "type": "integer", "minimum": 60, "maximum": 31536000 }, "kind": { "type": "string", "const": "every" } }, "required": ["everySeconds", "kind"] }, { "type": "object", "properties": { "cron": { "type": "string", "minLength": 1, "maxLength": 120 }, "kind": { "type": "string", "const": "cron" }, "timeZone": {} }, "required": ["cron", "kind", "timeZone"] } ] }, "status": { "type": "string", "enum": ["active", "paused", "cancelled", "completed"] }, "updatedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "createdAt", "generation", "id", "latencyClass", "lateness", "recurrence", "status", "updatedAt", "version" ] } }, "required": ["occurrence", "schedule"], "$defs": { "__schema0": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/$defs/__schema0" } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/$defs/__schema0" } } ] } } } } }, "description": "Resume a schedule", "headers": { "ETag": { "required": true, "schema": { "type": "string", "pattern": "^\"([1-9][0-9]{0,18})\"$" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "404": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["not_found"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: not_found." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "project_archived", "state_conflict", "version_conflict" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: project_archived, state_conflict, version_conflict." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Resume a schedule", "security": [ { "apiCredential": ["schedules:write"] }, { "memberSession": ["schedules:write"], "memberSessionEnvironment": [], "memberSessionProject": [] } ] } }, "/v1/schedules/{scheduleId}/archive": { "post": { "description": "Files a finished schedule away: it leaves the default listing and stays readable by identifier, carrying the instant it was archived. Only a cancelled or completed schedule can be archived — archiving is filing, not stopping, so cancel it first. Archiving an already archived schedule changes nothing and returns the same version.", "operationId": "schedules.archive", "parameters": [ { "in": "path", "name": "scheduleId", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "If-Match", "required": false, "schema": { "type": "string", "pattern": "^\"([1-9][0-9]{0,18})\"$" } } ], "responses": { "200": { "content": { "application/json": { "example": { "occurrence": { "attemptCount": 0, "generation": 1, "id": "occ_01h8xyz9k2m4n6p8r0t2v4w6y8", "plannedFor": "2026-07-28T15:00:00.000Z", "schedule": "sch_01h8xyz9k2m4n6p8r0t2v4w6y8", "sequence": 1, "settledAt": "2026-07-28T15:10:00.000Z", "state": "cancelled" }, "schedule": { "archivedAt": "2026-07-28T15:30:00.000Z", "createdAt": "2026-07-28T14:59:00.000Z", "generation": 1, "id": "sch_01h8xyz9k2m4n6p8r0t2v4w6y8", "latencyClass": "realtime", "lateness": { "policy": "catchUp" }, "recurrence": { "kind": "at" }, "status": "cancelled", "updatedAt": "2026-07-28T15:30:00.000Z", "version": 3 } }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "occurrence": { "type": "object", "properties": { "attemptCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "firstAttemptLatenessMs": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "firstAttemptStartedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "timingEligibility": { "type": "string", "enum": [ "eligible", "customer_blocked", "platform_blocked" ] }, "timingEligibilityReason": { "type": "string", "minLength": 1, "maxLength": 128 }, "timingPolicyVersion": { "type": "string", "minLength": 1, "maxLength": 64 }, "generation": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "id": { "type": "string", "pattern": "^occ_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "plannedFor": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "schedule": { "type": "string", "pattern": "^sch_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "sequence": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "settledAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "state": { "type": "string", "enum": [ "planned", "due", "dispatching", "retry_wait", "ambiguous", "succeeded", "terminal_failed", "cancelled", "skipped_stale" ] } }, "required": [ "attemptCount", "generation", "id", "plannedFor", "schedule", "sequence", "state" ] }, "schedule": { "type": "object", "properties": { "archivedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "data": { "$ref": "#/$defs/__schema0" }, "createdAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "delivery": { "type": "object", "properties": { "completion": { "type": "string", "enum": ["response", "callback"] }, "maxDurationSeconds": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "onOverlap": { "type": "string", "enum": ["skip", "queue"] } }, "required": [ "completion", "maxDurationSeconds", "onOverlap" ] }, "endpoint": { "type": "string", "pattern": "^ep_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "endpointUrl": { "type": "string", "format": "uri" }, "generation": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "id": { "type": "string", "pattern": "^sch_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "latencyClass": { "type": "string", "enum": ["realtime", "bulk"] }, "lateness": { "type": "object", "properties": { "maxStalenessSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "policy": { "type": "string", "enum": ["skipAhead", "catchUp"] } }, "required": ["policy"] }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "partitionKey": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9._:-]+$" }, "nextDueAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "recurrence": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "at" } }, "required": ["kind"] }, { "type": "object", "properties": { "everySeconds": { "type": "integer", "minimum": 60, "maximum": 31536000 }, "kind": { "type": "string", "const": "every" } }, "required": ["everySeconds", "kind"] }, { "type": "object", "properties": { "cron": { "type": "string", "minLength": 1, "maxLength": 120 }, "kind": { "type": "string", "const": "cron" }, "timeZone": {} }, "required": ["cron", "kind", "timeZone"] } ] }, "status": { "type": "string", "enum": ["active", "paused", "cancelled", "completed"] }, "updatedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "createdAt", "generation", "id", "latencyClass", "lateness", "recurrence", "status", "updatedAt", "version" ] } }, "required": ["occurrence", "schedule"], "$defs": { "__schema0": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/$defs/__schema0" } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/$defs/__schema0" } } ] } } } } }, "description": "Archive a schedule", "headers": { "ETag": { "required": true, "schema": { "type": "string", "pattern": "^\"([1-9][0-9]{0,18})\"$" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["invalid_request"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: invalid_request." }, "401": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "authentication_required", "credential_expired", "credential_revoked" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked." }, "403": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["scope_missing"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: scope_missing." }, "404": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["not_found"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: not_found." }, "409": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": [ "project_archived", "state_conflict", "version_conflict" ] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: project_archived, state_conflict, version_conflict." }, "429": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["rate_limited"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: rate_limited." }, "503": { "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "x-problem-codes": ["service_unavailable"] }, "detail": { "type": "string", "minLength": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "pattern": "^\\/.*" }, "reason": { "type": "string", "minLength": 1 } }, "required": ["pointer", "reason"] } }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "title": { "type": "string", "minLength": 1 }, "traceId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "about:blank" } }, "required": ["code", "status", "title", "type"] } } }, "description": "Problem document. Possible codes at this status: service_unavailable." } }, "summary": "Archive a schedule", "security": [ { "apiCredential": ["schedules:write"] }, { "memberSession": ["schedules:write"], "memberSessionEnvironment": [], "memberSessionProject": [] } ] } } }, "x-greatwait-callback-delivery-signature": { "envelope": { "propertyOrder": [ "version", "type", "scheduleId", "occurrenceId", "plannedFor", "attempt", "completion", "trigger", "data" ], "completionPropertyOrder": ["token", "url", "deadline"], "propertyOrder_2026_08_08": [ "version", "type", "scheduleId", "occurrenceId", "plannedFor", "attempt", "completion", "trigger", "data" ], "propertyOrder_2026_07_01": [ "version", "type", "scheduleId", "occurrenceId", "plannedFor", "attempt", "data" ], "serialization": "compact UTF-8 JSON with the stated top-level property order", "trigger": { "automatic": "A first attempt or a retry the system chose. Nobody asked for it, it may repeat work already done, and a receiver must run the occurrence at most once.", "default": "An envelope with no trigger field is automatic. Only 2026-07-01 can omit it.", "propertyOrder": ["kind", "sourceAttemptId"], "ordinal": "attempt. It only ever increases within an occurrence and every copy of one redelivery carries the same value, so a receiver recognises a repeat by keeping the highest it has run to completion rather than by keeping them all.", "redelivery": "A person ordered this delivery under the occurrences:redeliver scope. sourceAttemptId names the retained attempt they chose to follow and is there to show them, not to decide whether the work runs — attempt is what decides that. It is a request for the work to happen again, and a receiver that suppresses it as a duplicate answers a deliberate instruction with silence.", "requirement": "run the handler again for a redelivery whose attempt is above the highest this receiver has run to completion for the occurrence, keep suppressing every automatic delivery of a completed occurrence, and suppress every redelivery at or below that high-water mark" }, "version": "2026-08-23", "versions": ["2026-07-01", "2026-08-08", "2026-08-23"] }, "headers": { "contentType": "application/json", "required": [ "Content-Type", "Callback-Delivery-Id", "Callback-Occurrence-Id", "Callback-Timestamp", "Callback-Key-Id", "Callback-Signature" ] }, "replay": { "identity": "Callback-Delivery-Id", "requirement": "atomically reject a previously accepted delivery id before parsing" }, "signature": { "algorithm": "HMAC-SHA-256", "format": "v1=<64 lowercase hexadecimal characters>", "input": "ASCII .. followed by the exact raw request body bytes", "scheme": "v1", "timestampToleranceSeconds": 300 }, "legacyTestVector": { "envelope": { "attempt": 1, "data": {}, "occurrenceId": "occ_0123456789abcdefghjkmnpqrs", "plannedFor": "2026-07-28T15:00:00.000Z", "scheduleId": "sch_0123456789abcdefghjkmnpqrs", "type": "schedule.occurrence", "version": "2026-07-01" }, "exactBodyBase64": "eyJ2ZXJzaW9uIjoiMjAyNi0wNy0wMSIsInR5cGUiOiJzY2hlZHVsZS5vY2N1cnJlbmNlIiwic2NoZWR1bGVJZCI6InNjaF8wMTIzNDU2Nzg5YWJjZGVmZ2hqa21ucHFycyIsIm9jY3VycmVuY2VJZCI6Im9jY18wMTIzNDU2Nzg5YWJjZGVmZ2hqa21ucHFycyIsInBsYW5uZWRGb3IiOiIyMDI2LTA3LTI4VDE1OjAwOjAwLjAwMFoiLCJhdHRlbXB0IjoxLCJkYXRhIjp7fX0=", "exactBodyUtf8": "{\"version\":\"2026-07-01\",\"type\":\"schedule.occurrence\",\"scheduleId\":\"sch_0123456789abcdefghjkmnpqrs\",\"occurrenceId\":\"occ_0123456789abcdefghjkmnpqrs\",\"plannedFor\":\"2026-07-28T15:00:00.000Z\",\"attempt\":1,\"data\":{}}", "headers": { "Callback-Delivery-Id": "dlv_0123456789abcdefghjkmnpqrs", "Callback-Key-Id": "csk_0123456789abcdefghjkmnpqrs", "Callback-Occurrence-Id": "occ_0123456789abcdefghjkmnpqrs", "Callback-Signature": "v1=11135fdfc0bc5d49ebcc9d3a0d8df1116179097cefe961c6eca281339e5cfab3", "Callback-Timestamp": "2026-07-28T15:00:00.000Z", "Content-Type": "application/json" }, "secret": "greatwait-signature-vector-key-not-a-credential", "signingInputBase64": "MjAyNi0wNy0yOFQxNTowMDowMC4wMDBaLmRsdl8wMTIzNDU2Nzg5YWJjZGVmZ2hqa21ucHFycy57InZlcnNpb24iOiIyMDI2LTA3LTAxIiwidHlwZSI6InNjaGVkdWxlLm9jY3VycmVuY2UiLCJzY2hlZHVsZUlkIjoic2NoXzAxMjM0NTY3ODlhYmNkZWZnaGprbW5wcXJzIiwib2NjdXJyZW5jZUlkIjoib2NjXzAxMjM0NTY3ODlhYmNkZWZnaGprbW5wcXJzIiwicGxhbm5lZEZvciI6IjIwMjYtMDctMjhUMTU6MDA6MDAuMDAwWiIsImF0dGVtcHQiOjEsImRhdGEiOnt9fQ==", "signingInputUtf8": "2026-07-28T15:00:00.000Z.dlv_0123456789abcdefghjkmnpqrs.{\"version\":\"2026-07-01\",\"type\":\"schedule.occurrence\",\"scheduleId\":\"sch_0123456789abcdefghjkmnpqrs\",\"occurrenceId\":\"occ_0123456789abcdefghjkmnpqrs\",\"plannedFor\":\"2026-07-28T15:00:00.000Z\",\"attempt\":1,\"data\":{}}" }, "triggerTestVector": { "envelope": { "attempt": 1, "data": {}, "occurrenceId": "occ_0123456789abcdefghjkmnpqrs", "plannedFor": "2026-07-28T15:00:00.000Z", "scheduleId": "sch_0123456789abcdefghjkmnpqrs", "trigger": { "kind": "automatic" }, "type": "schedule.occurrence", "version": "2026-08-08" }, "exactBodyBase64": "eyJ2ZXJzaW9uIjoiMjAyNi0wOC0wOCIsInR5cGUiOiJzY2hlZHVsZS5vY2N1cnJlbmNlIiwic2NoZWR1bGVJZCI6InNjaF8wMTIzNDU2Nzg5YWJjZGVmZ2hqa21ucHFycyIsIm9jY3VycmVuY2VJZCI6Im9jY18wMTIzNDU2Nzg5YWJjZGVmZ2hqa21ucHFycyIsInBsYW5uZWRGb3IiOiIyMDI2LTA3LTI4VDE1OjAwOjAwLjAwMFoiLCJhdHRlbXB0IjoxLCJ0cmlnZ2VyIjp7ImtpbmQiOiJhdXRvbWF0aWMifSwiZGF0YSI6e319", "exactBodyUtf8": "{\"version\":\"2026-08-08\",\"type\":\"schedule.occurrence\",\"scheduleId\":\"sch_0123456789abcdefghjkmnpqrs\",\"occurrenceId\":\"occ_0123456789abcdefghjkmnpqrs\",\"plannedFor\":\"2026-07-28T15:00:00.000Z\",\"attempt\":1,\"trigger\":{\"kind\":\"automatic\"},\"data\":{}}", "headers": { "Callback-Delivery-Id": "dlv_0123456789abcdefghjkmnpqrs", "Callback-Key-Id": "csk_0123456789abcdefghjkmnpqrs", "Callback-Occurrence-Id": "occ_0123456789abcdefghjkmnpqrs", "Callback-Signature": "v1=bd96c6d68a5c0521c18600d92913ce4dcf32036f2c930d0f9db9de55da9280e7", "Callback-Timestamp": "2026-07-28T15:00:00.000Z", "Content-Type": "application/json" }, "secret": "greatwait-signature-vector-key-not-a-credential", "signingInputBase64": "MjAyNi0wNy0yOFQxNTowMDowMC4wMDBaLmRsdl8wMTIzNDU2Nzg5YWJjZGVmZ2hqa21ucHFycy57InZlcnNpb24iOiIyMDI2LTA4LTA4IiwidHlwZSI6InNjaGVkdWxlLm9jY3VycmVuY2UiLCJzY2hlZHVsZUlkIjoic2NoXzAxMjM0NTY3ODlhYmNkZWZnaGprbW5wcXJzIiwib2NjdXJyZW5jZUlkIjoib2NjXzAxMjM0NTY3ODlhYmNkZWZnaGprbW5wcXJzIiwicGxhbm5lZEZvciI6IjIwMjYtMDctMjhUMTU6MDA6MDAuMDAwWiIsImF0dGVtcHQiOjEsInRyaWdnZXIiOnsia2luZCI6ImF1dG9tYXRpYyJ9LCJkYXRhIjp7fX0=", "signingInputUtf8": "2026-07-28T15:00:00.000Z.dlv_0123456789abcdefghjkmnpqrs.{\"version\":\"2026-08-08\",\"type\":\"schedule.occurrence\",\"scheduleId\":\"sch_0123456789abcdefghjkmnpqrs\",\"occurrenceId\":\"occ_0123456789abcdefghjkmnpqrs\",\"plannedFor\":\"2026-07-28T15:00:00.000Z\",\"attempt\":1,\"trigger\":{\"kind\":\"automatic\"},\"data\":{}}" }, "completionTestVector": { "envelope": { "attempt": 1, "completion": { "token": "v1.example-claim-not-a-real-token.example-mac", "url": "https://greatwait-scheduler.example/callbacks/completion" }, "data": {}, "occurrenceId": "occ_0123456789abcdefghjkmnpqrs", "plannedFor": "2026-07-28T15:00:00.000Z", "scheduleId": "sch_0123456789abcdefghjkmnpqrs", "trigger": { "kind": "automatic" }, "type": "schedule.occurrence", "version": "2026-08-08" }, "exactBodyBase64": "eyJ2ZXJzaW9uIjoiMjAyNi0wOC0wOCIsInR5cGUiOiJzY2hlZHVsZS5vY2N1cnJlbmNlIiwic2NoZWR1bGVJZCI6InNjaF8wMTIzNDU2Nzg5YWJjZGVmZ2hqa21ucHFycyIsIm9jY3VycmVuY2VJZCI6Im9jY18wMTIzNDU2Nzg5YWJjZGVmZ2hqa21ucHFycyIsInBsYW5uZWRGb3IiOiIyMDI2LTA3LTI4VDE1OjAwOjAwLjAwMFoiLCJhdHRlbXB0IjoxLCJjb21wbGV0aW9uIjp7InRva2VuIjoidjEuZXhhbXBsZS1jbGFpbS1ub3QtYS1yZWFsLXRva2VuLmV4YW1wbGUtbWFjIiwidXJsIjoiaHR0cHM6Ly9ncmVhdHdhaXQtc2NoZWR1bGVyLmV4YW1wbGUvY2FsbGJhY2tzL2NvbXBsZXRpb24ifSwidHJpZ2dlciI6eyJraW5kIjoiYXV0b21hdGljIn0sImRhdGEiOnt9fQ==", "exactBodyUtf8": "{\"version\":\"2026-08-08\",\"type\":\"schedule.occurrence\",\"scheduleId\":\"sch_0123456789abcdefghjkmnpqrs\",\"occurrenceId\":\"occ_0123456789abcdefghjkmnpqrs\",\"plannedFor\":\"2026-07-28T15:00:00.000Z\",\"attempt\":1,\"completion\":{\"token\":\"v1.example-claim-not-a-real-token.example-mac\",\"url\":\"https://greatwait-scheduler.example/callbacks/completion\"},\"trigger\":{\"kind\":\"automatic\"},\"data\":{}}", "headers": { "Callback-Delivery-Id": "dlv_0123456789abcdefghjkmnpqrs", "Callback-Key-Id": "csk_0123456789abcdefghjkmnpqrs", "Callback-Occurrence-Id": "occ_0123456789abcdefghjkmnpqrs", "Callback-Signature": "v1=38c6d854051087ed408a5f6252d90375859f305aeb0bca1c3f3a5bb63135e138", "Callback-Timestamp": "2026-07-28T15:00:00.000Z", "Content-Type": "application/json" }, "secret": "greatwait-signature-vector-key-not-a-credential", "signingInputBase64": "MjAyNi0wNy0yOFQxNTowMDowMC4wMDBaLmRsdl8wMTIzNDU2Nzg5YWJjZGVmZ2hqa21ucHFycy57InZlcnNpb24iOiIyMDI2LTA4LTA4IiwidHlwZSI6InNjaGVkdWxlLm9jY3VycmVuY2UiLCJzY2hlZHVsZUlkIjoic2NoXzAxMjM0NTY3ODlhYmNkZWZnaGprbW5wcXJzIiwib2NjdXJyZW5jZUlkIjoib2NjXzAxMjM0NTY3ODlhYmNkZWZnaGprbW5wcXJzIiwicGxhbm5lZEZvciI6IjIwMjYtMDctMjhUMTU6MDA6MDAuMDAwWiIsImF0dGVtcHQiOjEsImNvbXBsZXRpb24iOnsidG9rZW4iOiJ2MS5leGFtcGxlLWNsYWltLW5vdC1hLXJlYWwtdG9rZW4uZXhhbXBsZS1tYWMiLCJ1cmwiOiJodHRwczovL2dyZWF0d2FpdC1zY2hlZHVsZXIuZXhhbXBsZS9jYWxsYmFja3MvY29tcGxldGlvbiJ9LCJ0cmlnZ2VyIjp7ImtpbmQiOiJhdXRvbWF0aWMifSwiZGF0YSI6e319", "signingInputUtf8": "2026-07-28T15:00:00.000Z.dlv_0123456789abcdefghjkmnpqrs.{\"version\":\"2026-08-08\",\"type\":\"schedule.occurrence\",\"scheduleId\":\"sch_0123456789abcdefghjkmnpqrs\",\"occurrenceId\":\"occ_0123456789abcdefghjkmnpqrs\",\"plannedFor\":\"2026-07-28T15:00:00.000Z\",\"attempt\":1,\"completion\":{\"token\":\"v1.example-claim-not-a-real-token.example-mac\",\"url\":\"https://greatwait-scheduler.example/callbacks/completion\"},\"trigger\":{\"kind\":\"automatic\"},\"data\":{}}" }, "redeliveryTestVector": { "envelope": { "attempt": 2, "completion": { "deadline": "2026-07-28T15:00:05.000Z", "token": "v2.example-claim-not-a-real-token.example-mac", "url": "https://greatwait-scheduler.example/callbacks/completion" }, "data": {}, "occurrenceId": "occ_0123456789abcdefghjkmnpqrs", "plannedFor": "2026-07-28T15:00:00.000Z", "scheduleId": "sch_0123456789abcdefghjkmnpqrs", "trigger": { "kind": "redelivery", "sourceAttemptId": "att_0123456789abcdefghjkmnpqrs" }, "type": "schedule.occurrence", "version": "2026-08-23" }, "exactBodyBase64": "eyJ2ZXJzaW9uIjoiMjAyNi0wOC0yMyIsInR5cGUiOiJzY2hlZHVsZS5vY2N1cnJlbmNlIiwic2NoZWR1bGVJZCI6InNjaF8wMTIzNDU2Nzg5YWJjZGVmZ2hqa21ucHFycyIsIm9jY3VycmVuY2VJZCI6Im9jY18wMTIzNDU2Nzg5YWJjZGVmZ2hqa21ucHFycyIsInBsYW5uZWRGb3IiOiIyMDI2LTA3LTI4VDE1OjAwOjAwLjAwMFoiLCJhdHRlbXB0IjoyLCJjb21wbGV0aW9uIjp7InRva2VuIjoidjIuZXhhbXBsZS1jbGFpbS1ub3QtYS1yZWFsLXRva2VuLmV4YW1wbGUtbWFjIiwidXJsIjoiaHR0cHM6Ly9ncmVhdHdhaXQtc2NoZWR1bGVyLmV4YW1wbGUvY2FsbGJhY2tzL2NvbXBsZXRpb24iLCJkZWFkbGluZSI6IjIwMjYtMDctMjhUMTU6MDA6MDUuMDAwWiJ9LCJ0cmlnZ2VyIjp7ImtpbmQiOiJyZWRlbGl2ZXJ5Iiwic291cmNlQXR0ZW1wdElkIjoiYXR0XzAxMjM0NTY3ODlhYmNkZWZnaGprbW5wcXJzIn0sImRhdGEiOnt9fQ==", "exactBodyUtf8": "{\"version\":\"2026-08-23\",\"type\":\"schedule.occurrence\",\"scheduleId\":\"sch_0123456789abcdefghjkmnpqrs\",\"occurrenceId\":\"occ_0123456789abcdefghjkmnpqrs\",\"plannedFor\":\"2026-07-28T15:00:00.000Z\",\"attempt\":2,\"completion\":{\"token\":\"v2.example-claim-not-a-real-token.example-mac\",\"url\":\"https://greatwait-scheduler.example/callbacks/completion\",\"deadline\":\"2026-07-28T15:00:05.000Z\"},\"trigger\":{\"kind\":\"redelivery\",\"sourceAttemptId\":\"att_0123456789abcdefghjkmnpqrs\"},\"data\":{}}", "headers": { "Callback-Delivery-Id": "dlv_0123456789abcdefghjkmnpqrs", "Callback-Key-Id": "csk_0123456789abcdefghjkmnpqrs", "Callback-Occurrence-Id": "occ_0123456789abcdefghjkmnpqrs", "Callback-Signature": "v1=9d698aed6d05dcd964f00d6e6796aab238f4f50e6f5cfeb61751fd7850778a04", "Callback-Timestamp": "2026-07-28T15:00:00.000Z", "Content-Type": "application/json" }, "secret": "greatwait-signature-vector-key-not-a-credential", "signingInputBase64": "MjAyNi0wNy0yOFQxNTowMDowMC4wMDBaLmRsdl8wMTIzNDU2Nzg5YWJjZGVmZ2hqa21ucHFycy57InZlcnNpb24iOiIyMDI2LTA4LTIzIiwidHlwZSI6InNjaGVkdWxlLm9jY3VycmVuY2UiLCJzY2hlZHVsZUlkIjoic2NoXzAxMjM0NTY3ODlhYmNkZWZnaGprbW5wcXJzIiwib2NjdXJyZW5jZUlkIjoib2NjXzAxMjM0NTY3ODlhYmNkZWZnaGprbW5wcXJzIiwicGxhbm5lZEZvciI6IjIwMjYtMDctMjhUMTU6MDA6MDAuMDAwWiIsImF0dGVtcHQiOjIsImNvbXBsZXRpb24iOnsidG9rZW4iOiJ2Mi5leGFtcGxlLWNsYWltLW5vdC1hLXJlYWwtdG9rZW4uZXhhbXBsZS1tYWMiLCJ1cmwiOiJodHRwczovL2dyZWF0d2FpdC1zY2hlZHVsZXIuZXhhbXBsZS9jYWxsYmFja3MvY29tcGxldGlvbiIsImRlYWRsaW5lIjoiMjAyNi0wNy0yOFQxNTowMDowNS4wMDBaIn0sInRyaWdnZXIiOnsia2luZCI6InJlZGVsaXZlcnkiLCJzb3VyY2VBdHRlbXB0SWQiOiJhdHRfMDEyMzQ1Njc4OWFiY2RlZmdoamttbnBxcnMifSwiZGF0YSI6e319", "signingInputUtf8": "2026-07-28T15:00:00.000Z.dlv_0123456789abcdefghjkmnpqrs.{\"version\":\"2026-08-23\",\"type\":\"schedule.occurrence\",\"scheduleId\":\"sch_0123456789abcdefghjkmnpqrs\",\"occurrenceId\":\"occ_0123456789abcdefghjkmnpqrs\",\"plannedFor\":\"2026-07-28T15:00:00.000Z\",\"attempt\":2,\"completion\":{\"token\":\"v2.example-claim-not-a-real-token.example-mac\",\"url\":\"https://greatwait-scheduler.example/callbacks/completion\",\"deadline\":\"2026-07-28T15:00:05.000Z\"},\"trigger\":{\"kind\":\"redelivery\",\"sourceAttemptId\":\"att_0123456789abcdefghjkmnpqrs\"},\"data\":{}}" }, "testVector": { "envelope": { "attempt": 1, "completion": { "deadline": "2026-07-28T15:00:05.000Z", "token": "v2.example-claim-not-a-real-token.example-mac", "url": "https://greatwait-scheduler.example/callbacks/completion" }, "data": {}, "occurrenceId": "occ_0123456789abcdefghjkmnpqrs", "plannedFor": "2026-07-28T15:00:00.000Z", "scheduleId": "sch_0123456789abcdefghjkmnpqrs", "trigger": { "kind": "automatic" }, "type": "schedule.occurrence", "version": "2026-08-23" }, "exactBodyBase64": "eyJ2ZXJzaW9uIjoiMjAyNi0wOC0yMyIsInR5cGUiOiJzY2hlZHVsZS5vY2N1cnJlbmNlIiwic2NoZWR1bGVJZCI6InNjaF8wMTIzNDU2Nzg5YWJjZGVmZ2hqa21ucHFycyIsIm9jY3VycmVuY2VJZCI6Im9jY18wMTIzNDU2Nzg5YWJjZGVmZ2hqa21ucHFycyIsInBsYW5uZWRGb3IiOiIyMDI2LTA3LTI4VDE1OjAwOjAwLjAwMFoiLCJhdHRlbXB0IjoxLCJjb21wbGV0aW9uIjp7InRva2VuIjoidjIuZXhhbXBsZS1jbGFpbS1ub3QtYS1yZWFsLXRva2VuLmV4YW1wbGUtbWFjIiwidXJsIjoiaHR0cHM6Ly9ncmVhdHdhaXQtc2NoZWR1bGVyLmV4YW1wbGUvY2FsbGJhY2tzL2NvbXBsZXRpb24iLCJkZWFkbGluZSI6IjIwMjYtMDctMjhUMTU6MDA6MDUuMDAwWiJ9LCJ0cmlnZ2VyIjp7ImtpbmQiOiJhdXRvbWF0aWMifSwiZGF0YSI6e319", "exactBodyUtf8": "{\"version\":\"2026-08-23\",\"type\":\"schedule.occurrence\",\"scheduleId\":\"sch_0123456789abcdefghjkmnpqrs\",\"occurrenceId\":\"occ_0123456789abcdefghjkmnpqrs\",\"plannedFor\":\"2026-07-28T15:00:00.000Z\",\"attempt\":1,\"completion\":{\"token\":\"v2.example-claim-not-a-real-token.example-mac\",\"url\":\"https://greatwait-scheduler.example/callbacks/completion\",\"deadline\":\"2026-07-28T15:00:05.000Z\"},\"trigger\":{\"kind\":\"automatic\"},\"data\":{}}", "headers": { "Callback-Delivery-Id": "dlv_0123456789abcdefghjkmnpqrs", "Callback-Key-Id": "csk_0123456789abcdefghjkmnpqrs", "Callback-Occurrence-Id": "occ_0123456789abcdefghjkmnpqrs", "Callback-Signature": "v1=5bf68b786fbac1afa7e3474ae5039ad27900b0185bca43a3e45185d56315a312", "Callback-Timestamp": "2026-07-28T15:00:00.000Z", "Content-Type": "application/json" }, "secret": "greatwait-signature-vector-key-not-a-credential", "signingInputBase64": "MjAyNi0wNy0yOFQxNTowMDowMC4wMDBaLmRsdl8wMTIzNDU2Nzg5YWJjZGVmZ2hqa21ucHFycy57InZlcnNpb24iOiIyMDI2LTA4LTIzIiwidHlwZSI6InNjaGVkdWxlLm9jY3VycmVuY2UiLCJzY2hlZHVsZUlkIjoic2NoXzAxMjM0NTY3ODlhYmNkZWZnaGprbW5wcXJzIiwib2NjdXJyZW5jZUlkIjoib2NjXzAxMjM0NTY3ODlhYmNkZWZnaGprbW5wcXJzIiwicGxhbm5lZEZvciI6IjIwMjYtMDctMjhUMTU6MDA6MDAuMDAwWiIsImF0dGVtcHQiOjEsImNvbXBsZXRpb24iOnsidG9rZW4iOiJ2Mi5leGFtcGxlLWNsYWltLW5vdC1hLXJlYWwtdG9rZW4uZXhhbXBsZS1tYWMiLCJ1cmwiOiJodHRwczovL2dyZWF0d2FpdC1zY2hlZHVsZXIuZXhhbXBsZS9jYWxsYmFja3MvY29tcGxldGlvbiIsImRlYWRsaW5lIjoiMjAyNi0wNy0yOFQxNTowMDowNS4wMDBaIn0sInRyaWdnZXIiOnsia2luZCI6ImF1dG9tYXRpYyJ9LCJkYXRhIjp7fX0=", "signingInputUtf8": "2026-07-28T15:00:00.000Z.dlv_0123456789abcdefghjkmnpqrs.{\"version\":\"2026-08-23\",\"type\":\"schedule.occurrence\",\"scheduleId\":\"sch_0123456789abcdefghjkmnpqrs\",\"occurrenceId\":\"occ_0123456789abcdefghjkmnpqrs\",\"plannedFor\":\"2026-07-28T15:00:00.000Z\",\"attempt\":1,\"completion\":{\"token\":\"v2.example-claim-not-a-real-token.example-mac\",\"url\":\"https://greatwait-scheduler.example/callbacks/completion\",\"deadline\":\"2026-07-28T15:00:05.000Z\"},\"trigger\":{\"kind\":\"automatic\"},\"data\":{}}" }, "unicodeTestVector": { "envelope": { "attempt": 1, "completion": { "deadline": "2026-07-28T15:00:05.000Z", "token": "v2.example-claim-not-a-real-token.example-mac", "url": "https://greatwait-scheduler.example/callbacks/completion" }, "data": { "note": "café ☃" }, "occurrenceId": "occ_0123456789abcdefghjkmnpqrs", "plannedFor": "2026-07-28T15:00:00.000Z", "scheduleId": "sch_0123456789abcdefghjkmnpqrs", "trigger": { "kind": "automatic" }, "type": "schedule.occurrence", "version": "2026-08-23" }, "exactBodyBase64": "eyJ2ZXJzaW9uIjoiMjAyNi0wOC0yMyIsInR5cGUiOiJzY2hlZHVsZS5vY2N1cnJlbmNlIiwic2NoZWR1bGVJZCI6InNjaF8wMTIzNDU2Nzg5YWJjZGVmZ2hqa21ucHFycyIsIm9jY3VycmVuY2VJZCI6Im9jY18wMTIzNDU2Nzg5YWJjZGVmZ2hqa21ucHFycyIsInBsYW5uZWRGb3IiOiIyMDI2LTA3LTI4VDE1OjAwOjAwLjAwMFoiLCJhdHRlbXB0IjoxLCJjb21wbGV0aW9uIjp7InRva2VuIjoidjIuZXhhbXBsZS1jbGFpbS1ub3QtYS1yZWFsLXRva2VuLmV4YW1wbGUtbWFjIiwidXJsIjoiaHR0cHM6Ly9ncmVhdHdhaXQtc2NoZWR1bGVyLmV4YW1wbGUvY2FsbGJhY2tzL2NvbXBsZXRpb24iLCJkZWFkbGluZSI6IjIwMjYtMDctMjhUMTU6MDA6MDUuMDAwWiJ9LCJ0cmlnZ2VyIjp7ImtpbmQiOiJhdXRvbWF0aWMifSwiZGF0YSI6eyJub3RlIjoiY2Fmw6kg4piDIn19", "exactBodyUtf8": "{\"version\":\"2026-08-23\",\"type\":\"schedule.occurrence\",\"scheduleId\":\"sch_0123456789abcdefghjkmnpqrs\",\"occurrenceId\":\"occ_0123456789abcdefghjkmnpqrs\",\"plannedFor\":\"2026-07-28T15:00:00.000Z\",\"attempt\":1,\"completion\":{\"token\":\"v2.example-claim-not-a-real-token.example-mac\",\"url\":\"https://greatwait-scheduler.example/callbacks/completion\",\"deadline\":\"2026-07-28T15:00:05.000Z\"},\"trigger\":{\"kind\":\"automatic\"},\"data\":{\"note\":\"café ☃\"}}", "headers": { "Callback-Delivery-Id": "dlv_0123456789abcdefghjkmnpqrs", "Callback-Key-Id": "csk_0123456789abcdefghjkmnpqrs", "Callback-Occurrence-Id": "occ_0123456789abcdefghjkmnpqrs", "Callback-Signature": "v1=18a8d1c50ea54bd0a5ec27abe80d1c98e44a7f358ecf8f06615c174075100e72", "Callback-Timestamp": "2026-07-28T15:00:00.000Z", "Content-Type": "application/json" }, "secret": "greatwait-signature-vector-key-not-a-credential", "signingInputBase64": "MjAyNi0wNy0yOFQxNTowMDowMC4wMDBaLmRsdl8wMTIzNDU2Nzg5YWJjZGVmZ2hqa21ucHFycy57InZlcnNpb24iOiIyMDI2LTA4LTIzIiwidHlwZSI6InNjaGVkdWxlLm9jY3VycmVuY2UiLCJzY2hlZHVsZUlkIjoic2NoXzAxMjM0NTY3ODlhYmNkZWZnaGprbW5wcXJzIiwib2NjdXJyZW5jZUlkIjoib2NjXzAxMjM0NTY3ODlhYmNkZWZnaGprbW5wcXJzIiwicGxhbm5lZEZvciI6IjIwMjYtMDctMjhUMTU6MDA6MDAuMDAwWiIsImF0dGVtcHQiOjEsImNvbXBsZXRpb24iOnsidG9rZW4iOiJ2Mi5leGFtcGxlLWNsYWltLW5vdC1hLXJlYWwtdG9rZW4uZXhhbXBsZS1tYWMiLCJ1cmwiOiJodHRwczovL2dyZWF0d2FpdC1zY2hlZHVsZXIuZXhhbXBsZS9jYWxsYmFja3MvY29tcGxldGlvbiIsImRlYWRsaW5lIjoiMjAyNi0wNy0yOFQxNTowMDowNS4wMDBaIn0sInRyaWdnZXIiOnsia2luZCI6ImF1dG9tYXRpYyJ9LCJkYXRhIjp7Im5vdGUiOiJjYWbDqSDimIMifX0=", "signingInputUtf8": "2026-07-28T15:00:00.000Z.dlv_0123456789abcdefghjkmnpqrs.{\"version\":\"2026-08-23\",\"type\":\"schedule.occurrence\",\"scheduleId\":\"sch_0123456789abcdefghjkmnpqrs\",\"occurrenceId\":\"occ_0123456789abcdefghjkmnpqrs\",\"plannedFor\":\"2026-07-28T15:00:00.000Z\",\"attempt\":1,\"completion\":{\"token\":\"v2.example-claim-not-a-real-token.example-mac\",\"url\":\"https://greatwait-scheduler.example/callbacks/completion\",\"deadline\":\"2026-07-28T15:00:05.000Z\"},\"trigger\":{\"kind\":\"automatic\"},\"data\":{\"note\":\"café ☃\"}}" }, "version": "2026-08-23", "envelopeSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "oneOf": [ { "type": "object", "properties": { "attempt": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "data": {}, "occurrenceId": { "type": "string", "pattern": "^occ_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "plannedFor": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "scheduleId": { "type": "string", "pattern": "^sch_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "type": { "type": "string", "const": "schedule.occurrence" }, "version": { "type": "string", "const": "2026-07-01" } }, "required": [ "attempt", "data", "occurrenceId", "plannedFor", "scheduleId", "type", "version" ] }, { "type": "object", "properties": { "attempt": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "data": {}, "occurrenceId": { "type": "string", "pattern": "^occ_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "plannedFor": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "scheduleId": { "type": "string", "pattern": "^sch_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "type": { "type": "string", "const": "schedule.occurrence" }, "completion": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1 }, "url": { "type": "string", "format": "uri" } }, "required": ["token", "url"] }, "trigger": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "automatic" } }, "required": ["kind"] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "redelivery" }, "sourceAttemptId": { "type": "string", "pattern": "^att_[0-9abcdefghjkmnpqrstvwxyz]{26}$" } }, "required": ["kind", "sourceAttemptId"] } ] }, "version": { "type": "string", "const": "2026-08-08" } }, "required": [ "attempt", "data", "occurrenceId", "plannedFor", "scheduleId", "type", "trigger", "version" ] }, { "type": "object", "properties": { "attempt": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "data": {}, "occurrenceId": { "type": "string", "pattern": "^occ_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "plannedFor": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "scheduleId": { "type": "string", "pattern": "^sch_[0-9abcdefghjkmnpqrstvwxyz]{26}$" }, "type": { "type": "string", "const": "schedule.occurrence" }, "completion": { "type": "object", "properties": { "deadline": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "token": { "type": "string", "minLength": 1 }, "url": { "type": "string", "format": "uri" } }, "required": ["deadline", "token", "url"] }, "trigger": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "automatic" } }, "required": ["kind"] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "redelivery" }, "sourceAttemptId": { "type": "string", "pattern": "^att_[0-9abcdefghjkmnpqrstvwxyz]{26}$" } }, "required": ["kind", "sourceAttemptId"] } ] }, "version": { "type": "string", "const": "2026-08-23" } }, "required": [ "attempt", "data", "occurrenceId", "plannedFor", "scheduleId", "type", "completion", "trigger", "version" ] } ] } }, "x-greatwait-callback-receiver": { "idempotency": { "occurrence": { "identity": "Callback-Occurrence-Id", "note": "Every automatic delivery of one occurrence — the first attempt and every retry the system chose — is at most one execution. A receiver claims the occurrence atomically and answers 200 for every later automatic delivery of it. This is what makes at-least-once delivery safe; a receiver that needs a second execution asks for a second occurrence, or a person orders a redelivery.", "requirement": "claim the occurrence atomically before running the handler; release the claim if the handler fails so a later attempt can retry it" }, "redelivery": { "identity": "Callback-Occurrence-Id together with the signed attempt number, which is the redelivery's ordinal", "note": "A redelivery is a deliberate, authorized instruction to do the work again. Suppressing it as a duplicate answers a person with silence, which is what a customer pressing redeliver after fixing their endpoint experiences as the attempt succeeding while nothing happens.", "optOut": "A receiver that genuinely requires strict once-only per occurrence chooses it explicitly and keeps answering duplicate. It is an opt-out, not the default, because a default of suppression makes the product lie to the person who pressed the button.", "ordering": "attempt only ever increases within an occurrence and every copy of one redelivery carries the same value, so a receiver keeps the highest redelivery it has run to completion and refuses anything at or below it. That is what recognises a copy delayed in a proxy, a queue or an abandoned connection, however late it arrives and however many redeliveries have completed since. Remembering only the most recent instruction cannot do this and will run a customer's work twice; remembering every instruction can, at the cost of a store that grows without bound. sourceAttemptId names the attempt the person chose to follow and is there to show them, not to decide whether the work runs.", "requirement": "run the handler again for a redelivery whose attempt is above the highest this receiver has run to completion for the occurrence, and suppress every redelivery at or below that high-water mark", "strictness": "A receiver that chose strict once-only suppresses every delivery for an occurrence once anything has finished, whatever caused it. Reading strictness as a rule about redeliveries alone leaves a hole: a strict receiver that processed a redelivery first would then admit a delayed automatic delivery and run a payment twice.", "warranty": "Each accepted redelivery is one logical run. Repeats are suppressed once the receiver has durably completed that run — not from the moment it starts one. A handler that performs its external effect and then dies before its claim is settled will be run again when the lease expires, which is the honest limit of what any at-least-once receiver can promise. A customer whose effect must happen exactly once commits the occurrence and ordinal alongside their own state, or passes them downstream as an idempotency key." }, "replay": { "identity": "Callback-Delivery-Id", "requirement": "reject a previously accepted delivery identity before parsing, and answer 200 — a duplicated request is not a failure" } }, "claimRules": [ "another delivery holds an unexpired lease, whatever the run, so an ordered redelivery never runs alongside the attempt it follows -> in_flight", "the delivery may not retake a settled occurrence and anything at all has finished for it -> settled. This covers every automatic delivery and every delivery at a receiver that chose strict once-only", "the delivery is a redelivery whose ordinal is at or below the highest this receiver has run to completion -> settled", "otherwise take it, recording the holder and the run -> claimed" ], "order": [ "read the exact request bytes before any body parser sees them", "reject a body over the receiver's byte bound without buffering it", "validate the five Callback-* headers and the content type", "reject a timestamp outside tolerance", "select the signing key by Callback-Key-Id within the receiver's own endpoint, project, and environment", "compare the HMAC in constant time over .. plus the exact bytes", "compare the canonical envelope identifiers with the occurrence header", "claim the delivery identity atomically", "only now parse the body, and read the trigger that says why this delivery exists", "claim the occurrence identity atomically, for the run the signed body names — the occurrence for an automatic delivery, and the occurrence with the redelivery's attempt ordinal for one a person ordered", "run the application handler" ], "responses": { "body_too_large": 413, "duplicate": 200, "handler_failed": 500, "in_flight": 503, "invalid_envelope": 400, "invalid_headers": 401, "invalid_signature": 401, "processed": 200, "replay": 200, "stale_timestamp": 408 }, "sink": { "behaviors": { "client_error": { "defaultStatus": 422, "receiverActed": false, "senderOutcome": "terminal", "summary": "Answers a selected 4xx. The sender records a customer refusal, and retries it only when the status is one the receiver may recover from — 401, 403 and 404, listed as `clientErrorStatusesRetried`. The default, 422, is not one of those, so it settles on the first attempt." }, "defer_abandon": { "defaultStatus": 202, "deferredReport": "never", "receiverActed": true, "senderOutcome": "ambiguous", "summary": "Acknowledges the delivery and then never reports at all. The sender waits until the deadline in the envelope and records ambiguity, because a receiver that took the work and went quiet may well have done it. This is the case the completion deadline exists to bound." }, "defer_fail": { "defaultStatus": 202, "deferredReport": "failed", "receiverActed": true, "senderOutcome": "retryable", "summary": "Acknowledges the delivery, then reports `failed` with the credential in its signed envelope. The occurrence goes back on the ordinary retry ladder — the same place a 500 puts it — which is how a receiver says its job died rather than that it vanished." }, "defer_succeed": { "defaultStatus": 202, "deferredReport": "succeeded", "receiverActed": true, "senderOutcome": "success", "summary": "Acknowledges the delivery with 202 and the pending marker, keeps the work, then reports `succeeded` with the credential in its signed envelope. The whole deferred exchange, without writing a receiver." }, "delay": { "defaultStatus": 200, "receiverActed": true, "senderOutcome": "success", "summary": "Waits a bounded interval, then accepts. Exercises a slow receiver that still succeeds." }, "disconnect": { "receiverActed": false, "senderOutcome": "ambiguous", "summary": "Authenticates the delivery and then drops the connection without processing it, holding until the sender gives up. Nothing was claimed and nothing ran, but the sender cannot know that." }, "duplicate": { "defaultStatus": 200, "receiverActed": false, "senderOutcome": "success", "summary": "Accepts and reports the occurrence as already handled, without processing it again. What occurrence idempotency looks like from the sender's side." }, "invalid_signature": { "defaultStatus": 401, "receiverActed": false, "senderOutcome": "retryable", "summary": "Rejects the delivery as unauthenticated regardless of whether the signature verified. Exercises the key-mismatch path without forging a signature. The sender retries on the receiver's ordinary budget, because the usual cause is a credential the receiver is about to redeploy." }, "rate_limited": { "defaultStatus": 429, "receiverActed": false, "senderOutcome": "retryable", "summary": "Answers 429 with a bounded Retry-After. The sender honours the hint and does not spend its give-up budget." }, "server_error": { "defaultStatus": 503, "receiverActed": false, "senderOutcome": "retryable", "summary": "Answers a selected 5xx. The sender retries with backoff." }, "success": { "defaultStatus": 200, "receiverActed": true, "senderOutcome": "success", "summary": "Verifies, records, and accepts." }, "timeout": { "receiverActed": true, "senderOutcome": "ambiguous", "summary": "Verifies and records the delivery, then never answers. The receiver acted and the sender cannot know it." } }, "bounds": { "maxCompletionDelayMs": 5000, "maxDelayMs": 10000, "maxHoldMs": 45000, "maxRetainedDeliveries": 50, "maxSinksPerEnvironment": 10, "maxRequestBodyBytes": 69632, "maxRetainedBodyBytes": 4096 }, "clientErrorStatuses": [400, 401, 403, 404, 409, 410, 422], "clientErrorStatusesRetried": [401, 403, 404], "deferral": { "acknowledgement": "{\"greatwait\":{\"status\":\"pending\"}}", "note": "A deferring behavior answers this exact body with this status, then reports with the bearer credential from the delivery's own signed envelope — to the one completion address the stage is configured with, which the envelope's own URL must match. A delivery whose envelope carries no completion material, or names a different address, cannot defer, and the sink answers it as an ordinary success instead.", "status": 202 }, "egress": "A test sink has no destination field: no program, no control operation and no request header names anywhere for it to send. The one request it performs is a deferred-completion report for a delivery it has already received and authenticated, to the URL and credential carried inside that delivery's signed envelope. It cannot forward or redirect a delivery.", "visibility": "Test environments only. Organization, project, environment, and credential kind come from the verified principal; no request may widen them.", "programSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "behavior": { "type": "string", "enum": [ "client_error", "defer_abandon", "defer_fail", "defer_succeed", "delay", "disconnect", "duplicate", "invalid_signature", "rate_limited", "server_error", "success", "timeout" ] }, "completionDelayMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 5000 }, "delayMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 10000 }, "forDeliveries": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100 }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 300 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "then": { "type": "string", "enum": [ "client_error", "defer_abandon", "defer_fail", "defer_succeed", "delay", "disconnect", "duplicate", "invalid_signature", "rate_limited", "server_error", "success", "timeout" ] } }, "required": ["behavior"] } }, "version": "2026-08-23", "acknowledgementSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "disposition": { "type": "string", "enum": [ "body_too_large", "duplicate", "handler_failed", "in_flight", "invalid_envelope", "invalid_headers", "invalid_signature", "processed", "replay", "stale_timestamp" ] }, "occurrenceId": { "type": "string", "pattern": "^occ_[0-9abcdefghjkmnpqrstvwxyz]{26}$" } }, "required": ["disposition"] } } }