{
  "openapi": "3.1.0",
  "info": {
    "title": "Orchestrion",
    "version": "1.0.0",
    "description": "Agent-native task orchestration API. Provides task lifecycle management with lease-based ownership, retry logic, and machine-readable recovery guidance (agent_contract) on every response."
  },
  "servers": [
    {
      "url": "/",
      "description": "Relative to deployment host"
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key in orch_live_{64 hex chars} format. Obtain via POST /v1/keys/register. Keys in query strings are rejected."
      }
    },
    "schemas": {
      "Task": {
        "type": "object",
        "description": "A task resource as returned by all task endpoints.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Task ID in tsk_{ulid} format.",
            "example": "tsk_01JXZK..."
          },
          "type": {
            "type": "string",
            "description": "Task routing key.",
            "maxLength": 100,
            "pattern": "^[a-zA-Z0-9_-]+$"
          },
          "payload": {
            "type": "object",
            "description": "Task input data (JSONB). Immutable after creation."
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "claimed",
              "completed",
              "dead_letter",
              "cancelled"
            ],
            "description": "Current task lifecycle state."
          },
          "priority": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "description": "Higher priority is claimed first."
          },
          "scheduledAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "ISO 8601. NULL = immediately claimable."
          },
          "attemptCount": {
            "type": "integer",
            "minimum": 0,
            "description": "Incremented on each claim. Reset to 0 on requeue."
          },
          "maxAttempts": {
            "type": "integer",
            "minimum": 1,
            "maximum": 10,
            "description": "Maximum claim attempts before dead-lettering."
          },
          "leaseDurationSeconds": {
            "type": "integer",
            "minimum": 30,
            "maximum": 3600,
            "description": "Lease duration per claim attempt."
          },
          "claimedBy": {
            "type": [
              "string",
              "null"
            ],
            "description": "Worker identity (observability only, not used for auth)."
          },
          "claimedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When current claim attempt began."
          },
          "leaseExpiresAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Hard deadline for current lease."
          },
          "lastHeartbeatAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Last successful heartbeat timestamp."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "Task creation timestamp."
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Last state change timestamp."
          },
          "completedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When task transitioned to completed."
          },
          "lastFailedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Most recent fail transition timestamp."
          },
          "lastFailureReason": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 500,
            "description": "Worker-provided failure reason."
          },
          "result": {
            "type": [
              "object",
              "null"
            ],
            "description": "Inline structured result (set on /complete)."
          },
          "outputId": {
            "type": [
              "string",
              "null"
            ],
            "description": "OutputLayer artifact reference (set on /complete)."
          }
        },
        "required": [
          "id",
          "type",
          "payload",
          "status",
          "priority",
          "scheduledAt",
          "attemptCount",
          "maxAttempts",
          "leaseDurationSeconds",
          "claimedBy",
          "claimedAt",
          "leaseExpiresAt",
          "lastHeartbeatAt",
          "createdAt",
          "updatedAt",
          "completedAt",
          "lastFailedAt",
          "lastFailureReason",
          "result",
          "outputId"
        ]
      },
      "AgentContract": {
        "type": "object",
        "description": "Machine-readable recovery guidance included in every response. Agents should read next_actions to determine what to do next.",
        "properties": {
          "version": {
            "type": "string",
            "const": "1",
            "description": "Contract version. Always \"1\" for V1 API."
          },
          "retryable": {
            "type": "boolean",
            "description": "Whether the same request can be retried."
          },
          "next_actions": {
            "type": "array",
            "description": "Ordered list of recommended actions. Exactly one has recommended: true.",
            "items": {
              "$ref": "#/components/schemas/Action"
            }
          },
          "task_claimable": {
            "type": "boolean",
            "description": "Present on claim responses only. true = task returned, false = queue empty."
          },
          "lease_valid": {
            "type": "boolean",
            "description": "Present when task status is \"claimed\". true = lease is active."
          },
          "lease_expires_in_seconds": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Present when task is \"claimed\". Seconds until lease expires."
          },
          "recommended_heartbeat_interval_seconds": {
            "type": "integer",
            "description": "Present when task is \"claimed\" with an active lease. Recommended heartbeat interval (lease_duration / 3)."
          }
        },
        "required": [
          "version",
          "retryable",
          "next_actions"
        ]
      },
      "Action": {
        "type": "object",
        "description": "A single recommended action within an agent_contract.",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "create_task",
              "claim_task",
              "complete_task",
              "fail_task",
              "heartbeat",
              "check_task_status",
              "requeue_task",
              "retry_after_wait",
              "authenticate",
              "fix_request",
              "download_artifact",
              "list_tasks",
              "upgrade_plan",
              "renew_plan",
              "check_billing_status",
              "verify_payment",
              "retry_checkout"
            ],
            "description": "Stable action code."
          },
          "available": {
            "type": "boolean",
            "description": "Whether this action is currently possible."
          },
          "recommended": {
            "type": "boolean",
            "description": "Whether this is the recommended next step."
          },
          "description": {
            "type": "string",
            "description": "Human-readable description."
          },
          "method": {
            "type": "string",
            "enum": [
              "GET",
              "POST"
            ],
            "description": "HTTP method (when action targets an endpoint)."
          },
          "endpoint": {
            "type": "string",
            "description": "API endpoint path (when action targets an endpoint)."
          },
          "retry_after_seconds": {
            "type": "integer",
            "description": "Advisory wait time before retrying."
          }
        },
        "required": [
          "action",
          "available",
          "recommended"
        ]
      },
      "ErrorResponse": {
        "type": "object",
        "description": "Standard error response shape for all error cases.",
        "properties": {
          "error": {
            "type": "string",
            "enum": [
              "missing_api_key",
              "invalid_api_key",
              "invalid_request",
              "task_not_found",
              "invalid_transition",
              "lease_expired",
              "task_currently_claimed",
              "not_yet_claimable",
              "idempotency_conflict",
              "idempotency_in_flight",
              "quota_exceeded",
              "plan_expired",
              "max_workers_reached",
              "payment_failed",
              "rate_limited",
              "server_error"
            ],
            "description": "Stable error code."
          },
          "message": {
            "type": "string",
            "description": "Human-readable error description."
          },
          "request_id": {
            "type": "string",
            "description": "Correlation ID for this request."
          },
          "agent_contract": {
            "$ref": "#/components/schemas/AgentContract"
          }
        },
        "required": [
          "error",
          "message",
          "request_id",
          "agent_contract"
        ]
      },
      "TaskWithContract": {
        "type": "object",
        "description": "Task resource with agent_contract (returned by most task endpoints).",
        "allOf": [
          {
            "$ref": "#/components/schemas/Task"
          },
          {
            "type": "object",
            "properties": {
              "agent_contract": {
                "$ref": "#/components/schemas/AgentContract"
              }
            },
            "required": [
              "agent_contract"
            ]
          }
        ]
      },
      "ClaimSuccessResponse": {
        "type": "object",
        "description": "Successful claim response wrapping the task.",
        "properties": {
          "task": {
            "$ref": "#/components/schemas/Task"
          },
          "agent_contract": {
            "$ref": "#/components/schemas/AgentContract"
          }
        },
        "required": [
          "task",
          "agent_contract"
        ]
      },
      "ClaimEmptyResponse": {
        "type": "object",
        "description": "Claim response when no tasks of the requested type are available.",
        "properties": {
          "task": {
            "type": "null"
          },
          "agent_contract": {
            "$ref": "#/components/schemas/AgentContract"
          }
        },
        "required": [
          "task",
          "agent_contract"
        ]
      },
      "PageInfo": {
        "type": "object",
        "properties": {
          "nextCursor": {
            "type": [
              "string",
              "null"
            ],
            "description": "Cursor for the next page, or null if no more pages."
          },
          "hasMore": {
            "type": "boolean",
            "description": "Whether more results exist beyond this page."
          }
        },
        "required": [
          "nextCursor",
          "hasMore"
        ]
      },
      "KeyRegistrationResponse": {
        "type": "object",
        "properties": {
          "apiKey": {
            "type": "string",
            "description": "Plaintext API key. Returned once, never stored."
          },
          "accountId": {
            "type": "string",
            "description": "Account ID associated with this key."
          }
        },
        "required": [
          "apiKey",
          "accountId"
        ]
      },
      "PlanDefinition": {
        "type": "object",
        "description": "A billing plan with its limits and pricing.",
        "properties": {
          "id": {
            "type": "string",
            "enum": [
              "free",
              "basic",
              "pro",
              "agency"
            ]
          },
          "name": {
            "type": "string"
          },
          "priceUsd": {
            "type": "number"
          },
          "maxWorkers": {
            "type": "integer"
          },
          "maxTasksPerMonth": {
            "type": "integer"
          },
          "maxClaimsPerHour": {
            "type": "integer"
          },
          "maxCreatesPerHour": {
            "type": "integer"
          },
          "retentionDays": {
            "type": "integer"
          },
          "purchasable": {
            "type": "boolean"
          }
        },
        "required": [
          "id",
          "name",
          "priceUsd",
          "maxWorkers",
          "maxTasksPerMonth",
          "maxClaimsPerHour",
          "maxCreatesPerHour",
          "retentionDays",
          "purchasable"
        ]
      },
      "BillingStatusResponse": {
        "type": "object",
        "description": "Current plan state and usage for the authenticated account.",
        "properties": {
          "plan": {
            "$ref": "#/components/schemas/PlanDefinition"
          },
          "planExpiresAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "tasksCreatedThisCycle": {
            "type": "integer"
          },
          "cycleStartedAt": {
            "type": "string",
            "format": "date-time"
          },
          "request_id": {
            "type": "string"
          }
        },
        "required": [
          "plan",
          "planExpiresAt",
          "tasksCreatedThisCycle",
          "cycleStartedAt",
          "request_id"
        ]
      },
      "CheckoutResponse": {
        "type": "object",
        "description": "Checkout session created. The checkoutUrl must be opened by a human to approve payment.",
        "properties": {
          "purchaseId": {
            "type": "string",
            "description": "Internal purchase ID (pur_{ulid} format)."
          },
          "orderId": {
            "type": "string",
            "description": "PayPal order ID."
          },
          "checkoutUrl": {
            "type": "string",
            "format": "uri",
            "description": "PayPal approval URL. Must be opened by a human."
          },
          "planId": {
            "type": "string"
          },
          "planName": {
            "type": "string"
          },
          "priceUsd": {
            "type": "number"
          },
          "checkoutExpiresAt": {
            "type": "string",
            "format": "date-time"
          },
          "request_id": {
            "type": "string"
          },
          "agent_contract": {
            "$ref": "#/components/schemas/AgentContract"
          }
        },
        "required": [
          "purchaseId",
          "orderId",
          "checkoutUrl",
          "planId",
          "planName",
          "priceUsd",
          "checkoutExpiresAt",
          "request_id",
          "agent_contract"
        ]
      },
      "VerifyResponse": {
        "type": "object",
        "description": "Payment verification and plan activation result.",
        "properties": {
          "outcome": {
            "type": "string",
            "enum": [
              "activated",
              "already_confirmed"
            ],
            "description": "Activation outcome."
          },
          "purchaseId": {
            "type": "string"
          },
          "planId": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "request_id": {
            "type": "string"
          },
          "agent_contract": {
            "$ref": "#/components/schemas/AgentContract"
          }
        },
        "required": [
          "outcome",
          "purchaseId",
          "planId",
          "message",
          "request_id",
          "agent_contract"
        ]
      }
    }
  },
  "paths": {
    "/health": {
      "get": {
        "summary": "Health check",
        "description": "Returns service health status including lease expiry job status.",
        "tags": [
          "Public"
        ],
        "responses": {
          "200": {
            "description": "Service is healthy.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "const": "ok"
                    },
                    "leaseExpiryJob": {
                      "type": "object",
                      "properties": {
                        "lastRunAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "staleSec": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "healthy": {
                          "type": "boolean"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/.well-known/agent.json": {
      "get": {
        "summary": "Agent discovery manifest",
        "description": "Returns the agent discovery manifest with references to all discovery resources.",
        "tags": [
          "Public"
        ],
        "responses": {
          "200": {
            "description": "Agent discovery manifest.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/v1/keys/register": {
      "post": {
        "summary": "Register API key",
        "description": "Creates a new API key and account. The plaintext key is returned exactly once.",
        "tags": [
          "Public"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string",
                    "description": "Optional contact email."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Key registered successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KeyRegistrationResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited (10/hour per IP).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/capabilities": {
      "get": {
        "summary": "API capabilities document",
        "description": "Returns the full API capabilities: version, limits, error codes, rate limits, action codes.",
        "tags": [
          "Public"
        ],
        "responses": {
          "200": {
            "description": "Capabilities document.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/v1/tool": {
      "get": {
        "summary": "Tool manifest",
        "description": "Returns the MCP-compatible tool manifest describing available operations.",
        "tags": [
          "Public"
        ],
        "responses": {
          "200": {
            "description": "Tool manifest.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/v1/schema": {
      "get": {
        "summary": "API schema",
        "description": "Returns this OpenAPI 3.1 schema document.",
        "tags": [
          "Public"
        ],
        "responses": {
          "200": {
            "description": "OpenAPI schema document.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/v1/billing/plans": {
      "get": {
        "summary": "List billing plans",
        "description": "Returns all available billing plans with limits and pricing. Public — no auth required.",
        "tags": [
          "Billing"
        ],
        "responses": {
          "200": {
            "description": "Plan catalog.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "plans": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PlanDefinition"
                      }
                    }
                  },
                  "required": [
                    "plans"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/billing/status": {
      "get": {
        "summary": "Billing status",
        "description": "Returns current plan, usage counters, and limits for the authenticated account.",
        "tags": [
          "Billing"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Billing status.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BillingStatusResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/billing/checkout": {
      "post": {
        "summary": "Start checkout",
        "description": "Create a PayPal checkout session for a plan purchase. Returns a checkoutUrl that a human must open to approve payment. Agents cannot complete payment themselves.",
        "tags": [
          "Billing"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "planId": {
                    "type": "string",
                    "enum": [
                      "basic",
                      "pro",
                      "agency"
                    ],
                    "description": "Plan tier to purchase."
                  }
                },
                "required": [
                  "planId"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Checkout created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CheckoutResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid plan or already has pending checkout.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Payment processing not configured.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/billing/verify": {
      "post": {
        "summary": "Verify payment",
        "description": "Capture PayPal payment and activate the purchased plan. Call after the user has approved payment on PayPal.",
        "tags": [
          "Billing"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "purchaseId": {
                    "type": "string",
                    "description": "Purchase ID from the checkout response."
                  }
                },
                "required": [
                  "purchaseId"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Payment verified and plan activated (or already confirmed).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerifyResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "402": {
            "description": "Payment failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Purchase not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "410": {
            "description": "Checkout expired.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/tasks": {
      "post": {
        "summary": "Create task",
        "description": "Create a new task. The task enters \"pending\" status and is available for claiming.",
        "tags": [
          "Tasks"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "maxLength": 100,
                    "pattern": "^[a-zA-Z0-9_-]+$",
                    "description": "Task routing key."
                  },
                  "payload": {
                    "type": "object",
                    "description": "Task input data. Max 64 KB, max depth 5."
                  },
                  "priority": {
                    "type": "integer",
                    "default": 0,
                    "minimum": 0,
                    "maximum": 100
                  },
                  "maxAttempts": {
                    "type": "integer",
                    "default": 3,
                    "minimum": 1,
                    "maximum": 10
                  },
                  "leaseDurationSeconds": {
                    "type": "integer",
                    "default": 300,
                    "minimum": 30,
                    "maximum": 3600
                  },
                  "scheduledAt": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Delay claiming until this time. Max 30 days."
                  },
                  "idempotencyKey": {
                    "type": "string",
                    "maxLength": 255,
                    "description": "Idempotency key (printable ASCII)."
                  }
                },
                "required": [
                  "type",
                  "payload"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Task created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskWithContract"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency conflict.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Idempotency in-flight.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "get": {
        "summary": "List tasks",
        "description": "List tasks with optional filtering and cursor pagination.",
        "tags": [
          "Tasks"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "pending",
                "claimed",
                "completed",
                "dead_letter",
                "cancelled"
              ]
            },
            "description": "Filter by status."
          },
          {
            "name": "type",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter by task type."
          },
          {
            "name": "claimed_by",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter by worker ID."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20,
              "minimum": 1,
              "maximum": 100
            },
            "description": "Max results per page."
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Pagination cursor."
          }
        ],
        "responses": {
          "200": {
            "description": "Task list.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/TaskWithContract"
                      }
                    },
                    "pageInfo": {
                      "$ref": "#/components/schemas/PageInfo"
                    }
                  },
                  "required": [
                    "items",
                    "pageInfo"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/tasks/{id}": {
      "get": {
        "summary": "Get task",
        "description": "Get a single task by ID.",
        "tags": [
          "Tasks"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Task ID."
          }
        ],
        "responses": {
          "200": {
            "description": "Task found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskWithContract"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Task not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/tasks/claim": {
      "post": {
        "summary": "Claim next task",
        "description": "Claim the next available task of the given type (server-assigned). Returns null task if queue is empty.",
        "tags": [
          "Tasks"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "description": "Task type to claim."
                  },
                  "worker_id": {
                    "type": "string",
                    "description": "Worker identity for observability."
                  }
                },
                "required": [
                  "type"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Claim result. task is null if no work is available.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ClaimSuccessResponse"
                    },
                    {
                      "$ref": "#/components/schemas/ClaimEmptyResponse"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/tasks/{id}/claim": {
      "post": {
        "summary": "Claim task by ID",
        "description": "Claim a specific task by ID (explicit assignment).",
        "tags": [
          "Tasks"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Task ID."
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "worker_id": {
                    "type": "string",
                    "description": "Worker identity for observability."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Task claimed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ClaimSuccessResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Task not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "Invalid transition or not yet claimable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/tasks/{id}/complete": {
      "post": {
        "summary": "Complete task",
        "description": "Complete a claimed task with optional result and/or OutputLayer artifact reference. Requires valid lease.",
        "tags": [
          "Tasks"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Task ID."
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "result": {
                    "type": "object",
                    "description": "Inline structured result. Max 64 KB, max depth 5."
                  },
                  "output_id": {
                    "type": "string",
                    "description": "OutputLayer artifact ID reference."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Task completed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskWithContract"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Task not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "Lease expired or invalid transition.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/tasks/{id}/fail": {
      "post": {
        "summary": "Fail task",
        "description": "Fail a claimed task attempt. Returns to \"pending\" if retries remain, or moves to \"dead_letter\" if exhausted. Requires valid lease.",
        "tags": [
          "Tasks"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Task ID."
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "reason": {
                    "type": "string",
                    "maxLength": 500,
                    "description": "Failure reason."
                  },
                  "retry_after_seconds": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 86400,
                    "description": "Delay before task becomes claimable again."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Task failed. Status is now pending or dead_letter.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskWithContract"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Task not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "Lease expired or invalid transition.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/tasks/{id}/heartbeat": {
      "post": {
        "summary": "Heartbeat (renew lease)",
        "description": "Renew the lease on a claimed task. Extends lease_expires_at by lease_duration_seconds. Requires valid lease.",
        "tags": [
          "Tasks"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Task ID."
          }
        ],
        "responses": {
          "200": {
            "description": "Lease renewed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskWithContract"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Task not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "Lease expired or invalid transition.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/tasks/{id}/cancel": {
      "post": {
        "summary": "Cancel task",
        "description": "Cancel a pending task. Only works on tasks in \"pending\" status.",
        "tags": [
          "Tasks"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Task ID."
          }
        ],
        "responses": {
          "200": {
            "description": "Task cancelled.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskWithContract"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Task not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "Task currently claimed or invalid transition.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/tasks/{id}/requeue": {
      "post": {
        "summary": "Requeue task",
        "description": "Re-queue a dead-lettered task. Resets attempt_count to 0 and returns task to \"pending\".",
        "tags": [
          "Tasks"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Task ID."
          }
        ],
        "responses": {
          "200": {
            "description": "Task requeued.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskWithContract"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Task not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "Invalid transition.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  }
}