{
  "openapi": "3.1.0",
  "info": {
    "title": "The Claw agent API",
    "version": "2026-10-14",
    "description": "Free asynchronous ONNX admission; exact-price MPP pull charges in OUSD; FIFO physical execution. Mainnet 4217. Only a credential-bearing run request can charge. Never automatically repay an unresolved request. Public metadata is not private. See the complete guide for limits, outcome rules and recovery."
  },
  "servers": [
    {
      "url": "https://www.paradigm.xyz/puzzles/claw/v1"
    }
  ],
  "externalDocs": {
    "description": "Complete agent submission guide",
    "url": "https://www.paradigm.xyz/puzzles/claw/guide.md"
  },
  "tags": [
    {
      "name": "Status"
    },
    {
      "name": "Models"
    },
    {
      "name": "Payments"
    },
    {
      "name": "Jobs"
    },
    {
      "name": "Interactive play"
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "operationId": "getHealth",
        "tags": [
          "Status"
        ],
        "summary": "Read API, runner, archive and payment configuration",
        "description": "API ok is not a physical-machine readiness guarantee.",
        "responses": {
          "200": {
            "description": "Current status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "payment": {
                      "type": "object",
                      "properties": {
                        "currency": {
                          "type": "string"
                        },
                        "decimals": {
                          "type": "integer"
                        },
                        "recipient": {
                          "type": "string"
                        },
                        "fee_currency": {
                          "type": "string"
                        }
                      },
                      "additionalProperties": true
                    },
                    "runner": {
                      "type": "object"
                    },
                    "archive": {
                      "type": "object"
                    },
                    "queue": {
                      "$ref": "#/components/schemas/Queue"
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/price": {
      "get": {
        "operationId": "getPrice",
        "tags": [
          "Status"
        ],
        "summary": "Get a nonbinding price estimate",
        "responses": {
          "200": {
            "description": "Not a reserved price or lease",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "payment": {
                      "type": "object",
                      "properties": {
                        "currency": {
                          "type": "string"
                        },
                        "decimals": {
                          "type": "integer"
                        },
                        "recipient": {
                          "type": "string"
                        },
                        "fee_currency": {
                          "type": "string"
                        }
                      },
                      "additionalProperties": true
                    },
                    "queue": {
                      "$ref": "#/components/schemas/Queue"
                    },
                    "quote_ttl_ms": {
                      "type": "integer"
                    },
                    "authorization_ttl_ms": {
                      "type": "integer"
                    },
                    "play_seconds": {
                      "type": "integer"
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/models": {
      "post": {
        "operationId": "uploadModel",
        "tags": [
          "Models"
        ],
        "summary": "Upload a raw ZIP for free admission",
        "description": "Not multipart. Exactly manifest.json and policy.onnx. 25 MiB compressed/uncompressed. A 202 is not acceptance: poll until model.status=uploaded. No MPP credential is needed. X-Puzzles-API-Key is optional for free admission testing. Supplied keys must be valid. Anonymous uploads have author null and cannot buy runs; upload again with a valid key to obtain an owned model ID.",
        "parameters": [
          {
            "in": "header",
            "name": "x-model-name",
            "schema": {
              "type": "string",
              "example": "model.zip"
            },
            "description": "Display filename; do not include secrets."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/zip": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Existing accepted identical artifact",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ModelResponse"
                }
              }
            }
          },
          "202": {
            "description": "Queued for admission",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ModelResponse"
                }
              }
            },
            "headers": {
              "Location": {
                "schema": {
                  "type": "string"
                }
              },
              "Retry-After": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "description": "Supplied Puzzles API key is malformed or invalid",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Upload rejected; oversized streaming bodies may close the connection",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "upload_rate_limited; honor Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "admission_unavailable or upload_busy; honor Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {},
          {
            "PuzzlesKey": []
          }
        ]
      }
    },
    "/models/{id}": {
      "get": {
        "operationId": "getModel",
        "tags": [
          "Models"
        ],
        "summary": "Poll admission",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Only uploaded means accepted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "model": {
                      "$ref": "#/components/schemas/Model"
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "model_auth_required or invalid_puzzles_api_key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Model not found or not owned by this account",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "PuzzlesKey": []
          },
          {
            "ModelStatus": []
          }
        ],
        "description": "Private admission details. Account-linked uploads require their owner's X-Puzzles-API-Key. Anonymous uploads require the X-Claw-Model-Token from the upload response. Model IDs and leaderboard entries do not grant access to submissions."
      }
    },
    "/models/{id}/run": {
      "post": {
        "operationId": "buyRun",
        "tags": [
          "Payments"
        ],
        "summary": "Quote or pay for one physical run",
        "description": "Without Authorization, returns an MPP 402. With a locally signed MPP Tempo transaction credential, checks an 8-second exact-price quote and sponsors/broadcasts payment. Only a confirmed and backed escrow receipt creates a job. Prizes and refunds go to the payer. Open receipts have a 24-hour permissionless refund deadline. Pull mode only. A fresh payment buys a new run. Persist challenge.request.externalId before submission; there is no Idempotency-Key API. Original successful credential replay returns the same job. Requires X-Puzzles-API-Key on every request, including the signed MPP retry. The model ID belongs to the verified uploader.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "security": [
          {
            "PuzzlesKey": []
          },
          {
            "PuzzlesKey": [],
            "MPP": []
          }
        ],
        "responses": {
          "200": {
            "description": "Confirmed payment, or same paid quote replay",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobResponse"
                }
              }
            },
            "headers": {
              "Payment-Receipt": {
                "schema": {
                  "type": "string"
                },
                "description": "MPP payment receipt for a newly completed payment"
              }
            }
          },
          "202": {
            "description": "payment_pending_confirmation; poll status_url, never repay while unresolved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PendingPayment"
                }
              }
            }
          },
          "400": {
            "description": "prize_recipient_is_payer or invalid_payment_credential",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "puzzles_api_key_required or invalid_puzzles_api_key; no payment submitted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Initial payment challenge; or Quote Stale with a fresh challenge; or payment_rejected. Do not blindly retry a second 402.",
            "headers": {
              "WWW-Authenticate": {
                "schema": {
                  "type": "string"
                },
                "description": "Payment challenge, when supplied; token amounts are integer millionths of OUSD"
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "model_owner_mismatch; upload your own model with the key before buying a run",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "model_not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "model_not_accepted, quote_pending_payment, quote_model_mismatch or quote_unavailable; inspect/poll original record",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "quote_not_found_or_expired",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "paid_play_unavailable or payment_busy; honor Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-mpp": {
          "method": "tempo",
          "intent": "charge",
          "mode": "pull",
          "chainId": 4217,
          "currency": "0x20c0000000000000000000006a37da5c996874be",
          "recipient": "0xec0eca588024e2d0091e74bd9034ff581111ea7f",
          "decimals": 6,
          "feePayer": true
        }
      }
    },
    "/quotes/{id}": {
      "get": {
        "operationId": "getQuote",
        "tags": [
          "Payments"
        ],
        "summary": "Reconcile the original payment",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Original quote and its job, if paid",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "quote": {
                      "$ref": "#/components/schemas/Quote"
                    },
                    "job": {
                      "anyOf": [
                        {
                          "$ref": "#/components/schemas/Job"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "404": {
            "description": "Not found; missing data alone does not establish that a payment was canceled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/jobs/{id}": {
      "get": {
        "operationId": "getJob",
        "tags": [
          "Jobs"
        ],
        "summary": "Poll a paid run",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "done and refunded are terminal; delivery_pending means funds remain owed; needs_review requires an operator",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "job": {
                      "$ref": "#/components/schemas/Job"
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "404": {
            "description": "job_not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/jobs": {
      "get": {
        "operationId": "listJobs",
        "tags": [
          "Jobs"
        ],
        "summary": "List recent public jobs",
        "description": "Not wallet-filtered. Never select an arbitrary job as the identity of a lost payment.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Recent jobs and queue",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "jobs": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Job"
                      }
                    },
                    "queue": {
                      "$ref": "#/components/schemas/Queue"
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/submissions/identity": {
      "post": {
        "operationId": "verifyPuzzlesKey",
        "tags": [
          "Models"
        ],
        "summary": "Verify a Paradigm Puzzles API key",
        "security": [
          {
            "PuzzlesKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Verified account; no key is returned",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "author": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Puzzles API key missing or invalid",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Puzzles authentication unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/models/leaderboard": {
      "get": {
        "operationId": "getModelLeaderboard",
        "tags": [
          "Models"
        ],
        "summary": "Top 100 players by their best model success rate",
        "description": "One model per verified uploader, with at least 20 completed, scored runs per model. Success rate is wins divided by runs. Manual games, anonymous legacy runs, refunds, voids and unresolved outcomes are excluded. Resolved timeout and policy-violation losses count. Equal rates favor the model with more scored runs; players share a rank only when both rate and run count match. Personal model ties prefer more runs, then the earliest upload.",
        "responses": {
          "200": {
            "description": "Leaderboard",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "entries": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "rank": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "author": {
                            "type": "string"
                          },
                          "model_id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "wins": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "runs": {
                            "type": "integer",
                            "minimum": 20
                          },
                          "success_rate": {
                            "type": "number",
                            "minimum": 0,
                            "maximum": 1,
                            "description": "Successful pickups divided by completed, scored runs; multiply by 100 for a percentage."
                          }
                        },
                        "additionalProperties": true
                      }
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/camera/frame.jpg": {
      "get": {
        "operationId": "observeCamera",
        "tags": [
          "Interactive play"
        ],
        "summary": "Fresh public camera frame without payment",
        "responses": {
          "200": {
            "description": "960 x 600 JPEG. No stale fallback.",
            "content": {
              "image/jpeg": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            },
            "headers": {
              "X-Claw-Captured-At-Ms": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-Claw-Frame-Sha256": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "503": {
            "description": "camera_unavailable; retry after one second",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/manual/run": {
      "post": {
        "operationId": "buyInteractiveRun",
        "tags": [
          "Interactive play",
          "Payments"
        ],
        "summary": "Quote or pay for one interactive turn",
        "description": "Send the same saved X-Claw-Control-Token on the initial 402 request and its signed MPP pull retry. OUSD exact-price payment, gas sponsored. No Puzzles API key or model upload. A new payment buys a new turn; never repay an unresolved request. Recover with GET /manual/session using the original token. Heartbeat every 750 ms after confirmation, then start when ready. Fifteen real seconds to steer and Drop. Disconnecting before Drop forfeits the turn.",
        "parameters": [],
        "security": [
          {
            "ClawControl": []
          },
          {
            "ClawControl": [],
            "MPP": []
          }
        ],
        "responses": {
          "200": {
            "description": "Confirmed payment, or same paid quote replay",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobResponse"
                }
              }
            },
            "headers": {
              "Payment-Receipt": {
                "schema": {
                  "type": "string"
                },
                "description": "MPP payment receipt for a newly completed payment"
              }
            }
          },
          "202": {
            "description": "payment_pending_confirmation; poll status_url, never repay while unresolved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PendingPayment"
                }
              }
            }
          },
          "400": {
            "description": "control_token_required or invalid_payment_credential",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Initial payment challenge; or Quote Stale with a fresh challenge; or payment_rejected. Do not blindly retry a second 402.",
            "headers": {
              "WWW-Authenticate": {
                "schema": {
                  "type": "string"
                },
                "description": "Payment challenge, when supplied; token amounts are integer millionths of OUSD"
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "wrong_manual_owner",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "quote_pending_payment or quote_unavailable; reconcile the original token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "quote_not_found_or_expired",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "paid_play_unavailable or payment_busy; honor Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-mpp": {
          "method": "tempo",
          "intent": "charge",
          "mode": "pull",
          "chainId": 4217,
          "currency": "0x20c0000000000000000000006a37da5c996874be",
          "recipient": "0xec0eca588024e2d0091e74bd9034ff581111ea7f",
          "decimals": 6,
          "feePayer": true
        }
      }
    },
    "/manual/session": {
      "get": {
        "operationId": "recoverInteractivePayment",
        "tags": [
          "Interactive play"
        ],
        "summary": "Recover this private control token's original payments",
        "security": [
          {
            "ClawControl": []
          }
        ],
        "responses": {
          "200": {
            "description": "Latest 25 bound quotes and their jobs. Empty is not proof that an in-flight payment failed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "server_time_ms": {
                      "type": "integer"
                    },
                    "sessions": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "quote": {
                            "$ref": "#/components/schemas/Quote"
                          },
                          "job": {
                            "anyOf": [
                              {
                                "$ref": "#/components/schemas/Job"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "control": {
                            "anyOf": [
                              {
                                "$ref": "#/components/schemas/Control"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          }
                        },
                        "additionalProperties": true
                      }
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "control_token_required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/manual/jobs/{id}": {
      "post": {
        "operationId": "controlInteractiveRun",
        "tags": [
          "Interactive play"
        ],
        "summary": "Heartbeat, start or control your paid turn",
        "security": [
          {
            "ClawControl": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "description": "Heartbeat every 750 ms. Start only when ready. Steering expires after 400 ms; renew every 150 ms, then stop. Movement, stop and Drop require a strictly increasing seq and sent_at_ms within 1000 ms of the server clock. One Drop only. Time continues between requests.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "action": {
                    "type": "string",
                    "enum": [
                      "heartbeat",
                      "start",
                      "up",
                      "down",
                      "left",
                      "right",
                      "stop",
                      "drop",
                      "leave"
                    ]
                  },
                  "seq": {
                    "type": "integer"
                  },
                  "sent_at_ms": {
                    "type": "integer"
                  }
                },
                "additionalProperties": true,
                "required": [
                  "action"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Current control state",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "job": {
                      "$ref": "#/components/schemas/Job"
                    },
                    "control": {
                      "$ref": "#/components/schemas/Control"
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid command",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "wrong_manual_owner",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "job_not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Turn is not accepting this command, stale sequence or stale command",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Commands too frequent",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/manual/jobs/{id}/recording": {
      "get": {
        "operationId": "downloadOwnInteractiveRecording",
        "tags": [
          "Interactive play"
        ],
        "summary": "Download your own robot-camera video and synchronized actions ZIP",
        "security": [
          {
            "ClawControl": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Private presigned URL, valid for 60 seconds",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "type": "string"
                    },
                    "sha256": {
                      "type": "string"
                    },
                    "bytes": {
                      "type": "integer"
                    },
                    "expires_in": {
                      "const": 60
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "202": {
            "description": "Archive not ready; retry after five seconds",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "const": "recording_pending"
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "403": {
            "description": "wrong_manual_owner",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "PuzzlesKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Puzzles-API-Key",
        "description": "Your personal Paradigm Puzzles pp_... API key. Optional for free upload testing; required to link an upload to its owner and for every model-run request, separately from MPP Authorization."
      },
      "MPP": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization",
        "description": "MPP credential: Payment <encoded credential>. Not a bearer API key. Sign locally with an authorized Tempo wallet. Do not share private keys."
      },
      "ModelStatus": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Claw-Model-Token",
        "description": "Private status_token returned once with an anonymous upload. Bound to that model, valid for 24 hours, and grants no paid-run access. Never put it in a URL."
      },
      "ClawControl": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Claw-Control-Token",
        "description": "Client-generated random 32-byte secret encoded as 64 lowercase hex characters. Save before payment; use the same token on the initial challenge, MPP retry, controls, recovery and recording download."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "detail": {
            "type": "string"
          },
          "status_url": {
            "type": "string"
          },
          "quote": {
            "$ref": "#/components/schemas/Quote"
          },
          "model": {
            "$ref": "#/components/schemas/Model"
          },
          "queue": {
            "$ref": "#/components/schemas/Queue"
          }
        },
        "additionalProperties": true
      },
      "Problem": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          },
          "detail": {
            "type": "string"
          }
        },
        "additionalProperties": true
      },
      "Model": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "filename": {
            "type": "string"
          },
          "content_type": {
            "type": "string"
          },
          "size_bytes": {
            "type": "integer"
          },
          "sha256": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending_admission",
              "validating",
              "uploaded",
              "rejected",
              "expired"
            ]
          },
          "created_at_ms": {
            "type": "integer"
          },
          "admission": {
            "type": [
              "object",
              "null"
            ]
          },
          "admission_error": {
            "type": [
              "string",
              "null"
            ]
          },
          "author": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "additionalProperties": true
      },
      "ModelResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "model": {
            "$ref": "#/components/schemas/Model"
          },
          "status_url": {
            "type": "string"
          },
          "status_token": {
            "type": "string",
            "description": "Only returned for anonymous uploads. Keep private; use as X-Claw-Model-Token for admission polling."
          }
        },
        "additionalProperties": true
      },
      "Quote": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "model_id": {
            "anyOf": [
              {
                "type": "string",
                "format": "uuid"
              },
              {
                "const": "__manual_control_v1__"
              }
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "quoted",
              "pending_payment",
              "paid",
              "stale",
              "expired",
              "payment_failed",
              "payment_expired",
              "payment_refunded"
            ]
          },
          "price_micro_usd": {
            "type": "integer"
          },
          "amount": {
            "type": "string",
            "description": "Decimal payment token amount"
          },
          "queue_depth": {
            "type": "integer"
          },
          "created_at_ms": {
            "type": "integer"
          },
          "quote_expires_at_ms": {
            "type": "integer"
          },
          "authorization_expires_at_ms": {
            "type": "integer"
          }
        },
        "additionalProperties": true
      },
      "Job": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "model_id": {
            "anyOf": [
              {
                "type": "string",
                "format": "uuid"
              },
              {
                "type": "null"
              }
            ]
          },
          "kind": {
            "type": "string",
            "enum": [
              "model",
              "manual"
            ]
          },
          "quote_id": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "leasing",
              "running",
              "grading",
              "settlement_pending",
              "payout_pending",
              "done",
              "needs_review",
              "refunded"
            ]
          },
          "queue_position": {
            "type": [
              "integer",
              "null"
            ]
          },
          "created_at_ms": {
            "type": "integer"
          },
          "paid_at_ms": {
            "type": "integer"
          },
          "started_at_ms": {
            "type": [
              "integer",
              "null"
            ]
          },
          "finished_at_ms": {
            "type": [
              "integer",
              "null"
            ]
          },
          "attempts": {
            "type": "integer"
          },
          "last_attempt_at_ms": {
            "type": [
              "integer",
              "null"
            ]
          },
          "last_error": {
            "type": [
              "string",
              "null"
            ]
          },
          "result": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "status": {
                "type": "string"
              },
              "reason": {
                "type": "string"
              },
              "outcome": {
                "type": "object",
                "properties": {
                  "pickup_success": {
                    "type": "boolean"
                  },
                  "grade": {
                    "type": "string"
                  },
                  "review_required": {
                    "type": "boolean"
                  }
                },
                "additionalProperties": true
              }
            }
          },
          "prize": {
            "type": "object",
            "properties": {
              "recipient": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "amount_micro_usd": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "delivery_pending": {
                "type": "boolean"
              },
              "delivery_receipt": {
                "type": [
                  "object",
                  "null"
                ]
              }
            },
            "additionalProperties": true
          },
          "escrow": {
            "type": [
              "object",
              "null"
            ],
            "description": "Receipt witness, immutable refund deadline, outcome, outstanding credit and settlement transaction."
          },
          "paid": {
            "type": "object",
            "properties": {
              "price_micro_usd": {
                "type": "integer"
              },
              "amount": {
                "type": "string"
              },
              "tx_reference": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "additionalProperties": true
          },
          "lease": {
            "type": [
              "object",
              "null"
            ],
            "description": "Informational only; no client claim/control is required."
          }
        },
        "additionalProperties": true
      },
      "JobResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "job": {
            "$ref": "#/components/schemas/Job"
          },
          "queue": {
            "$ref": "#/components/schemas/Queue"
          }
        },
        "additionalProperties": true
      },
      "PendingPayment": {
        "type": "object",
        "properties": {
          "error": {
            "const": "payment_pending_confirmation"
          },
          "detail": {
            "type": "string"
          },
          "status_url": {
            "type": "string"
          },
          "queue": {
            "$ref": "#/components/schemas/Queue"
          }
        },
        "additionalProperties": true
      },
      "Queue": {
        "type": "object",
        "properties": {
          "demand_depth": {
            "type": "integer"
          },
          "estimated_wait_seconds": {
            "type": "integer",
            "description": "Nominal, excludes real-world delays"
          },
          "pending_payments": {
            "type": "integer"
          },
          "jobs": {
            "type": "object",
            "additionalProperties": {
              "type": "integer"
            }
          },
          "auction": {
            "type": "object",
            "properties": {
              "priceMicroUsd": {
                "type": "integer"
              },
              "amount": {
                "type": "string"
              },
              "minMicroUsd": {
                "type": "integer"
              },
              "maxMicroUsd": {
                "type": "integer"
              },
              "baseMicroUsd": {
                "type": "integer"
              },
              "demandDepth": {
                "type": "integer"
              },
              "queueMultiplier": {
                "type": "number"
              },
              "halfLifeSeconds": {
                "type": "number"
              }
            },
            "additionalProperties": true
          }
        },
        "additionalProperties": true
      },
      "Control": {
        "type": "object",
        "properties": {
          "phase": {
            "type": "string"
          },
          "server_time_ms": {
            "type": "integer"
          },
          "deadline_ms": {
            "type": [
              "integer",
              "null"
            ]
          }
        },
        "additionalProperties": true
      }
    }
  }
}
