{ "openapi": "3.1.0", "info": { "title": "ProteinIQ Public API", "version": "1.0.0", "description": "Run ProteinIQ tools and workflows, inspect jobs, stream status updates, and fetch results from code." }, "servers": [ { "url": "https://proteiniq.io" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "ProteinIQ API key" } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "resolution" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "resolution": { "type": "string", "description": "A short action the client can take to resolve or recover from the error" }, "details": {} } } } }, "Job": { "type": "object", "required": [ "id", "object", "project_id", "status", "tool", "created_at" ], "properties": { "id": { "type": "string" }, "object": { "const": "job" }, "project_id": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "tool": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "credits_used": { "type": "number" }, "created_at": { "type": "string", "format": "date-time" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "progress": { "type": [ "number", "null" ] }, "execution_time_seconds": { "type": [ "number", "null" ] }, "error": { "type": [ "string", "null" ] }, "billing": { "type": "object", "properties": { "mode": { "type": "string" }, "reserved_credits": { "type": [ "number", "null" ] }, "final_credits": { "type": [ "number", "null" ] }, "rate_credits_per_minute": { "type": [ "number", "null" ] }, "billable_runtime_seconds": { "type": [ "number", "null" ] }, "outcome": { "type": [ "string", "null" ] }, "finalized_at": { "type": [ "string", "null" ], "format": "date-time" }, "refund_credits": { "type": [ "number", "null" ] }, "refund_credits_applied_to_team": { "type": [ "number", "null" ] }, "refund_deferred_to_workflow_run": { "type": [ "boolean", "null" ] } } } } }, "InputSource": { "oneOf": [ { "type": "object", "required": [ "type" ], "properties": { "type": { "const": "text" } }, "additionalProperties": false }, { "type": "object", "required": [ "type" ], "properties": { "type": { "const": "file" }, "fileName": { "type": "string" }, "fileNames": { "type": "array", "items": { "type": "string" } }, "fileMimeType": { "type": "string" }, "file_id": { "type": "string", "minLength": 1 }, "fileId": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "externalSource", "externalId" ], "properties": { "type": { "const": "external" }, "externalSource": { "type": "string", "enum": [ "rcsb", "pubchem", "uniprot" ] }, "externalId": { "type": "string" } }, "additionalProperties": false } ] }, "SubmittedInput": { "type": "object", "required": [ "id", "slotId", "kind", "format", "source" ], "properties": { "id": { "type": "string" }, "slotId": { "type": "string" }, "kind": { "type": "string" }, "format": { "type": "string" }, "content": { "type": "string" }, "contentEncoding": { "type": "string", "enum": [ "utf8", "base64" ] }, "source": { "$ref": "#/components/schemas/InputSource" }, "label": { "type": "string" }, "copies": { "type": "integer", "minimum": 1, "maximum": 10 }, "cyclic": { "type": "boolean" }, "modifications": { "type": "array", "items": { "type": "object", "required": [ "position", "ccd" ], "properties": { "position": { "type": "integer", "minimum": 1 }, "ccd": { "type": "string", "minLength": 1, "maxLength": 8 } }, "additionalProperties": false } }, "msa": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string" }, "fileName": { "type": "string" }, "format": { "type": "string" } }, "additionalProperties": false }, "chainId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true } }, "anyOf": [ { "required": [ "content" ] }, { "properties": { "source": { "type": "object", "required": [ "type" ], "properties": { "type": { "const": "file" }, "file_id": { "type": "string", "minLength": 1 }, "fileId": { "type": "string", "minLength": 1 } }, "anyOf": [ { "required": [ "file_id" ] }, { "required": [ "fileId" ] } ] } } } ], "additionalProperties": false }, "JobInput": { "type": "object", "required": [ "inputs" ], "properties": { "inputs": { "type": "array", "items": { "$ref": "#/components/schemas/SubmittedInput" } } }, "additionalProperties": false }, "JobRequest": { "type": "object", "required": [ "tool", "name", "input" ], "properties": { "tool": { "type": "string" }, "name": { "type": "string" }, "max_quoted_credits": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Maximum fixed charge or initial runtime reservation accepted at submission. A higher current price returns price_changed (409). Use billing.max_reserved_credits for the total runtime reservation limit." }, "project_id": { "type": [ "string", "null" ] }, "input": { "$ref": "#/components/schemas/JobInput" }, "settings": { "type": "object", "additionalProperties": true }, "billing": { "type": "object", "properties": { "max_reserved_credits": { "type": "integer", "minimum": 1 }, "maxReservedCredits": { "type": "integer", "minimum": 1 } }, "additionalProperties": false } }, "additionalProperties": false }, "JobQuoteRequest": { "type": "object", "required": [ "tool", "input" ], "properties": { "tool": { "type": "string" }, "input": { "$ref": "#/components/schemas/JobInput" }, "settings": { "type": "object", "additionalProperties": true }, "billing": { "type": "object", "properties": { "max_reserved_credits": { "type": "integer", "minimum": 1 }, "maxReservedCredits": { "type": "integer", "minimum": 1 } }, "additionalProperties": false } }, "additionalProperties": false }, "ToolInputSlot": { "type": "object", "required": [ "id", "label", "capabilities" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "min": { "type": "integer" }, "max": { "type": "integer" }, "acceptedKinds": { "type": "array", "items": { "type": "string" } }, "defaultKind": { "type": "string" }, "capabilities": { "type": "object", "additionalProperties": true } }, "additionalProperties": true }, "Tool": { "type": "object", "required": [ "id", "object", "name", "input" ], "properties": { "id": { "type": "string" }, "object": { "const": "tool" }, "name": { "type": "string" }, "description": { "type": "string" }, "input": { "type": "object", "properties": { "slots": { "type": "array", "items": { "$ref": "#/components/schemas/ToolInputSlot" } } }, "additionalProperties": true } }, "additionalProperties": true }, "ToolSummary": { "type": "object", "required": [ "id", "object", "name", "description", "category", "tags", "credit_model" ], "properties": { "id": { "type": "string" }, "object": { "const": "tool" }, "name": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "credit_model": { "type": "object", "required": [ "is_free" ], "properties": { "is_free": { "type": "boolean" } } } } }, "Account": { "type": "object", "required": [ "object", "workspace", "limits", "api_key" ], "properties": { "object": { "const": "account" }, "workspace": { "type": "object", "required": [ "id", "plan", "credits" ], "properties": { "id": { "type": "string" }, "plan": { "type": "object", "required": [ "tier", "paid" ], "properties": { "tier": { "type": "string" }, "paid": { "type": "boolean" } } }, "credits": { "type": "object", "required": [ "available" ], "properties": { "available": { "type": "number" } } } } }, "limits": { "type": "object", "required": [ "active_jobs", "concurrent_jobs", "public_api_rate_limit" ], "properties": { "active_jobs": { "type": "integer" }, "concurrent_jobs": { "type": "object", "required": [ "max", "remaining" ], "properties": { "max": { "type": "integer" }, "remaining": { "type": "integer" } } }, "public_api_rate_limit": { "type": "object", "required": [ "limit", "window_seconds" ], "properties": { "limit": { "type": "integer" }, "window_seconds": { "type": "integer" } } } } }, "api_key": { "type": "object", "required": [ "id", "env", "prefix", "scopes" ], "properties": { "id": { "type": "string" }, "env": { "type": "string" }, "prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } } } } } }, "List": { "type": "object", "required": [ "object", "data", "has_more", "next_cursor" ], "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": {} }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "ToolList": { "type": "object", "required": [ "object", "data", "has_more", "next_cursor" ], "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ToolSummary" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "JobList": { "type": "object", "required": [ "object", "data", "has_more", "next_cursor" ], "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Job" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "JobQuote": { "type": "object", "required": [ "object", "tool", "estimated_credits", "available_credits", "billable_credits", "blocking_errors", "limits", "billing" ], "properties": { "object": { "const": "job_quote" }, "tool": { "type": "string" }, "estimated_credits": { "type": "number" }, "available_credits": { "type": "number" }, "billable_credits": { "type": "number" }, "blocking_errors": { "type": "array", "items": {} }, "limits": { "type": "object", "required": [ "active_concurrent_jobs", "max_concurrent_jobs", "daily_limit_used", "daily_limit_max" ], "properties": { "active_concurrent_jobs": { "type": "integer" }, "max_concurrent_jobs": { "type": "integer" }, "daily_limit_used": { "type": [ "integer", "null" ] }, "daily_limit_max": { "type": [ "integer", "null" ] } } }, "billing": { "oneOf": [ { "type": "object", "required": [ "mode" ], "properties": { "mode": { "const": "fixed" } } }, { "type": "object", "required": [ "mode", "reserved_credits", "estimated_credits", "rate_credits_per_minute", "max_billable_runtime_seconds" ], "properties": { "mode": { "const": "metered_runtime" }, "reserved_credits": { "type": "number" }, "estimated_credits": { "type": "number" }, "rate_credits_per_minute": { "type": "number" }, "max_billable_runtime_seconds": { "type": "number" } } } ] } } }, "JobCancellation": { "type": "object", "required": [ "object", "refunded", "job" ], "properties": { "object": { "const": "job_cancellation" }, "refunded": { "type": "boolean" }, "job": { "$ref": "#/components/schemas/Job" } } }, "JobRetry": { "type": "object", "required": [ "object", "job" ], "properties": { "object": { "const": "job_retry" }, "job": { "$ref": "#/components/schemas/Job" } } }, "JobShare": { "type": "object", "required": [ "id", "object", "email", "claimed", "claimed_at", "invitee_name", "created_at" ], "properties": { "id": { "type": "string" }, "object": { "const": "job_share" }, "email": { "type": "string", "format": "email" }, "claimed": { "type": "boolean" }, "claimed_at": { "type": [ "string", "null" ], "format": "date-time" }, "invitee_name": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "JobSharing": { "type": "object", "required": [ "object", "job_id", "visibility", "shares" ], "properties": { "object": { "const": "job_sharing" }, "job_id": { "type": "string" }, "visibility": { "type": "string", "enum": [ "PRIVATE", "PUBLIC", "AUTHENTICATED", "INVITED" ] }, "shares": { "type": "array", "items": { "$ref": "#/components/schemas/JobShare" } } } }, "JobSharingRequest": { "type": "object", "properties": { "visibility": { "type": "string", "enum": [ "PRIVATE", "PUBLIC", "AUTHENTICATED", "INVITED" ] }, "add_invites": { "type": "array", "items": { "type": "string", "format": "email" }, "maxItems": 100 }, "addInvites": { "type": "array", "items": { "type": "string", "format": "email" }, "maxItems": 100 }, "remove_invites": { "type": "array", "items": { "type": "string", "format": "email" }, "maxItems": 100 }, "removeInvites": { "type": "array", "items": { "type": "string", "format": "email" }, "maxItems": 100 } }, "additionalProperties": false }, "JobResultFile": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "output_port_id": { "type": "string" }, "order": { "type": "integer", "minimum": 0 }, "rank": { "type": [ "integer", "null" ], "minimum": 1 }, "source_input_ids": { "type": "array", "items": { "type": "string" } }, "size": { "type": "number" }, "content_type": { "type": "string" }, "url": { "type": "string", "format": "uri" } }, "additionalProperties": true }, "JobResult": { "type": "object", "required": [ "object", "job_id", "tool", "status", "completed_at", "data_source", "files", "results" ], "properties": { "object": { "const": "job_result" }, "job_id": { "type": "string" }, "tool": { "type": "string" }, "status": { "type": "string" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "data_source": { "type": "string", "enum": [ "result-manifest-v2", "result-manifest-v1", "legacy-r2" ] }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/JobResultFile" } }, "results": {} }, "oneOf": [ { "required": [ "data_source", "results" ], "properties": { "data_source": { "const": "result-manifest-v2" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/JobResultStructuredItem" } } } }, { "required": [ "data_source" ], "properties": { "data_source": { "type": "string", "enum": [ "result-manifest-v1", "legacy-r2" ] } } } ] }, "JobResultStructuredItem": { "type": "object", "required": [ "id", "output_port_id", "order", "rank", "file_name", "source_input_ids", "format", "value" ], "properties": { "id": { "type": "string" }, "output_port_id": { "type": "string" }, "order": { "type": "integer", "minimum": 0 }, "rank": { "type": [ "integer", "null" ], "minimum": 1 }, "file_name": { "type": [ "string", "null" ] }, "source_input_ids": { "type": "array", "items": { "type": "string" } }, "format": { "type": "string" }, "value": {} }, "additionalProperties": false }, "OpenAPIContract": { "type": "object", "required": [ "openapi", "info", "paths" ], "additionalProperties": true }, "File": { "type": "object", "required": [ "id", "object", "project_id", "filename", "original_name", "format", "mime_type", "size", "origin", "storage_owner", "created_at", "input_reference" ], "properties": { "id": { "type": "string" }, "object": { "const": "file" }, "project_id": { "type": [ "string", "null" ] }, "filename": { "type": "string" }, "original_name": { "type": "string" }, "format": { "type": "string" }, "mime_type": { "type": "string" }, "size": { "type": "integer" }, "origin": { "type": "string", "enum": [ "UPLOAD", "JOB_OUTPUT", "JOB_INPUT", "IMPORT" ] }, "storage_owner": { "type": "string", "enum": [ "FILE_LIBRARY", "JOB_ARTIFACT" ] }, "preview_kind": { "type": [ "string", "null" ], "enum": [ "text", "structure", "image", "binary", null ] }, "job_id": { "type": [ "string", "null" ] }, "job_name": { "type": [ "string", "null" ] }, "job_type": { "type": [ "string", "null" ] }, "tool": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "description": { "type": [ "string", "null" ] }, "collection_ids": { "type": "array", "items": { "type": "string" } }, "collections": { "type": "array", "items": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "content_url": { "type": "string" }, "download_url": { "type": "string" }, "input_reference": { "type": "object", "required": [ "type", "file_id" ], "properties": { "type": { "const": "file" }, "file_id": { "type": "string" } } } } }, "FileList": { "type": "object", "required": [ "object", "data", "has_more", "next_cursor" ], "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/File" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "FileDeletion": { "type": "object", "required": [ "object", "id", "deleted" ], "properties": { "object": { "const": "file_deletion" }, "id": { "type": "string" }, "deleted": { "type": "boolean" } } }, "Project": { "type": "object", "required": [ "id", "object", "name", "description", "counts", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "object": { "const": "project" }, "name": { "type": "string" }, "description": { "type": ["string", "null"] }, "counts": { "type": "object", "required": [ "jobs", "files", "workflows", "workflow_runs", "studio_sessions", "ai_conversations" ], "properties": { "jobs": { "type": "integer" }, "files": { "type": "integer" }, "workflows": { "type": "integer" }, "workflow_runs": { "type": "integer" }, "studio_sessions": { "type": "integer" }, "ai_conversations": { "type": "integer" } }, "additionalProperties": false }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "ProjectList": { "type": "object", "required": ["object", "data", "has_more", "next_cursor"], "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": ["string", "null"] } }, "additionalProperties": false }, "ProjectCreateRequest": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "description": { "type": ["string", "null"], "maxLength": 500 } }, "additionalProperties": false }, "ProjectUpdateRequest": { "type": "object", "minProperties": 1, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "description": { "type": ["string", "null"], "maxLength": 500 } }, "additionalProperties": false }, "ProjectAssignmentRequest": { "type": "object", "required": ["target_project_id", "resources"], "properties": { "target_project_id": { "type": ["string", "null"] }, "resources": { "type": "array", "minItems": 1, "maxItems": 6, "items": { "type": "object", "required": ["type", "ids"], "properties": { "type": { "type": "string", "enum": [ "job", "file", "workflow", "workflow_run", "studio_session", "ai_conversation" ] }, "ids": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "type": "string" } } }, "additionalProperties": false } }, "move_linked_files": { "type": "boolean", "default": false } }, "additionalProperties": false }, "ProjectAssignment": { "type": "object", "required": [ "object", "target_project", "counts", "linked_file_count" ], "properties": { "object": { "const": "project_assignment" }, "target_project": { "oneOf": [ { "type": "object", "required": ["id", "name"], "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "additionalProperties": false }, { "type": "null" } ] }, "counts": { "type": "object", "required": [ "jobs", "files", "workflows", "workflow_runs", "studio_sessions", "ai_conversations" ], "properties": { "jobs": { "type": "integer" }, "files": { "type": "integer" }, "workflows": { "type": "integer" }, "workflow_runs": { "type": "integer" }, "studio_sessions": { "type": "integer" }, "ai_conversations": { "type": "integer" } }, "additionalProperties": false }, "linked_file_count": { "type": "integer" } }, "additionalProperties": false }, "ProjectDeletionRequest": { "type": "object", "required": ["mode"], "properties": { "mode": { "type": "string", "enum": ["move", "unassign", "delete_contents"] }, "target_project_id": { "type": "string" } }, "additionalProperties": false }, "ProjectDeletion": { "type": "object", "required": [ "id", "object", "project_id", "project_name", "mode", "target_project_id", "status", "error", "attempt_count", "next_attempt_at", "retryable", "created_at", "started_at", "completed_at", "updated_at" ], "properties": { "id": { "type": "string" }, "object": { "const": "project_deletion" }, "project_id": { "type": ["string", "null"] }, "project_name": { "type": "string" }, "mode": { "type": "string", "enum": ["move", "unassign", "delete_contents"] }, "target_project_id": { "type": ["string", "null"] }, "status": { "type": "string", "enum": ["pending", "processing", "completed", "failed"] }, "error": { "type": ["string", "null"] }, "attempt_count": { "type": "integer", "minimum": 0 }, "next_attempt_at": { "type": ["string", "null"], "format": "date-time" }, "retryable": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "started_at": { "type": ["string", "null"], "format": "date-time" }, "completed_at": { "type": ["string", "null"], "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false } }, "responses": { "ErrorResponse": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "paths": { "/api/v1/account": { "get": { "security": [ { "bearerAuth": [] } ], "summary": "Inspect API workspace credits, limits, and key metadata", "responses": { "200": { "description": "Account summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } } }, "401": { "description": "Invalid API key" }, "default": { "$ref": "#/components/responses/ErrorResponse" } }, "operationId": "getAccount" } }, "/api/v1/tools": { "get": { "security": [ { "bearerAuth": [] } ], "summary": "List tools", "responses": { "200": { "description": "Tool list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolList" } } } }, "default": { "$ref": "#/components/responses/ErrorResponse" } }, "operationId": "listTools" } }, "/api/v1/tools/{toolId}": { "get": { "security": [ { "bearerAuth": [] } ], "summary": "Describe a tool", "parameters": [ { "name": "toolId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Tool detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tool" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "$ref": "#/components/responses/ErrorResponse" } }, "operationId": "getTool" } }, "/api/v1/jobs": { "get": { "security": [ { "bearerAuth": [] } ], "summary": "List jobs", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "starting_after", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "project_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "unassigned", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Job list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobList" } } } }, "default": { "$ref": "#/components/responses/ErrorResponse" } }, "operationId": "listJobs" }, "post": { "security": [ { "bearerAuth": [] } ], "summary": "Submit a job", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobRequest" }, "example": { "tool": "esmfold", "name": "Lysozyme ESMFold run", "input": { "inputs": [ { "id": "seqs_1", "slotId": "protein", "kind": "protein", "format": "fasta", "content": ">seq\nMKT", "source": { "type": "text" } } ] }, "settings": {} } } } }, "responses": { "202": { "description": "Job accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "default": { "$ref": "#/components/responses/ErrorResponse" } }, "operationId": "submitJob" } }, "/api/v1/jobs/quote": { "post": { "security": [ { "bearerAuth": [] } ], "summary": "Validate input and estimate credits without creating a job", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobQuoteRequest" }, "example": { "tool": "esmfold", "input": { "inputs": [ { "id": "seqs_1", "slotId": "protein", "kind": "protein", "format": "fasta", "content": ">seq\nMKT", "source": { "type": "text" } } ] }, "settings": {} } } } }, "responses": { "200": { "description": "Job quote", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobQuote" } } } }, "default": { "$ref": "#/components/responses/ErrorResponse" } }, "operationId": "quoteJob" } }, "/api/v1/jobs/{jobId}/status": { "get": { "security": [ { "bearerAuth": [] } ], "summary": "Poll job status", "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Job status", "headers": { "Retry-After": { "description": "Suggested seconds to wait before polling this job again.", "schema": { "type": "integer", "examples": [ 5, 300 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "429": { "description": "Status polling was too frequent for this job", "headers": { "Retry-After": { "description": "Seconds to wait before polling this job again.", "schema": { "type": "integer", "example": 5 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "$ref": "#/components/responses/ErrorResponse" } }, "operationId": "getJobStatus" } }, "/api/v1/jobs/{jobId}/share": { "get": { "security": [ { "bearerAuth": [] } ], "summary": "Get job sharing settings", "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Job sharing settings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobSharing" } } } }, "default": { "$ref": "#/components/responses/ErrorResponse" } }, "operationId": "getJobSharing" }, "patch": { "security": [ { "bearerAuth": [] } ], "summary": "Update job sharing settings", "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobSharingRequest" }, "example": { "visibility": "INVITED", "add_invites": [ "collaborator@example.com" ], "remove_invites": [ "old-collaborator@example.com" ] } } } }, "responses": { "200": { "description": "Updated job sharing settings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobSharing" } } } }, "default": { "$ref": "#/components/responses/ErrorResponse" } }, "operationId": "updateJobSharing" } }, "/api/v1/jobs/{jobId}/events": { "get": { "security": [ { "bearerAuth": [] } ], "summary": "Stream job status events", "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Server-sent status event stream", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/ErrorResponse" } }, "operationId": "streamJobEvents" } }, "/api/v1/jobs/{jobId}/cancel": { "post": { "security": [ { "bearerAuth": [] } ], "summary": "Cancel a queued job", "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Cancellation result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobCancellation" } } } }, "default": { "$ref": "#/components/responses/ErrorResponse" } }, "operationId": "cancelJob" } }, "/api/v1/jobs/{jobId}/retry": { "post": { "security": [ { "bearerAuth": [] } ], "summary": "Retry a pending dispatch attempt", "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Retry result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobRetry" } } } }, "default": { "$ref": "#/components/responses/ErrorResponse" } }, "operationId": "retryJob" } }, "/api/v1/results/{jobId}": { "get": { "security": [ { "bearerAuth": [] } ], "summary": "Fetch completed job results", "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Job result manifest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResult" } } } }, "409": { "description": "Job results are not ready yet", "headers": { "Retry-After": { "description": "Suggested seconds to wait before retrying result fetch.", "schema": { "type": "integer", "example": 5 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Result polling was too frequent for this job", "headers": { "Retry-After": { "description": "Seconds to wait before fetching this job result again.", "schema": { "type": "integer", "example": 5 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "$ref": "#/components/responses/ErrorResponse" } }, "operationId": "getJobResult" } }, "/api/v1/results/{jobId}/items/{itemId}": { "get": { "security": [ { "bearerAuth": [] } ], "summary": "Download a manifest-owned result artifact", "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Result artifact bytes", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "default": { "$ref": "#/components/responses/ErrorResponse" } }, "operationId": "downloadJobResultItem" } }, "/api/v1/openapi.json": { "get": { "summary": "Fetch the OpenAPI contract", "responses": { "200": { "description": "OpenAPI 3.1 contract", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAPIContract" } } } } }, "operationId": "getOpenAPIContract" } }, "/api/v1/files": { "get": { "security": [ { "bearerAuth": [] } ], "summary": "List saved workspace files", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "starting_after", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "origin", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "UPLOAD", "JOB_OUTPUT", "JOB_INPUT", "IMPORT" ] } }, { "name": "collection_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "project_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "unassigned", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "mine", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "File list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileList" } } } }, "default": { "$ref": "#/components/responses/ErrorResponse" } }, "operationId": "listFiles" }, "post": { "security": [ { "bearerAuth": [] } ], "summary": "Upload a saved workspace file", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" }, "description": { "type": "string" }, "tags": { "type": "string" }, "collection_ids": { "type": "string" }, "project_id": { "type": "string" } } } } } }, "responses": { "201": { "description": "Uploaded file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" } } } }, "default": { "$ref": "#/components/responses/ErrorResponse" } }, "operationId": "uploadFile" } }, "/api/v1/files/{fileId}": { "get": { "security": [ { "bearerAuth": [] } ], "summary": "Get saved file metadata", "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "File resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" } } } }, "default": { "$ref": "#/components/responses/ErrorResponse" } }, "operationId": "getFile" }, "delete": { "security": [ { "bearerAuth": [] } ], "summary": "Delete a saved workspace file", "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "File deletion result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileDeletion" } } } }, "default": { "$ref": "#/components/responses/ErrorResponse" } }, "operationId": "deleteFile" } }, "/api/v1/projects": { "get": { "security": [{ "bearerAuth": [] }], "summary": "List active workspace projects", "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "starting_after", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Project list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectList" } } } }, "default": { "$ref": "#/components/responses/ErrorResponse" } }, "operationId": "listProjects" }, "post": { "security": [{ "bearerAuth": [] }], "summary": "Create a workspace project", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectCreateRequest" } } } }, "responses": { "201": { "description": "Project created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "default": { "$ref": "#/components/responses/ErrorResponse" } }, "operationId": "createProject" } }, "/api/v1/projects/{projectId}": { "get": { "security": [{ "bearerAuth": [] }], "summary": "Get a project", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Project resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "default": { "$ref": "#/components/responses/ErrorResponse" } }, "operationId": "getProject" }, "patch": { "security": [{ "bearerAuth": [] }], "summary": "Update a project", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectUpdateRequest" } } } }, "responses": { "200": { "description": "Project updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "default": { "$ref": "#/components/responses/ErrorResponse" } }, "operationId": "updateProject" }, "delete": { "security": [{ "bearerAuth": [] }], "summary": "Delete a project and choose how to handle its contents", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectDeletionRequest" } } } }, "responses": { "202": { "description": "Project deletion accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectDeletion" } } } }, "default": { "$ref": "#/components/responses/ErrorResponse" } }, "operationId": "deleteProject" } }, "/api/v1/projects/assignments": { "patch": { "security": [{ "bearerAuth": [] }], "summary": "Move project resources", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectAssignmentRequest" } } } }, "responses": { "200": { "description": "Project assignment result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectAssignment" } } } }, "default": { "$ref": "#/components/responses/ErrorResponse" } }, "operationId": "assignProjectResources" } }, "/api/v1/project-deletions/{operationId}": { "get": { "security": [{ "bearerAuth": [] }], "summary": "Get a project deletion operation", "parameters": [ { "name": "operationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Project deletion operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectDeletion" } } } }, "default": { "$ref": "#/components/responses/ErrorResponse" } }, "operationId": "getProjectDeletion" }, "post": { "security": [{ "bearerAuth": [] }], "summary": "Retry a recoverable project deletion operation", "parameters": [ { "name": "operationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Project deletion retry accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectDeletion" } } } }, "default": { "$ref": "#/components/responses/ErrorResponse" } }, "operationId": "retryProjectDeletion" } }, "/api/v1/workflows": { "get": { "security": [{ "bearerAuth": [] }], "summary": "List accessible published workflows", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "starting_after", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "project_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "unassigned", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Workflow list", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/ErrorResponse" } }, "operationId": "listWorkflows" } }, "/api/v1/workflows/{workflowId}": { "get": { "security": [{ "bearerAuth": [] }], "summary": "Get a published workflow", "parameters": [ { "name": "workflowId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Workflow resource", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/ErrorResponse" } }, "operationId": "getWorkflow" } }, "/api/v1/workflows/{workflowId}/validate": { "post": { "security": [{ "bearerAuth": [] }], "summary": "Validate an editable workflow draft", "parameters": [ { "name": "workflowId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["definition"], "properties": { "definition": { "type": "object", "additionalProperties": true }, "settings": { "type": "object", "additionalProperties": true } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Workflow validation result", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/ErrorResponse" } }, "operationId": "validateWorkflow" } }, "/api/v1/workflows/{workflowId}/runs": { "post": { "security": [{ "bearerAuth": [] }], "summary": "Start a published workflow run", "parameters": [ { "name": "workflowId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["input_data"], "properties": { "name": { "type": "string" }, "project_id": { "type": ["string", "null"] }, "input_data": { "type": "object", "additionalProperties": true } }, "additionalProperties": false } } } }, "responses": { "202": { "description": "Workflow run accepted", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/ErrorResponse" } }, "operationId": "startWorkflowRun" } }, "/api/v1/workflow-runs/{runId}": { "get": { "security": [{ "bearerAuth": [] }], "summary": "Get workflow run status", "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Workflow run resource", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/ErrorResponse" } }, "operationId": "getWorkflowRun" } }, "/api/v1/workflow-runs/{runId}/results": { "get": { "security": [{ "bearerAuth": [] }], "summary": "Get workflow run result metadata", "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Workflow run results", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/ErrorResponse" } }, "operationId": "getWorkflowRunResults" } }, "/api/v1/workflow-runs/{runId}/curation": { "get": { "security": [{ "bearerAuth": [] }], "summary": "Get a workflow curation checkpoint", "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Curation checkpoint and candidates", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/ErrorResponse" } }, "operationId": "getWorkflowCuration" }, "post": { "security": [{ "bearerAuth": [] }], "summary": "Record a workflow curation decision", "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["candidate_set_digest", "approved_candidate_ids"], "properties": { "candidate_set_digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }, "approved_candidate_ids": { "type": "array", "minItems": 1, "maxItems": 10000, "items": { "type": "string", "pattern": "^wca_[0-9a-f]{64}$" } }, "note": { "type": "string", "maxLength": 2000 }, "criteria": { "type": "object", "additionalProperties": true } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Curation decision recorded", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/ErrorResponse" } }, "operationId": "recordWorkflowCuration" } }, "/api/v1/workflow-runs/{runId}/continue": { "post": { "security": [{ "bearerAuth": [] }], "summary": "Continue a paused workflow run", "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Workflow continuation accepted", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/ErrorResponse" } }, "operationId": "continueWorkflowRun" } }, "/api/v1/workflow-runs/{runId}/cancel": { "post": { "security": [{ "bearerAuth": [] }], "summary": "Cancel a workflow run", "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Workflow cancellation and credit accounting", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/ErrorResponse" } }, "operationId": "cancelWorkflowRun" } }, "/api/v1/workflow-runs/{runId}/retry": { "post": { "security": [{ "bearerAuth": [] }], "summary": "Retry a workflow run", "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["mode"], "properties": { "mode": { "type": "string", "enum": ["from_start", "from_failed_node"] }, "node_id": { "type": "string" } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Workflow retry attempt created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/ErrorResponse" } }, "operationId": "retryWorkflowRun" } } } }