{ "openapi": "3.1.0", "info": { "title": "Editing Machine API", "version": "1.0.0", "description": "Public V1 surface for Editing Machine. All endpoints require an `Authorization: Bearer em_` header. Per-tier rate limits apply (free=5/min, lite=15/min, plus=30/min, pro=60/min); honour the `Retry-After` header on 429.", "contact": { "name": "Editing Machine API", "url": "https://editingmachine.app/main/api-docs" } }, "servers": [ { "url": "https://editingmachine.app/api/v1", "description": "Production" } ], "tags": [ { "name": "Projects", "description": "Editing project lifecycle." }, { "name": "API Keys", "description": "Mint and revoke API keys." }, { "name": "Webhooks", "description": "Project lifecycle webhooks." } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key", "description": "API key issued by Editing Machine. Format: `em_<64 hex chars>`." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } }, "paths": { "/projects": { "post": { "operationId": "createProject", "summary": "Create a new editing project from a published recipe.", "tags": [ "Projects" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "201": { "description": "Project created in draft status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string", "enum": [ "created" ] }, "recipe": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "purpose", "format", "brand", "channel" ] } }, "required": [ "name", "type" ] }, "credits_estimated": { "type": "integer", "description": "Credits that will be deducted on /execute." }, "price_quote": { "type": "object", "properties": { "quote_id": { "type": "string", "description": "Opaque signed quote. Submit to /execute." }, "credits": { "type": "integer", "description": "Credits that will be deducted on /execute." }, "fingerprint": { "type": "string", "description": "Deterministic hash of the pricing quartet." }, "expires_at": { "type": "string", "description": "ISO 8601 timestamp. Quote is rejected after this." } }, "required": [ "quote_id", "credits", "fingerprint", "expires_at" ], "description": "Signed price quote (Task #1513). Submit `quote_id` to /execute; the deduct path refuses if the pricing quartet on the row has drifted." }, "created_at": { "type": "string", "description": "ISO 8601 timestamp." } }, "required": [ "id", "status", "recipe", "credits_estimated", "price_quote", "created_at" ] } } } }, "400": { "description": "Invalid input or recipe has no published version.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Missing, malformed, expired, or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "API key lacks the required scope for this operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Recipe or brand not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Rate limit exceeded. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "recipe_id": { "type": "integer", "description": "ID of a published recipe.", "minimum": 0 }, "project_name": { "type": "string" }, "brand_id": { "type": "integer", "minimum": 0 }, "footage_source": { "type": "string", "enum": [ "client_upload", "smart_cloud_library", "director_sourced", "mixed" ] }, "script_brief": { "type": "object", "properties": { "audience": { "type": "string", "minLength": 1, "maxLength": 500 }, "goal": { "type": "string", "minLength": 1, "maxLength": 500 }, "keyMessage": { "type": "string", "maxLength": 1000 }, "tone": { "type": "string", "enum": [ "casual", "professional", "energetic", "cinematic", "other" ] }, "durationBucket": { "type": "string", "enum": [ "<30s", "30-90s", "2-5min", "5-15min", "long-form" ] }, "referenceLinks": { "type": "array", "items": { "type": "string", "maxLength": 500 }, "maxItems": 10 }, "notes": { "type": "string", "maxLength": 2000 } }, "required": [ "audience", "goal", "tone", "durationBucket" ] }, "repeat_pattern_confirmed": { "type": "boolean" }, "output_format": { "type": "string", "description": "Pricing quartet — output format (e.g. 'short-video', 'long-video', 'stitched-video').", "minLength": 1 }, "quality_tier": { "type": "string", "description": "Pricing quartet — quality tier (e.g. 'basic-cut', 'enhanced-edit', 'premium-quality').", "minLength": 1 }, "video_duration": { "type": "string", "description": "Pricing quartet — duration bucket (e.g. 'short', 'medium', 'long', 'feature').", "minLength": 1 }, "turnaround_time": { "type": "string", "description": "Pricing quartet — turnaround tier (e.g. 'relaxed', 'standard', 'rush').", "minLength": 1 } }, "required": [ "recipe_id", "footage_source", "output_format", "quality_tier", "video_duration", "turnaround_time" ] } } } }, "x-rate-limit-tier": "tier-based", "x-required-scopes": [ "projects:write" ] } }, "/projects/{id}/assets": { "post": { "operationId": "importProjectAsset", "summary": "Import an asset into a project from a remote URL.", "tags": [ "Projects" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "202": { "description": "Asset import accepted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "asset_id": { "type": "string" }, "filename": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "importing" ] }, "size_bytes": { "type": "integer", "nullable": true }, "url": { "type": "string", "format": "uri" } }, "required": [ "asset_id", "filename", "status", "size_bytes", "url" ] } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Missing, malformed, expired, or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "API key lacks the required scope for this operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Resource not found or not visible to this account.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Rate limit exceeded. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } } } }, "description": "Direct multipart uploads are not exposed on the public V1 surface — use the chunked upload API instead.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Editing project ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Remote URL to import as a project asset.", "format": "uri" } }, "required": [ "url" ] } } } }, "x-rate-limit-tier": "tier-based", "x-required-scopes": [ "projects:write" ] } }, "/projects/{id}/execute": { "post": { "operationId": "executeProject", "summary": "Move a draft project into the editing pipeline.", "tags": [ "Projects" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Project enqueued for editing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string", "enum": [ "queued" ] }, "credits_deducted": { "type": "integer" }, "credits_remaining": { "type": "integer" } }, "required": [ "id", "status", "credits_deducted", "credits_remaining" ] } } } }, "400": { "description": "Validation failed, missing `quote_id`, or `invalid_quote` (tampered / wrong project).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Missing, malformed, expired, or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "Insufficient credits to execute.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "API key lacks the required scope for this operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Resource not found or not visible to this account.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "409": { "description": "Project is not in a state that allows execution, or the signed price quote is stale (the pricing quartet on the row drifted between create and execute — request a new quote by recreating the project).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "410": { "description": "Signed price quote has expired. Recreate the project via POST /projects to receive a fresh quote.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Rate limit or concurrent-job limit exceeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } } } }, "description": "Deducts credits, enqueues Director orchestration, and dispatches a `project.started` webhook. Requires the signed `quote_id` returned by POST /projects (Task #1513) — the deduct path refuses if the pricing quartet on the row has drifted. Subject to per-tier concurrent-job limits.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Editing project ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "quote_id": { "type": "string", "description": "Opaque signed quote returned by POST /projects. Required (Task #1513). Tampered, expired, or stale quotes are rejected.", "minLength": 1 } }, "required": [ "quote_id" ] } } } }, "x-rate-limit-tier": "tier-based", "x-required-scopes": [ "projects:write" ] } }, "/projects/{id}": { "get": { "operationId": "getProject", "summary": "Get the public status of an editing project.", "tags": [ "Projects" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Project status snapshot.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string", "enum": [ "created", "processing", "complete", "revision" ] }, "progress_percent": { "type": "integer", "minimum": 0, "maximum": 100 }, "output_urls": { "type": "array", "items": { "type": "string", "format": "uri" } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "status", "progress_percent", "output_urls", "created_at", "updated_at" ] } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Missing, malformed, expired, or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "API key lacks the required scope for this operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Resource not found or not visible to this account.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Rate limit exceeded. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Editing project ID." } ], "x-rate-limit-tier": "tier-based", "x-required-scopes": [ "projects:read" ] } }, "/api-keys": { "post": { "operationId": "createApiKey", "summary": "Mint a new API key for the calling account.", "tags": [ "API Keys" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "201": { "description": "API key created. Raw key shown ONCE.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "key": { "type": "string", "description": "Full raw key. Shown ONCE." }, "prefix": { "type": "string" }, "created_at": { "type": "string" }, "message": { "type": "string" } }, "required": [ "id", "name", "key", "prefix", "created_at", "message" ] } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Missing, malformed, expired, or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "API key lacks the required scope for this operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Rate limit exceeded. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Human-readable label for the key.", "minLength": 1, "maxLength": 100 } }, "required": [ "name" ] } } } }, "x-rate-limit-tier": "burst-protected", "x-required-scopes": [ "api-keys:write" ] }, "get": { "operationId": "listApiKeys", "summary": "List API keys for the calling account (Academy keys excluded).", "tags": [ "API Keys" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "API keys (raw key never returned).", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "keyPrefix": { "type": "string" }, "lastUsedAt": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "revokedAt": { "type": "string", "nullable": true } }, "required": [ "id", "name", "keyPrefix", "lastUsedAt", "createdAt", "revokedAt" ] } } } } }, "401": { "description": "Missing, malformed, expired, or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "API key lacks the required scope for this operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Rate limit exceeded. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } } } }, "x-rate-limit-tier": "tier-based", "x-required-scopes": [ "api-keys:read" ] } }, "/api-keys/{id}": { "delete": { "operationId": "revokeApiKey", "summary": "Revoke an API key.", "tags": [ "API Keys" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "API key revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Missing, malformed, expired, or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Academy keys cannot be revoked through this endpoint.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Resource not found or not visible to this account.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Rate limit exceeded. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } } } }, "description": "Returns 403 if the target key carries an `academy:*` scope — Academy keys are managed out-of-band.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "x-rate-limit-tier": "burst-protected", "x-required-scopes": [ "api-keys:write" ] } }, "/webhooks": { "post": { "operationId": "createWebhook", "summary": "Register a webhook endpoint for project lifecycle events.", "tags": [ "Webhooks" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "201": { "description": "Webhook registered. HMAC secret shown ONCE.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "project.started", "project.completed", "project.failed", "director.message.posted", "project.awaiting_client_input" ] } }, "secret": { "type": "string", "description": "HMAC signing secret. Shown ONCE." }, "created_at": { "type": "string" }, "message": { "type": "string" } }, "required": [ "id", "url", "events", "secret", "created_at", "message" ] } } } }, "400": { "description": "Invalid webhook configuration or unreachable URL.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Missing, malformed, expired, or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "API key lacks the required scope for this operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Rate limit exceeded. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "HTTPS endpoint that will receive deliveries.", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "project.started", "project.completed", "project.failed", "director.message.posted", "project.awaiting_client_input" ] }, "description": "Events to subscribe to.", "minItems": 1 }, "description": { "type": "string" } }, "required": [ "url", "events" ] } } } }, "x-rate-limit-tier": "burst-protected", "x-required-scopes": [ "webhooks:write" ] }, "get": { "operationId": "listWebhooks", "summary": "List webhook endpoints for the calling account.", "tags": [ "Webhooks" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Webhook endpoints.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "project.started", "project.completed", "project.failed", "director.message.posted", "project.awaiting_client_input" ] } }, "isActive": { "type": "boolean" }, "lastDeliveredAt": { "type": "string", "nullable": true }, "createdAt": { "type": "string" } }, "required": [ "id", "url", "events", "isActive", "lastDeliveredAt", "createdAt" ] } } } } }, "401": { "description": "Missing, malformed, expired, or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "API key lacks the required scope for this operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Rate limit exceeded. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } } } }, "x-rate-limit-tier": "tier-based", "x-required-scopes": [ "webhooks:read" ] } }, "/webhooks/{id}": { "delete": { "operationId": "deactivateWebhook", "summary": "Deactivate a webhook endpoint.", "tags": [ "Webhooks" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Webhook deactivated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Missing, malformed, expired, or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "API key lacks the required scope for this operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Resource not found or not visible to this account.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Rate limit exceeded. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code (e.g. validation_error, unauthorized, forbidden, not_found, conflict, insufficient_credits, rate_limit_exceeded, concurrent_limit_exceeded, internal_error)." }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "retry_after": { "type": "integer" }, "balance": { "type": "integer" }, "required": { "type": "integer" }, "current_jobs": { "type": "integer" }, "limit": { "type": "integer" }, "current_status": { "type": "string" } }, "required": [ "error", "message" ] } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "x-rate-limit-tier": "burst-protected", "x-required-scopes": [ "webhooks:write" ] } } } }