Skip to content

Record a sky camera around the clock, keep the footage on your own disk, and find what flew past.

197 KB
Raw Blame
{
  "openapi": "3.1.1",
  "info": {
    "title": "openskycam API",
    "version": "1.4.1",
    "description": "Read original footage from the existing camera archive. Create a key in the website under API access, then send Authorization: Bearer <key>. Pagination, checksums, and byte-range downloads support large transfers. Raw footage expires under the existing 40-day retention policy. Everything the website does is also an API call: each /api/<path> operation except API key management is served at /v1/<path> for an Agent key that covers every camera, under the same name (the website copy is website_<name>), and image links in its answers point at /v1. API key management requires a website session and cannot be used with a Bearer key. Processor endpoints are an opt-in local integration preview. They require a processor:run credential restricted to one registered pipeline and selected cameras. Continuous production inference is not enabled. Model publishing uses models:write; device synchronization uses models:sync scoped to one device. Models persist independently of footage retention. Workshop saves logical buckets and workflows, runs explicitly submitted bounded labeling jobs, and freezes reviewed dataset versions. Workshop execution uses workshop:run keys scoped to a device and cameras. Existing footage:read keys can download dataset manifests and images for their cameras. This does not enable continuous production inference."
  },
  "servers": [
    {
      "url": "/",
      "description": "This deployment's API host (API_HOST); the website also serves /v1"
    }
  ],
  "tags": [
    {
      "name": "Footage",
      "description": "Read-only access to recordings granted to your API key."
    },
    {
      "name": "Key management",
      "description": "Manage your own keys from a signed-in website session."
    },
    {
      "name": "Inference",
      "description": "Leased processing jobs, results and evidence. Local preview; 404 when disabled."
    },
    {
      "name": "Models",
      "description": "Immutable trained models, verified transfers, and device assignments."
    },
    {
      "name": "Workshop",
      "description": "Saved workflows, shared buckets, bounded processing, review, and immutable dataset versions."
    },
    {
      "name": "Agent",
      "description": "An MCP server that gives an AI agent full use of openskycam through an agent key."
    }
  ],
  "security": [
    {
      "ApiKey": []
    }
  ],
  "paths": {
    "/v1/me": {
      "get": {
        "operationId": "getApiIdentity",
        "summary": "Inspect the current API key",
        "description": "Returns permissions for this key without exposing account details.",
        "tags": ["Footage"],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Identity"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, expired, or revoked API key. Includes WWW-Authenticate: Bearer.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key does not allow access to this camera.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Request failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/cameras": {
      "get": {
        "operationId": "listCameras",
        "summary": "List accessible cameras",
        "description": "Only cameras granted to the API key are returned.",
        "tags": ["Footage"],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Cameras"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, expired, or revoked API key. Includes WWW-Authenticate: Bearer.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key does not allow access to this camera.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Request failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/recordings": {
      "get": {
        "operationId": "listRecordings",
        "summary": "Find recordings by camera and time",
        "description": "Returns original recordings overlapping [from, to), ordered by start and object key. Unknown durations use a 60-second overlap estimate. Follow next_url until null; send the same Bearer header on every request. New uploads after as_of are excluded from subsequent pages. Retention may still remove older objects during a transfer. Files are not trimmed or transcoded. Responses contain download URLs, sizes, and checksums; no dataset is created.",
        "tags": ["Footage"],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RecordingPage"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, expired, or revoked API key. Includes WWW-Authenticate: Bearer.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key does not allow access to this camera.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Request failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "400": {
            "description": "Request failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "camera",
            "in": "query",
            "required": true,
            "description": "Camera ID.",
            "schema": {
              "type": "string",
              "example": "sky01"
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": true,
            "description": "Inclusive beginning with explicit time zone.",
            "schema": {
              "type": "string",
              "format": "date-time",
              "example": "2026-09-22T19:30:00Z"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": true,
            "description": "Exclusive end with explicit time zone.",
            "schema": {
              "type": "string",
              "format": "date-time",
              "example": "2026-09-22T20:30:00Z"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum records per page.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 100
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque pagination cursor. Keep camera, from, and to unchanged.",
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/v1/recordings/{camera}/{start}/file": {
      "get": {
        "operationId": "downloadRecording",
        "summary": "Download an original recording",
        "description": "Streams original MP4 bytes without buffering or transcoding. A single Range header enables resumable downloads. Send the Bearer key on every request; a listed download_url does not grant access by itself. The one exception is a signed link (query parameters key, expires and sig, valid for one hour, GET or HEAD of that exact path only) that an agent key's MCP tools hand out; it needs no header and stops working when its key is revoked or rotated. Cache files locally by object key and SHA-256. Raw footage follows the 40-day retention policy.",
        "tags": ["Footage"],
        "parameters": [
          {
            "name": "camera",
            "in": "path",
            "required": true,
            "description": "Camera ID.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "start",
            "in": "path",
            "required": true,
            "description": "UTC segment ID from its start timestamp.",
            "schema": {
              "type": "string",
              "pattern": "^\\d{8}T\\d{6}Z$",
              "example": "20260922T193000Z"
            }
          },
          {
            "name": "Range",
            "in": "header",
            "required": false,
            "description": "Optional single byte range, such as bytes=1048576-.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Complete original MP4.",
            "headers": {
              "Accept-Ranges": {
                "schema": {
                  "type": "string",
                  "const": "bytes"
                }
              },
              "Content-Length": {
                "schema": {
                  "type": "integer"
                }
              },
              "ETag": {
                "schema": {
                  "type": "string"
                }
              },
              "Content-Disposition": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "video/mp4": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "206": {
            "description": "Requested byte range.",
            "headers": {
              "Accept-Ranges": {
                "schema": {
                  "type": "string",
                  "const": "bytes"
                }
              },
              "Content-Length": {
                "schema": {
                  "type": "integer"
                }
              },
              "ETag": {
                "schema": {
                  "type": "string"
                }
              },
              "Content-Disposition": {
                "schema": {
                  "type": "string"
                }
              },
              "Content-Range": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "video/mp4": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "Request failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Recording is missing or has expired.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "416": {
            "description": "Byte range cannot be satisfied.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "The footage store is unreachable. Retry later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, expired, or revoked API key. Includes WWW-Authenticate: Bearer.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key does not allow access to this camera.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Request failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "head": {
        "operationId": "headRecording",
        "summary": "Inspect a recording file",
        "tags": ["Footage"],
        "description": "Returns original file headers without the body. Range is ignored for HEAD.",
        "parameters": [
          {
            "name": "camera",
            "in": "path",
            "required": true,
            "description": "Camera ID.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "start",
            "in": "path",
            "required": true,
            "description": "UTC segment ID from its start timestamp.",
            "schema": {
              "type": "string",
              "pattern": "^\\d{8}T\\d{6}Z$",
              "example": "20260922T193000Z"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "File metadata.",
            "headers": {
              "Accept-Ranges": {
                "schema": {
                  "type": "string",
                  "const": "bytes"
                }
              },
              "Content-Length": {
                "schema": {
                  "type": "integer"
                }
              },
              "ETag": {
                "schema": {
                  "type": "string"
                }
              },
              "Content-Disposition": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Request failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Request failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "The footage store is unreachable. Retry later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, expired, or revoked API key. Includes WWW-Authenticate: Bearer.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key does not allow access to this camera.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Request failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/keys": {
      "servers": [
        {
          "url": "/",
          "description": "The signed-in website (SITE_HOST), not the API host"
        }
      ],
      "get": {
        "operationId": "listApiKeys",
        "summary": "List your API keys",
        "tags": ["Key management"],
        "security": [
          {
            "AccessSession": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KeyList"
                }
              }
            }
          },
          "403": {
            "description": "A signed-in email session is required. Mutations also require a same-origin Origin header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Request failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Request failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "Lists your keys without revealing their secrets. Returns at most 200 keys: all active keys first, then the most recent expired or revoked keys."
      },
      "post": {
        "operationId": "createApiKey",
        "summary": "Create a scoped API key",
        "tags": ["Key management"],
        "security": [
          {
            "AccessSession": []
          }
        ],
        "responses": {
          "403": {
            "description": "A signed-in email session is required. Mutations also require a same-origin Origin header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Request failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Request failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "201": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreatedKey"
                }
              }
            }
          },
          "400": {
            "description": "Request failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Request failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Request failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Request failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "Origin",
            "in": "header",
            "required": true,
            "description": "Must exactly match the website origin.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "description": "Maximum 20 active keys per signed-in email. The secret is returned once. API keys cannot call key management endpoints. Defaults to footage:read. processor:run requires pipeline_id and an inference-enabled environment; it adds job claim, heartbeat, completion, failure and evidence upload to footage read access.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name", "cameras", "expires_in_days"],
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 80
                  },
                  "cameras": {
                    "type": "array",
                    "minItems": 0,
                    "uniqueItems": true,
                    "items": {
                      "type": "string"
                    },
                    "description": "Choose cameras for footage/processor keys. Must be empty for model keys."
                  },
                  "expires_in_days": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 365,
                    "default": 90
                  },
                  "scope": {
                    "type": "string",
                    "enum": ["footage:read", "processor:run", "models:write", "models:sync", "workshop:run", "agent"],
                    "default": "footage:read"
                  },
                  "pipeline_id": {
                    "type": "string",
                    "description": "Required for processor:run; rejected for footage:read."
                  },
                  "device_id": {
                    "type": "string",
                    "pattern": "^[a-z0-9][a-z0-9._-]{0,63}$"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/keys/{id}": {
      "servers": [
        {
          "url": "/",
          "description": "The signed-in website (SITE_HOST), not the API host"
        }
      ],
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Your key ID.",
          "schema": {
            "type": "string"
          }
        }
      ],
      "patch": {
        "operationId": "renameApiKey",
        "summary": "Rename an API key",
        "tags": ["Key management"],
        "security": [
          {
            "AccessSession": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KeyResult"
                }
              }
            }
          },
          "403": {
            "description": "A signed-in email session is required. Mutations also require a same-origin Origin header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Request failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Request failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "400": {
            "description": "Request failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Request failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Request failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "Origin",
            "in": "header",
            "required": true,
            "description": "Must exactly match the website origin.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name"],
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 80
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "revokeApiKey",
        "summary": "Revoke an API key",
        "tags": ["Key management"],
        "security": [
          {
            "AccessSession": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KeyResult"
                }
              }
            }
          },
          "403": {
            "description": "A signed-in email session is required. Mutations also require a same-origin Origin header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Request failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Request failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "Origin",
            "in": "header",
            "required": true,
            "description": "Must exactly match the website origin.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "description": "Revocation is immediate for new API requests and idempotent. A transfer already authorized may finish. The masked entry remains in your history."
      }
    },
    "/api/keys/{id}/rotate": {
      "servers": [
        {
          "url": "/",
          "description": "The signed-in website (SITE_HOST), not the API host"
        }
      ],
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Your key ID.",
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "operationId": "rotateApiKey",
        "summary": "Rotate an active API key",
        "tags": ["Key management"],
        "security": [
          {
            "AccessSession": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreatedKey"
                }
              }
            }
          },
          "403": {
            "description": "A signed-in email session is required. Mutations also require a same-origin Origin header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Request failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Request failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "Origin",
            "in": "header",
            "required": true,
            "description": "Must exactly match the website origin.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "description": "Immediately replaces the secret. Camera permissions and expiry stay the same. The new secret is returned only once. Existing clients need to update their credential."
      }
    },
    "/v1/processor/jobs/claim": {
      "post": {
        "operationId": "claimInferenceJob",
        "summary": "Claim one recording",
        "tags": ["Inference"],
        "description": "Claims one available job for this key’s pipeline and camera. Five-minute lease; three total attempts. Null means no available work. Do not blindly retry a lost claim response: the lease will expire.",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "job": {
                      "oneOf": [
                        {
                          "$ref": "#/components/schemas/ClaimedJob"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": ["job"]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Wrong key scope, camera, or website origin.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Inference disabled or resource unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Expired or superseded lease, or a conflicting result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Body exceeds the request limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Wrong content type.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Invalid provenance, coverage, tracks or evidence.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Transient server error. Retry with the same lease and result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "camera": {
                    "type": "string"
                  }
                },
                "required": ["camera"]
              }
            }
          }
        }
      }
    },
    "/v1/processor/jobs/{id}/heartbeat": {
      "post": {
        "operationId": "renewInferenceLease",
        "summary": "Renew a processing lease",
        "tags": ["Inference"],
        "description": "Renew before expiry using the generation and token from claim. A 409 means stop processing and discard this attempt.",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "lease_until": {
                      "type": "string",
                      "format": "date-time"
                    }
                  },
                  "required": ["lease_until"]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Wrong key scope, camera, or website origin.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Inference disabled or resource unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Expired or superseded lease, or a conflicting result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Body exceeds the request limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Wrong content type.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Invalid provenance, coverage, tracks or evidence.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Transient server error. Retry with the same lease and result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Claimed job ID.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Lease"
              }
            }
          }
        }
      }
    },
    "/v1/processor/jobs/{id}/complete": {
      "post": {
        "operationId": "completeInferenceJob",
        "summary": "Commit processing results",
        "tags": ["Inference"],
        "description": "Maximum 2 MiB JSON. Upload referenced JPEGs first. Coverage must match duration within two seconds with at least one sampled frame. Hashes must match the claim. Identical serialized result retries from the committing lease return 200; different results return 409. Expiry remains anchored to the event. Zero tracks records completed coverage.",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "job_id": {
                      "type": "string"
                    },
                    "status": {
                      "const": "completed"
                    },
                    "result_sha256": {
                      "type": "string",
                      "pattern": "^[a-f0-9]{64}$"
                    }
                  },
                  "required": ["job_id", "status", "result_sha256"]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Wrong key scope, camera, or website origin.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Inference disabled or resource unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Expired or superseded lease, or a conflicting result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Body exceeds the request limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Wrong content type.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Invalid provenance, coverage, tracks or evidence.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Transient server error. Retry with the same lease and result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Claimed job ID.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "generation": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "lease_token": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "result": {
                    "$ref": "#/components/schemas/InferenceResult"
                  }
                },
                "required": ["generation", "lease_token", "result"]
              }
            }
          }
        }
      }
    },
    "/v1/processor/jobs/{id}/fail": {
      "post": {
        "operationId": "failInferenceJob",
        "summary": "Report an unsuccessful attempt",
        "tags": ["Inference"],
        "description": "Missing footage expires the job. Other failures retry after 60 seconds until the third attempt. Report a code, never credentials, paths or raw exception dumps.",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": ["queued", "failed", "expired"]
                    }
                  },
                  "required": ["status"]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Wrong key scope, camera, or website origin.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Inference disabled or resource unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Expired or superseded lease, or a conflicting result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Body exceeds the request limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Wrong content type.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Invalid provenance, coverage, tracks or evidence.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Transient server error. Retry with the same lease and result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Claimed job ID.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "generation": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "lease_token": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "error": {
                    "type": "string",
                    "enum": [
                      "download_failed",
                      "checksum_mismatch",
                      "decode_failed",
                      "model_failed",
                      "source_missing",
                      "processor_failed"
                    ]
                  }
                },
                "required": ["generation", "lease_token", "error"]
              }
            }
          }
        }
      }
    },
    "/v1/processor/jobs/{id}/evidence/{sha256}": {
      "put": {
        "operationId": "uploadInferenceEvidence",
        "summary": "Upload a track evidence frame",
        "tags": ["Inference"],
        "description": "JPEG up to 4 MiB. Path SHA-256 must match the body. Stored only under this job and generation; no arbitrary bucket keys. Upload before completing the job.",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "sha256": {
                      "type": "string",
                      "pattern": "^[a-f0-9]{64}$"
                    }
                  },
                  "required": ["sha256"]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Wrong key scope, camera, or website origin.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Inference disabled or resource unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Expired or superseded lease, or a conflicting result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Body exceeds the request limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Wrong content type.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Invalid provenance, coverage, tracks or evidence.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Transient server error. Retry with the same lease and result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Claimed job ID.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sha256",
            "in": "path",
            "required": true,
            "description": "SHA-256 of JPEG bytes.",
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{64}$"
            }
          },
          {
            "name": "X-Lease-Token",
            "in": "header",
            "required": true,
            "description": "Current lease token.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Lease-Generation",
            "in": "header",
            "required": true,
            "description": "Current generation.",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "image/jpeg": {
              "schema": {
                "type": "string",
                "format": "binary",
                "maxLength": 4194304
              }
            }
          }
        }
      }
    },
    "/api/inference/reconcile": {
      "post": {
        "operationId": "reconcileInferenceJobs",
        "summary": "Enqueue missing jobs for a time window",
        "tags": ["Inference"],
        "description": "Requires a website session and an enabled camera subscription. Select at most 24 hours; inserts at most 1440 source rows. Existing input/pipeline jobs are not duplicated. Inputs older than 40 days are excluded.",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "enqueued": {
                      "type": "integer"
                    }
                  },
                  "required": ["enqueued"]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Wrong key scope, camera, or website origin.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Inference disabled or resource unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Expired or superseded lease, or a conflicting result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Body exceeds the request limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Wrong content type.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Invalid provenance, coverage, tracks or evidence.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Transient server error. Retry with the same lease and result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "AccessSession": []
          }
        ],
        "parameters": [
          {
            "name": "Origin",
            "in": "header",
            "required": true,
            "description": "Must match the website origin.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "camera": {
                    "type": "string"
                  },
                  "pipeline_id": {
                    "type": "string"
                  },
                  "from": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "to": {
                    "type": "string",
                    "format": "date-time"
                  }
                },
                "required": ["camera", "pipeline_id", "from", "to"]
              }
            }
          }
        }
      }
    },
    "/api/inference/status": {
      "get": {
        "operationId": "getInferenceStatus",
        "summary": "Read coverage and recent job outcomes",
        "tags": ["Inference"],
        "description": "Counts per pipeline/camera/status and 20 most recent unexpired jobs. Only completed jobs contribute processed coverage.",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "counts": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "recent": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  },
                  "required": ["counts", "recent"]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Wrong key scope, camera, or website origin.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Inference disabled or resource unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Expired or superseded lease, or a conflicting result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Body exceeds the request limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Wrong content type.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Invalid provenance, coverage, tracks or evidence.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Transient server error. Retry with the same lease and result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "AccessSession": []
          }
        ]
      }
    },
    "/api/inference/jobs/{id}/result": {
      "get": {
        "operationId": "getInferenceResult",
        "summary": "Read detailed tracks and provenance",
        "tags": ["Inference"],
        "description": "Website session required. Returns the committed R2 document. Missing, incomplete and expired results return 404.",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InferenceResult"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Wrong key scope, camera, or website origin.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Inference disabled or resource unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Expired or superseded lease, or a conflicting result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Body exceeds the request limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Wrong content type.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Invalid provenance, coverage, tracks or evidence.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Transient server error. Retry with the same lease and result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "AccessSession": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Claimed job ID.",
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/v1/models": {
      "get": {
        "operationId": "listModels",
        "summary": "List immutable model versions",
        "description": "Requires models:write. Includes all archived versions, classes, metrics and artifact checksums. Creation metadata preserves its source; registered_at is the library import/publication date. Historical dates are read from the verified, immutable R2 catalog and matched to artifact checksums. A missing date is never replaced with the import date.",
        "tags": ["Models"],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "models": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ModelCatalogEntry"
                      }
                    }
                  },
                  "required": ["models"],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid metadata, assignment or parameters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or expired credential.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Credential does not permit this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Immutable version or concurrent assignment conflict.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Artifact checksum or size mismatch.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "publishModel",
        "summary": "Publish a trained model version",
        "description": "Requires models:write. Upload artifacts first. Retrying identical metadata succeeds; changing an existing family/version returns 409. Does not deploy the model.",
        "tags": ["Models"],
        "responses": {
          "400": {
            "description": "Invalid metadata, assignment or parameters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or expired credential.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Credential does not permit this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Immutable version or concurrent assignment conflict.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Artifact checksum or size mismatch.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "201": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ModelVersion"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ModelVersion"
              }
            }
          }
        }
      }
    },
    "/v1/models/chunks/{sha}": {
      "put": {
        "operationId": "uploadModelChunk",
        "summary": "Upload a checksum-addressed chunk",
        "description": "Requires models:write. At most 8 MiB. SHA-256 is checked before persistence. Identical chunks are safe to retry.",
        "tags": ["Models"],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ArtifactChunk"
                }
              }
            }
          },
          "400": {
            "description": "Invalid metadata, assignment or parameters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or expired credential.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Credential does not permit this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Immutable version or concurrent assignment conflict.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Artifact checksum or size mismatch.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "sha",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{64}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/octet-stream": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            }
          }
        }
      }
    },
    "/v1/models/artifacts": {
      "post": {
        "operationId": "completeModelArtifact",
        "summary": "Verify and register a complete artifact",
        "description": "Requires models:write. Ordered chunks reconstruct the exact original file; its full SHA-256 is verified. Maximum artifact size 1 GiB. Repeating an already verified artifact is idempotent.",
        "tags": ["Models"],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ArtifactChunk"
                }
              }
            }
          },
          "400": {
            "description": "Invalid metadata, assignment or parameters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or expired credential.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Credential does not permit this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Immutable version or concurrent assignment conflict.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Artifact checksum or size mismatch.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "sha256": {
                    "type": "string",
                    "pattern": "^[a-f0-9]{64}$"
                  },
                  "bytes": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 1073741824
                  },
                  "chunks": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/ArtifactChunk"
                    },
                    "maxItems": 128
                  }
                },
                "required": ["sha256", "bytes", "chunks"],
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/v1/models/artifacts/{sha}": {
      "get": {
        "operationId": "downloadModelArtifact",
        "summary": "Download original model bytes",
        "description": "Publisher keys may download the library. models:sync keys may download only artifacts in their device current assignment. Verify Content-Length and X-Content-SHA256 locally before loading.",
        "tags": ["Models"],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            },
            "headers": {
              "X-Content-SHA256": {
                "schema": {
                  "type": "string",
                  "pattern": "^[a-f0-9]{64}$"
                }
              },
              "Content-Length": {
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "Invalid metadata, assignment or parameters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or expired credential.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Credential does not permit this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Immutable version or concurrent assignment conflict.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Artifact checksum or size mismatch.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "sha",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{64}$"
            }
          }
        ]
      }
    },
    "/v1/models/devices/{id}/desired": {
      "get": {
        "operationId": "getDeviceModelAssignment",
        "summary": "Read the device desired deployment",
        "description": "Requires models:sync for exactly this device. Empty models unloads its managed weights; null means no assignment has been made.",
        "tags": ["Models"],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deployment": {
                      "oneOf": [
                        {
                          "$ref": "#/components/schemas/ModelDeployment"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": ["deployment"],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid metadata, assignment or parameters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or expired credential.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Credential does not permit this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Immutable version or concurrent assignment conflict.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Artifact checksum or size mismatch.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9._-]{0,63}$"
            }
          }
        ]
      }
    },
    "/v1/models/devices/{id}/status": {
      "post": {
        "operationId": "reportDeviceModelStatus",
        "summary": "Acknowledge a model deployment",
        "description": "Requires models:sync for this device. revision is the attempted assignment; active_revision is the locally committed version. Stale reports cannot mark a newer assignment ready. Send stable error codes, never exception dumps.",
        "tags": ["Models"],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    }
                  },
                  "required": ["ok"],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid metadata, assignment or parameters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or expired credential.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Credential does not permit this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Immutable version or concurrent assignment conflict.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Artifact checksum or size mismatch.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "revision": {
                    "type": ["string", "null"]
                  },
                  "active_revision": {
                    "type": ["string", "null"]
                  },
                  "status": {
                    "enum": ["ready", "error"]
                  },
                  "error": {
                    "type": ["string", "null"]
                  }
                },
                "required": ["revision", "active_revision", "status"],
                "additionalProperties": false
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9._-]{0,63}$"
            }
          }
        ]
      }
    },
    "/api/models": {
      "get": {
        "operationId": "websiteListModels",
        "summary": "Browse model library",
        "description": " Creation metadata preserves its source; registered_at is the library import/publication date. Historical dates are read from the verified, immutable R2 catalog and matched to artifact checksums. A missing date is never replaced with the import date.",
        "tags": ["Models"],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "models": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ModelCatalogEntry"
                      }
                    }
                  },
                  "required": ["models"],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid metadata, assignment or parameters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or expired credential.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Credential does not permit this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Immutable version or concurrent assignment conflict.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Artifact checksum or size mismatch.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "AccessSession": []
          }
        ],
        "servers": [
          {
            "url": "/",
            "description": "The signed-in website (SITE_HOST), not the API host"
          }
        ]
      }
    },
    "/api/models/devices": {
      "get": {
        "operationId": "websiteListModelDevices",
        "summary": "Inspect model deployment status",
        "description": "",
        "tags": ["Models"],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "devices": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ModelDevice"
                      }
                    }
                  },
                  "required": ["devices"],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid metadata, assignment or parameters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or expired credential.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Credential does not permit this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Immutable version or concurrent assignment conflict.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Artifact checksum or size mismatch.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "AccessSession": []
          }
        ],
        "servers": [
          {
            "url": "/",
            "description": "The signed-in website (SITE_HOST), not the API host"
          }
        ]
      },
      "post": {
        "operationId": "websiteRegisterModelDevice",
        "summary": "Register a model runtime",
        "description": "",
        "tags": ["Models"],
        "responses": {
          "400": {
            "description": "Invalid metadata, assignment or parameters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or expired credential.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Credential does not permit this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Immutable version or concurrent assignment conflict.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Artifact checksum or size mismatch.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "201": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "pattern": "^[a-z0-9][a-z0-9._-]{0,63}$"
                    }
                  },
                  "required": ["id"],
                  "additionalProperties": false
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "pattern": "^[a-z0-9][a-z0-9._-]{0,63}$"
                  }
                },
                "required": ["id"],
                "additionalProperties": false
              }
            }
          }
        },
        "security": [
          {
            "AccessSession": []
          }
        ],
        "servers": [
          {
            "url": "/",
            "description": "The signed-in website (SITE_HOST), not the API host"
          }
        ]
      }
    },
    "/api/models/devices/{id}/deployment": {
      "put": {
        "operationId": "websiteAssignModels",
        "summary": "Deploy exact models and inference settings",
        "description": "Same-origin website request. Pins artifact hashes and parameters. Optimistic concurrency requires previous_revision, including null initially. Empty models unloads the managed cache. This does not enable production inference.",
        "tags": ["Models"],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ModelDeployment"
                }
              }
            }
          },
          "400": {
            "description": "Invalid metadata, assignment or parameters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or expired credential.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Credential does not permit this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Immutable version or concurrent assignment conflict.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Artifact checksum or size mismatch.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "previous_revision": {
                    "type": ["string", "null"]
                  },
                  "models": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/ModelSelection"
                    },
                    "maxItems": 16
                  }
                },
                "required": ["previous_revision", "models"],
                "additionalProperties": false
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9._-]{0,63}$"
            }
          }
        ],
        "security": [
          {
            "AccessSession": []
          }
        ],
        "servers": [
          {
            "url": "/",
            "description": "The signed-in website (SITE_HOST), not the API host"
          }
        ]
      }
    },
    "/api/workshop": {
      "get": {
        "operationId": "GetReadWorkshop",
        "summary": "Read Workshop",
        "description": "Returns {revision,document}. All Access users of this single-camera workspace share saved state. Requires a signed-in website session; mutations require a same-origin request.",
        "tags": ["Workshop"],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid input or unsupported workflow"
          },
          "401": {
            "description": "Sign in or supply a valid API key"
          },
          "403": {
            "description": "Scope, device, camera, or origin is not allowed"
          },
          "409": {
            "description": "Revision, idempotency key, or job lease conflict"
          }
        },
        "security": [],
        "servers": [
          {
            "url": "/",
            "description": "The signed-in website (SITE_HOST), not the API host"
          }
        ],
        "parameters": []
      },
      "put": {
        "operationId": "PutSaveWorkshop",
        "summary": "Save Workshop",
        "description": "Compare-and-swap using revision. A conflict never overwrites another window. Document schema 3 supports buckets, workflows, nodes, edges and viewports. Requires a signed-in website session; mutations require a same-origin request.",
        "tags": ["Workshop"],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid input or unsupported workflow"
          },
          "401": {
            "description": "Sign in or supply a valid API key"
          },
          "403": {
            "description": "Scope, device, camera, or origin is not allowed"
          },
          "409": {
            "description": "Revision, idempotency key, or job lease conflict"
          }
        },
        "security": [],
        "servers": [
          {
            "url": "/",
            "description": "The signed-in website (SITE_HOST), not the API host"
          }
        ],
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "revision": {
                    "type": "integer"
                  },
                  "document": {
                    "type": "object",
                    "additionalProperties": true
                  }
                },
                "required": ["revision", "document"],
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/api/workshop/schedules": {
      "get": {
        "operationId": "GetListWorkshopSchedules",
        "summary": "List Workshop schedule outcomes",
        "description": "Shows each scheduled workflow's latest trigger: started, skipped, or failed, with its message. The scheduler runs every minute; times are UTC. Requires a signed-in website session; mutations require a same-origin request.",
        "tags": ["Workshop"],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid input or unsupported workflow"
          },
          "401": {
            "description": "Sign in or supply a valid API key"
          },
          "403": {
            "description": "Scope, device, camera, or origin is not allowed"
          },
          "409": {
            "description": "Revision, idempotency key, or job lease conflict"
          }
        },
        "security": [],
        "servers": [
          {
            "url": "/",
            "description": "The signed-in website (SITE_HOST), not the API host"
          }
        ],
        "parameters": []
      }
    },
    "/api/workshop/summary": {
      "get": {
        "operationId": "GetWorkshopSummary",
        "summary": "Workshop summary",
        "description": "Counts behind the Workshop overview: per bucket, available images by review state and when one was last added; per workflow, run count, newest run with its status, images by review state, per-class detections with how many images a reviewer accepted or rejected, and images per UTC day. Requires a signed-in website session.",
        "tags": ["Workshop"],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid input or unsupported workflow"
          },
          "401": {
            "description": "Sign in or supply a valid API key"
          },
          "403": {
            "description": "Scope, device, camera, or origin is not allowed"
          },
          "409": {
            "description": "Revision, idempotency key, or job lease conflict"
          }
        },
        "security": [],
        "servers": [
          {
            "url": "/",
            "description": "The signed-in website (SITE_HOST), not the API host"
          }
        ],
        "parameters": []
      }
    },
    "/api/workshop/runtimes": {
      "get": {
        "operationId": "GetListWorkshopRuntimes",
        "summary": "List Workshop runtimes",
        "description": "Shows immutable runtime fingerprints and last processor contact. Requires a signed-in website session; mutations require a same-origin request.",
        "tags": ["Workshop"],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid input or unsupported workflow"
          },
          "401": {
            "description": "Sign in or supply a valid API key"
          },
          "403": {
            "description": "Scope, device, camera, or origin is not allowed"
          },
          "409": {
            "description": "Revision, idempotency key, or job lease conflict"
          }
        },
        "security": [],
        "servers": [
          {
            "url": "/",
            "description": "The signed-in website (SITE_HOST), not the API host"
          }
        ],
        "parameters": []
      },
      "post": {
        "operationId": "PostRegisterWorkshopRuntime",
        "summary": "Register Workshop runtime",
        "description": "Register a new source fingerprint for an existing device. Existing manifests are immutable. Requires a signed-in website session; mutations require a same-origin request.",
        "tags": ["Workshop"],
        "responses": {
          "400": {
            "description": "Invalid input or unsupported workflow"
          },
          "401": {
            "description": "Sign in or supply a valid API key"
          },
          "403": {
            "description": "Scope, device, camera, or origin is not allowed"
          },
          "409": {
            "description": "Revision, idempotency key, or job lease conflict"
          },
          "201": {
            "description": "Success"
          }
        },
        "security": [],
        "servers": [
          {
            "url": "/",
            "description": "The signed-in website (SITE_HOST), not the API host"
          }
        ],
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "device_id": {
                    "type": "string"
                  },
                  "code_sha256": {
                    "type": "string"
                  }
                },
                "required": ["device_id", "code_sha256"],
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/api/workshop/runs": {
      "get": {
        "operationId": "GetListWorkshopRuns",
        "summary": "List Workshop runs",
        "description": "Returns the latest 100 runs, or one workflow's with ?workflow=, pinned snapshots, input progress, failures and output image counts, and how many of each run's images are pending, accepted, or rejected. Requires a signed-in website session; mutations require a same-origin request.",
        "tags": ["Workshop"],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid input or unsupported workflow"
          },
          "401": {
            "description": "Sign in or supply a valid API key"
          },
          "403": {
            "description": "Scope, device, camera, or origin is not allowed"
          },
          "409": {
            "description": "Revision, idempotency key, or job lease conflict"
          }
        },
        "security": [],
        "servers": [
          {
            "url": "/",
            "description": "The signed-in website (SITE_HOST), not the API host"
          }
        ],
        "parameters": [
          {
            "name": "workflow",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Only this workflow's runs."
          }
        ]
      },
      "post": {
        "operationId": "PostSubmitWorkshopRun",
        "summary": "Submit Workshop run",
        "description": "A client-generated id makes retries idempotent. Pins the saved graph, model artifacts, parameters, runtime, and inputs. Maximum 100 inputs and 2,000 samples. Supported: full-frame Ultralytics detection/classification; time, weekday, class, confidence and count conditions. Crop and tiled adapters are rejected. Requires a signed-in website session; mutations require a same-origin request. Test mode requires image_limit (1–100), stops sampling at that count, writes only temporary run previews, and never inserts bucket members. Preview access ends one hour after submission or at source expiration, whichever is earlier. Scheduled cleanup removes temporary images and labels.",
        "tags": ["Workshop"],
        "responses": {
          "400": {
            "description": "Invalid input or unsupported workflow"
          },
          "401": {
            "description": "Sign in or supply a valid API key"
          },
          "403": {
            "description": "Scope, device, camera, or origin is not allowed"
          },
          "409": {
            "description": "Revision, idempotency key, or job lease conflict"
          },
          "201": {
            "description": "Success"
          }
        },
        "security": [],
        "servers": [
          {
            "url": "/",
            "description": "The signed-in website (SITE_HOST), not the API host"
          }
        ],
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "workflow_id": {
                    "type": "string"
                  },
                  "runtime_id": {
                    "type": "string"
                  },
                  "revision": {
                    "type": "integer"
                  },
                  "mode": {
                    "type": "string",
                    "enum": ["test", "run"],
                    "default": "run"
                  },
                  "image_limit": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 100,
                    "description": "Required for test mode; omitted for full runs."
                  }
                },
                "required": ["id", "workflow_id", "runtime_id", "revision"],
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/api/workshop/runs/{id}/cancel": {
      "post": {
        "operationId": "PostCancelWorkshopRun",
        "summary": "Cancel Workshop run",
        "description": "Cancels queued and leased shards. In-flight submissions are fenced. Completed output is preserved. Requires a signed-in website session; mutations require a same-origin request.",
        "tags": ["Workshop"],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid input or unsupported workflow"
          },
          "401": {
            "description": "Sign in or supply a valid API key"
          },
          "403": {
            "description": "Scope, device, camera, or origin is not allowed"
          },
          "409": {
            "description": "Revision, idempotency key, or job lease conflict"
          }
        },
        "security": [],
        "servers": [
          {
            "url": "/",
            "description": "The signed-in website (SITE_HOST), not the API host"
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "required": [],
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/api/workshop/buckets/{id}": {
      "get": {
        "operationId": "GetReadBucketContents",
        "summary": "Read bucket contents",
        "description": "Returns up to 500 available items and dataset versions. Every item carries source expiry, capture time, annotation/model provenance, review state, and image URL. Requires a signed-in website session; mutations require a same-origin request. Also returns the bucket-wide accepted count; use /browse for filtering and pagination.",
        "tags": ["Workshop"],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid input or unsupported workflow"
          },
          "401": {
            "description": "Sign in or supply a valid API key"
          },
          "403": {
            "description": "Scope, device, camera, or origin is not allowed"
          },
          "409": {
            "description": "Revision, idempotency key, or job lease conflict"
          }
        },
        "security": [],
        "servers": [
          {
            "url": "/",
            "description": "The signed-in website (SITE_HOST), not the API host"
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      },
      "delete": {
        "operationId": "DeleteWorkshopBucket",
        "summary": "Delete bucket",
        "description": "Permanently removes a labeled bucket, its image/label memberships (including saved items), and dataset versions. Clears its input/output selections in linked workflows and cancels unfinished runs referencing it. Preserves source footage, other bucket memberships, and shared image bytes. Unreferenced retained copies become eligible for cleanup after a one-hour grace period. Camera archive cannot be deleted. Requires a signed-in website session and same-origin request. The confirmed document revision is enforced atomically; stale confirmations return 409 without modifying data.",
        "tags": ["Workshop"],
        "responses": {
          "200": {
            "description": "Deleted; replace local Workshop state with this document and revision",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkshopDeletionResult"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or unsupported workflow"
          },
          "401": {
            "description": "Sign in or supply a valid API key"
          },
          "403": {
            "description": "Scope, device, camera, or origin is not allowed"
          },
          "409": {
            "description": "Revision, idempotency key, or job lease conflict"
          },
          "404": {
            "description": "Already deleted or missing"
          }
        },
        "security": [],
        "servers": [
          {
            "url": "/",
            "description": "The signed-in website (SITE_HOST), not the API host"
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["revision"],
                "properties": {
                  "revision": {
                    "type": "integer",
                    "minimum": 1
                  }
                },
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/api/workshop/items/{id}/review": {
      "put": {
        "operationId": "PutReviewLabeledImage",
        "summary": "Review labeled image",
        "description": "Accept or reject a proposal, optionally replacing its labels: each label's class must be one of the labeling model's classes, and a detection needs a box of four fractions (left, top, right, bottom). Labels that differ from the model's are marked edited. Review never extends retention and existing dataset snapshots do not change. Requires a signed-in website session; mutations require a same-origin request.",
        "tags": ["Workshop"],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid input or unsupported workflow"
          },
          "401": {
            "description": "Sign in or supply a valid API key"
          },
          "403": {
            "description": "Scope, device, camera, or origin is not allowed"
          },
          "409": {
            "description": "Revision, idempotency key, or job lease conflict"
          }
        },
        "security": [],
        "servers": [
          {
            "url": "/",
            "description": "The signed-in website (SITE_HOST), not the API host"
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "review": {
                    "type": "string",
                    "enum": ["pending", "accepted", "rejected"]
                  },
                  "annotations": {
                    "type": "array",
                    "maxItems": 100,
                    "description": "Replacement labels, from the image's current labels.",
                    "items": {
                      "type": "object",
                      "properties": {
                        "class_name": {
                          "type": "string"
                        },
                        "confidence": {
                          "type": "number",
                          "minimum": 0,
                          "maximum": 1
                        },
                        "box": {
                          "type": "array",
                          "items": {
                            "type": "number",
                            "minimum": 0,
                            "maximum": 1
                          },
                          "minItems": 4,
                          "maxItems": 4
                        }
                      },
                      "required": ["class_name", "confidence"]
                    }
                  }
                },
                "required": ["review"],
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/api/workshop/items/{id}/save": {
      "post": {
        "operationId": "PostRetainLabeledImage",
        "summary": "Retain labeled image",
        "description": "Copies and checksum-verifies image bytes outside the expiring prefix, then atomically retains the image, labels and provenance. Original video is not retained. Repeated saves are idempotent. Create a new dataset version after saving. Requires a signed-in website session; mutations require a same-origin request.",
        "tags": ["Workshop"],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid input or unsupported workflow"
          },
          "401": {
            "description": "Sign in or supply a valid API key"
          },
          "403": {
            "description": "Scope, device, camera, or origin is not allowed"
          },
          "409": {
            "description": "Revision, idempotency key, or job lease conflict"
          }
        },
        "security": [],
        "servers": [
          {
            "url": "/",
            "description": "The signed-in website (SITE_HOST), not the API host"
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "required": [],
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/api/workshop/items/{id}/image": {
      "get": {
        "operationId": "GetReadLabeledImage",
        "summary": "Read labeled image",
        "description": "Returns JPEG bytes only while available. Private browser cache for at most one day and no longer than image expiry. Requires a signed-in website session; mutations require a same-origin request.",
        "tags": ["Workshop"],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or unsupported workflow"
          },
          "401": {
            "description": "Sign in or supply a valid API key"
          },
          "403": {
            "description": "Scope, device, camera, or origin is not allowed"
          },
          "409": {
            "description": "Revision, idempotency key, or job lease conflict"
          }
        },
        "security": [],
        "servers": [
          {
            "url": "/",
            "description": "The signed-in website (SITE_HOST), not the API host"
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/api/workshop/buckets/{id}/versions": {
      "post": {
        "operationId": "PostCreateDatasetVersion",
        "summary": "Create dataset version",
        "description": "Pins latest accepted proposals for each media identity, exact annotation/provenance, output class mapping and camera/day-grouped 80/10/10 splits. One task; no image limit. The version expires when its first unsaved member expires. Requires a signed-in website session; mutations require a same-origin request.",
        "tags": ["Workshop"],
        "responses": {
          "400": {
            "description": "Invalid input or unsupported workflow"
          },
          "401": {
            "description": "Sign in or supply a valid API key"
          },
          "403": {
            "description": "Scope, device, camera, or origin is not allowed"
          },
          "409": {
            "description": "Revision, idempotency key, or job lease conflict"
          },
          "201": {
            "description": "Success"
          }
        },
        "security": [],
        "servers": [
          {
            "url": "/",
            "description": "The signed-in website (SITE_HOST), not the API host"
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  },
                  "include_rejected": {
                    "type": "boolean",
                    "description": "Also freeze images reviewed No. Every item has review accepted or rejected; a rejected item keeps the labels that were rejected."
                  }
                },
                "required": ["id", "name"],
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/api/workshop/versions/{id}": {
      "get": {
        "operationId": "GetReadDatasetVersion",
        "summary": "Read dataset version",
        "description": "Returns manifest, SHA-256 and availability. Expired versions cannot be downloaded. Requires a signed-in website session; mutations require a same-origin request.",
        "tags": ["Workshop"],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid input or unsupported workflow"
          },
          "401": {
            "description": "Sign in or supply a valid API key"
          },
          "403": {
            "description": "Scope, device, camera, or origin is not allowed"
          },
          "409": {
            "description": "Revision, idempotency key, or job lease conflict"
          }
        },
        "security": [],
        "servers": [
          {
            "url": "/",
            "description": "The signed-in website (SITE_HOST), not the API host"
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/v1/workshop/versions/{id}": {
      "get": {
        "operationId": "GetDownloadDatasetManifest",
        "summary": "Download dataset manifest",
        "description": "Requires footage:read for every source camera. The manifest contains ordered class_names, normalized annotations, media_path URLs, checksums, provenance, expiration and pinned splits. class_id indexes class_names; model_class_id retains the original checkpoint ID.",
        "tags": ["Workshop"],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid input or unsupported workflow"
          },
          "401": {
            "description": "Sign in or supply a valid API key"
          },
          "403": {
            "description": "Scope, device, camera, or origin is not allowed"
          },
          "409": {
            "description": "Revision, idempotency key, or job lease conflict"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/v1/workshop/items/{id}/image": {
      "get": {
        "operationId": "GetDownloadDatasetImage",
        "summary": "Download dataset image",
        "description": "Requires a footage:read or agent key for the source camera. Use the same Bearer key with the manifest media_path; verify the manifest SHA-256 for each image.",
        "tags": ["Workshop"],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or unsupported workflow"
          },
          "401": {
            "description": "Sign in or supply a valid API key"
          },
          "403": {
            "description": "Scope, device, camera, or origin is not allowed"
          },
          "409": {
            "description": "Revision, idempotency key, or job lease conflict"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/v1/workshop/claim": {
      "post": {
        "operationId": "PostClaimWorkshopJob",
        "summary": "Claim Workshop job",
        "description": "Requires workshop:run restricted to the registered device and camera. Only manually submitted jobs for the exact source fingerprint are claimed. Lease is five minutes, at most three claims per shard.",
        "tags": ["Workshop"],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid input or unsupported workflow"
          },
          "401": {
            "description": "Sign in or supply a valid API key"
          },
          "403": {
            "description": "Scope, device, camera, or origin is not allowed"
          },
          "409": {
            "description": "Revision, idempotency key, or job lease conflict"
          }
        },
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "runtime_id": {
                    "type": "string"
                  },
                  "code_sha256": {
                    "type": "string"
                  }
                },
                "required": ["runtime_id", "code_sha256"],
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/v1/workshop/jobs/{id}/heartbeat": {
      "post": {
        "operationId": "PostRenewWorkshopLease",
        "summary": "Renew Workshop lease",
        "description": "Renews only the current generation and token, never beyond source expiration.",
        "tags": ["Workshop"],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid input or unsupported workflow"
          },
          "401": {
            "description": "Sign in or supply a valid API key"
          },
          "403": {
            "description": "Scope, device, camera, or origin is not allowed"
          },
          "409": {
            "description": "Revision, idempotency key, or job lease conflict"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Lease-Token",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Lease-Generation",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "required": [],
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/v1/workshop/jobs/{id}/input": {
      "get": {
        "operationId": "GetDownloadPinnedJobInput",
        "summary": "Download pinned job input",
        "description": "Requires the current lease. Streams the exact raw recording or existing labeled image.",
        "tags": ["Workshop"],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or unsupported workflow"
          },
          "401": {
            "description": "Sign in or supply a valid API key"
          },
          "403": {
            "description": "Scope, device, camera, or origin is not allowed"
          },
          "409": {
            "description": "Revision, idempotency key, or job lease conflict"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Lease-Token",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Lease-Generation",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/v1/workshop/jobs/{id}/models/{sha}": {
      "get": {
        "operationId": "GetDownloadPinnedJobModel",
        "summary": "Download pinned job model",
        "description": "Requires the current lease and a checksum present in the run snapshot.",
        "tags": ["Workshop"],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or unsupported workflow"
          },
          "401": {
            "description": "Sign in or supply a valid API key"
          },
          "403": {
            "description": "Scope, device, camera, or origin is not allowed"
          },
          "409": {
            "description": "Revision, idempotency key, or job lease conflict"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sha",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Lease-Token",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Lease-Generation",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/v1/workshop/jobs/{id}/images/{sha}": {
      "put": {
        "operationId": "PutUploadDerivedFrame",
        "summary": "Upload derived frame",
        "description": "Requires the current lease. JPEG up to 8 MiB, bytes verified against path SHA-256. Expiry is inherited from input. Canonical bytes are reused for matching checksum and expiration.",
        "tags": ["Workshop"],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid input or unsupported workflow"
          },
          "401": {
            "description": "Sign in or supply a valid API key"
          },
          "403": {
            "description": "Scope, device, camera, or origin is not allowed"
          },
          "409": {
            "description": "Revision, idempotency key, or job lease conflict"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sha",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Lease-Token",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Lease-Generation",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "image/jpeg": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            }
          }
        }
      }
    },
    "/v1/workshop/jobs/{id}/complete": {
      "post": {
        "operationId": "PostCommitWorkshopResults",
        "summary": "Commit Workshop results",
        "description": "All scheduled samples must be accounted for, including negative frames and empty slots. Validates model classes, boxes, source window, code fingerprint and uploaded bytes. Commits proposals exactly once for the active lease.",
        "tags": ["Workshop"],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid input or unsupported workflow"
          },
          "401": {
            "description": "Sign in or supply a valid API key"
          },
          "403": {
            "description": "Scope, device, camera, or origin is not allowed"
          },
          "409": {
            "description": "Revision, idempotency key, or job lease conflict"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "generation": {
                    "type": "integer"
                  },
                  "lease_token": {
                    "type": "string"
                  },
                  "code_sha256": {
                    "type": "string"
                  },
                  "sampled_frames": {
                    "type": "integer"
                  },
                  "empty_slots": {
                    "type": "array",
                    "items": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 599
                    },
                    "maxItems": 600,
                    "description": "Ascending slot numbers the recorder skipped: no frame falls inside them, and a later frame proves the gap. sampled_frames plus these slots must equal the scheduled samples, and no frame may share a slot with another or with an empty slot."
                  },
                  "frames": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "bucket_id": {
                          "type": "string"
                        },
                        "model_node": {
                          "type": "string"
                        },
                        "pts": {
                          "type": "integer"
                        },
                        "time_base": {
                          "type": "array",
                          "items": {
                            "type": "integer"
                          },
                          "minItems": 2,
                          "maxItems": 2
                        },
                        "offset": {
                          "type": "number"
                        },
                        "width": {
                          "type": "integer"
                        },
                        "height": {
                          "type": "integer"
                        },
                        "sha256": {
                          "type": "string"
                        },
                        "annotations": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "description": "Normalized detections. A box may name its object's track in track_id, one of this frame's tracks."
                        },
                        "tracks": {
                          "type": "array",
                          "maxItems": 1000,
                          "items": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "description": "Video jobs only: the tracks of this frame's boxes, each named by at least one box. id is \"<job id>:<n>\"; motion is moving, stationary or brief; speed is frame heights per second or null; start, end and detections; optional clipped; path lists [t, x, y, width, height, class_id, confidence] per detection; optional scan (frames kept by change) has fps, searched, seen, speed, first, last and samples [t, x|null, y|null, peak] near this frame. Stored in the image's provenance."
                        }
                      },
                      "required": [
                        "bucket_id",
                        "model_node",
                        "pts",
                        "time_base",
                        "offset",
                        "width",
                        "height",
                        "sha256",
                        "annotations"
                      ],
                      "additionalProperties": false
                    },
                    "maxItems": 600
                  }
                },
                "required": ["generation", "lease_token", "code_sha256", "sampled_frames", "frames"],
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/v1/workshop/jobs/{id}/fail": {
      "post": {
        "operationId": "PostFailWorkshopJob",
        "summary": "Fail Workshop job",
        "description": "Records a bounded failure code; failed output is never treated as zero detections.",
        "tags": ["Workshop"],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid input or unsupported workflow"
          },
          "401": {
            "description": "Sign in or supply a valid API key"
          },
          "403": {
            "description": "Scope, device, camera, or origin is not allowed"
          },
          "409": {
            "description": "Revision, idempotency key, or job lease conflict"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "generation": {
                    "type": "integer"
                  },
                  "lease_token": {
                    "type": "string"
                  },
                  "error": {
                    "type": "string",
                    "enum": ["download_failed", "decode_failed", "model_failed", "processor_failed"]
                  }
                },
                "required": ["generation", "lease_token", "error"],
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/api/workshop/runs/{id}": {
      "get": {
        "operationId": "GetWorkshopRunDetail",
        "summary": "Read run progress and latest output",
        "description": "Returns mode, status, expected_images, processed_images, jobs with active stage/node and errors, pinned workflow, and up to 100 latest authenticated preview/result URLs. Poll every 1.5 seconds while queued or running; stop at terminal state. Test output is isolated from bucket review/save/export APIs. Requires a signed-in website session.",
        "tags": ["Workshop"],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid input or unsupported workflow"
          },
          "401": {
            "description": "Sign in or supply a valid API key"
          },
          "403": {
            "description": "Scope, device, camera, or origin is not allowed"
          },
          "409": {
            "description": "Revision, idempotency key, or job lease conflict"
          },
          "404": {
            "description": "Run not found"
          }
        },
        "security": [],
        "servers": [
          {
            "url": "/",
            "description": "The signed-in website (SITE_HOST), not the API host"
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/api/workshop/runs/{id}/review": {
      "get": {
        "operationId": "GetRunReview",
        "summary": "Read a run for review",
        "description": "Everything the run review page needs: the run, the recordings it read (for the player), the pinned models' classes, and up to 1,000 of its saved images oldest first, each with labels, provenance, review state, and image URL. Requires a signed-in website session.",
        "tags": ["Workshop"],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid input or unsupported workflow"
          },
          "401": {
            "description": "Sign in or supply a valid API key"
          },
          "403": {
            "description": "Scope, device, camera, or origin is not allowed"
          },
          "409": {
            "description": "Revision, idempotency key, or job lease conflict"
          }
        },
        "security": [],
        "servers": [
          {
            "url": "/",
            "description": "The signed-in website (SITE_HOST), not the API host"
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/api/workshop/runs/{id}/previews/{item}/image": {
      "get": {
        "operationId": "GetWorkshopRunPreviewImage",
        "summary": "Read a temporary run preview",
        "description": "Authenticated temporary image. Rejects expired previews and prior lease attempts. Test previews expire within one hour; the image is not eligible for bucket save or dataset export. Cache-Control: private, no-store.",
        "tags": ["Workshop"],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or unsupported workflow"
          },
          "401": {
            "description": "Sign in or supply a valid API key"
          },
          "403": {
            "description": "Scope, device, camera, or origin is not allowed"
          },
          "409": {
            "description": "Revision, idempotency key, or job lease conflict"
          }
        },
        "security": [],
        "servers": [
          {
            "url": "/",
            "description": "The signed-in website (SITE_HOST), not the API host"
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "item",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/v1/workshop/jobs/{id}/progress": {
      "post": {
        "operationId": "PostWorkshopJobProgress",
        "summary": "Publish fenced job progress and a verified preview",
        "description": "Requires the active device/camera-scoped Workshop lease. Stages may preserve the current processed count. Advancing it requires one uploaded frame with sequence=processed−1; publish in order. Repeated identical events are safe; stale attempts and cancelled jobs are rejected. This does not commit bucket results.",
        "tags": ["Workshop"],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid input or unsupported workflow"
          },
          "401": {
            "description": "Sign in or supply a valid API key"
          },
          "403": {
            "description": "Scope, device, camera, or origin is not allowed"
          },
          "409": {
            "description": "Revision, idempotency key, or job lease conflict"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["generation", "lease_token", "phase", "node_id", "processed"],
                "properties": {
                  "generation": {
                    "type": "integer"
                  },
                  "lease_token": {
                    "type": "string"
                  },
                  "phase": {
                    "type": "string",
                    "enum": ["downloading", "loading_model", "processing", "uploading", "finalizing"]
                  },
                  "node_id": {
                    "type": ["string", "null"]
                  },
                  "processed": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 600
                  },
                  "sequence": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 599
                  },
                  "frame": {
                    "type": "object",
                    "description": "One frame with the same contract as complete.frames; uploaded JPEG SHA, final model, classes, normalized boxes and source timing are verified."
                  },
                  "empty": {
                    "type": "boolean",
                    "description": "True when the slots up to processed held no frame (a recorder gap), which advances processed without a frame."
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/workshop/workflows/{id}/deletion": {
      "get": {
        "operationId": "GetWorkflowDeletionPreview",
        "summary": "Preview workflow deletion",
        "description": "Returns the current revision, affected content counts, unfinished runs, and linked workflows. Counts can change as runs progress. Requires a signed-in website session.",
        "tags": ["Workshop"],
        "responses": {
          "200": {
            "description": "Deletion preview",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkshopDeletionPreview"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or unsupported workflow"
          },
          "401": {
            "description": "Sign in or supply a valid API key"
          },
          "403": {
            "description": "Scope, device, camera, or origin is not allowed"
          },
          "409": {
            "description": "Revision, idempotency key, or job lease conflict"
          },
          "404": {
            "description": "Already deleted or missing"
          }
        },
        "security": [],
        "servers": [
          {
            "url": "/",
            "description": "The signed-in website (SITE_HOST), not the API host"
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/api/workshop/workflows/{id}": {
      "delete": {
        "operationId": "DeleteWorkshopWorkflow",
        "summary": "Delete workflow",
        "description": "Permanently removes a workflow and cancels queued/leased jobs. Keeps immutable run history, completed results, and output buckets. Requires a signed-in website session and same-origin request. The confirmed document revision is enforced atomically; stale confirmations return 409 without modifying data.",
        "tags": ["Workshop"],
        "responses": {
          "200": {
            "description": "Deleted; replace local Workshop state with this document and revision",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkshopDeletionResult"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or unsupported workflow"
          },
          "401": {
            "description": "Sign in or supply a valid API key"
          },
          "403": {
            "description": "Scope, device, camera, or origin is not allowed"
          },
          "409": {
            "description": "Revision, idempotency key, or job lease conflict"
          },
          "404": {
            "description": "Already deleted or missing"
          }
        },
        "security": [],
        "servers": [
          {
            "url": "/",
            "description": "The signed-in website (SITE_HOST), not the API host"
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["revision"],
                "properties": {
                  "revision": {
                    "type": "integer",
                    "minimum": 1
                  }
                },
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/api/workshop/buckets/{id}/deletion": {
      "get": {
        "operationId": "GetBucketDeletionPreview",
        "summary": "Preview bucket deletion",
        "description": "Returns the current revision, affected content counts, unfinished runs, and linked workflows. Counts can change as runs progress. Requires a signed-in website session.",
        "tags": ["Workshop"],
        "responses": {
          "200": {
            "description": "Deletion preview",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkshopDeletionPreview"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or unsupported workflow"
          },
          "401": {
            "description": "Sign in or supply a valid API key"
          },
          "403": {
            "description": "Scope, device, camera, or origin is not allowed"
          },
          "409": {
            "description": "Revision, idempotency key, or job lease conflict"
          },
          "404": {
            "description": "Already deleted or missing"
          }
        },
        "security": [],
        "servers": [
          {
            "url": "/",
            "description": "The signed-in website (SITE_HOST), not the API host"
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/v1/workshop/runs/{id}/previews/{item}/image": {
      "get": {
        "operationId": "GetDownloadRunPreviewImage",
        "summary": "Download a temporary run preview",
        "description": "A test-run preview or an agent photo, for a footage:read or agent key with its camera. Previews expire an hour after the run starts.",
        "tags": ["Workshop"],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or unsupported workflow"
          },
          "401": {
            "description": "Sign in or supply a valid API key"
          },
          "403": {
            "description": "Scope, device, camera, or origin is not allowed"
          },
          "409": {
            "description": "Revision, idempotency key, or job lease conflict"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "item",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/v1/mcp": {
      "post": {
        "operationId": "PostAgentMcp",
        "summary": "Agent MCP server",
        "description": "Model Context Protocol (Streamable HTTP, stateless JSON). Send one JSON-RPC 2.0 message per request with an agent key. Tools: guide, footage, workflows, runs, images, buckets, models; guides and skills are also resources and prompts. Notifications return 202. GET returns 405: there is no server stream.",
        "tags": ["Agent"],
        "responses": {
          "200": {
            "description": "Success"
          },
          "401": {
            "description": "Sign in or supply a valid API key"
          },
          "403": {
            "description": "Scope, device, camera, or origin is not allowed"
          },
          "202": {
            "description": "Notification accepted"
          }
        },
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["jsonrpc", "method"],
                "properties": {
                  "jsonrpc": {
                    "const": "2.0"
                  },
                  "id": {
                    "type": ["string", "integer"]
                  },
                  "method": {
                    "type": "string"
                  },
                  "params": {
                    "type": "object"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/workshop/buckets/{id}/browse": {
      "get": {
        "operationId": "BrowseWorkshopBucket",
        "summary": "Browse bucket detections",
        "description": "Returns items with image URLs, total filtered count, cursor (null at the end), and bucket-wide run, camera and class facets. Filters apply before pagination. Cursor capture time and ID use a creation snapshot to exclude new arrivals. Signed-in website session required.",
        "tags": ["Workshop"],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid input or unsupported workflow"
          },
          "401": {
            "description": "Sign in or supply a valid API key"
          },
          "403": {
            "description": "Scope, device, camera, or origin is not allowed"
          },
          "409": {
            "description": "Revision, idempotency key, or job lease conflict"
          },
          "404": {
            "description": "Bucket or image expired or missing"
          }
        },
        "security": [],
        "servers": [
          {
            "url": "/",
            "description": "The signed-in website (SITE_HOST), not the API host"
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "description": "Search label, camera, run name or ID.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "run",
            "in": "query",
            "description": "Only this run ID.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "camera",
            "in": "query",
            "description": "Only this camera.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "class",
            "in": "query",
            "description": "Exact label; confidence limits apply to the same object.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from",
            "in": "query",
            "description": "Inclusive capture timestamp in ISO 8601.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "description": "Exclusive capture timestamp in ISO 8601.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Opaque cursor from the previous page; keep other filters unchanged.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "review",
            "in": "query",
            "description": "Optional review status.",
            "schema": {
              "type": "string",
              "enum": ["pending", "accepted", "rejected"]
            }
          },
          {
            "name": "sort",
            "in": "query",
            "description": "Capture-time ordering.",
            "schema": {
              "type": "string",
              "enum": ["newest", "oldest"],
              "default": "newest"
            }
          },
          {
            "name": "saved",
            "in": "query",
            "description": "Only retained images.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Images per page.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 120
            }
          },
          {
            "name": "min_confidence",
            "in": "query",
            "description": "Inclusive confidence boundary; at least one matching object must be in range.",
            "schema": {
              "type": "number",
              "minimum": 0,
              "maximum": 1
            }
          },
          {
            "name": "max_confidence",
            "in": "query",
            "description": "Inclusive confidence boundary; at least one matching object must be in range.",
            "schema": {
              "type": "number",
              "minimum": 0,
              "maximum": 1
            }
          },
          {
            "name": "min_objects",
            "in": "query",
            "description": "Inclusive object-count boundary per image.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 100
            }
          },
          {
            "name": "max_objects",
            "in": "query",
            "description": "Inclusive object-count boundary per image.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 100
            }
          }
        ]
      }
    },
    "/api/workshop/items/{id}": {
      "get": {
        "operationId": "GetWorkshopItemDetail",
        "summary": "Open a detection with its recording",
        "description": "Returns item, original recording reference (or null), immutable run name/creation time, and allowed labeling-model classes. Follows nested source provenance for images processed through multiple buckets. Signed-in website session required.",
        "tags": ["Workshop"],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid input or unsupported workflow"
          },
          "401": {
            "description": "Sign in or supply a valid API key"
          },
          "403": {
            "description": "Scope, device, camera, or origin is not allowed"
          },
          "409": {
            "description": "Revision, idempotency key, or job lease conflict"
          },
          "404": {
            "description": "Bucket or image expired or missing"
          }
        },
        "security": [],
        "servers": [
          {
            "url": "/",
            "description": "The signed-in website (SITE_HOST), not the API host"
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/api/workshop/items/{id}/thumbnail": {
      "get": {
        "operationId": "GetWorkshopThumbnail",
        "summary": "Read a small detection thumbnail",
        "description": "Returns a 256px or 512px JPEG, optionally cropped around the highest-confidence box. Original bytes are unchanged. Each thumbnail is made once and kept until its image expires or its labels change, so later reads from any browser return the kept copy. Authenticated, private browser cache for at most one day and no longer than image expiry; ETag supports revalidation. Signed-in website session required.",
        "tags": ["Workshop"],
        "responses": {
          "200": {
            "description": "JPEG thumbnail",
            "content": {
              "image/jpeg": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or unsupported workflow"
          },
          "401": {
            "description": "Sign in or supply a valid API key"
          },
          "403": {
            "description": "Scope, device, camera, or origin is not allowed"
          },
          "409": {
            "description": "Revision, idempotency key, or job lease conflict"
          },
          "404": {
            "description": "Bucket or image expired or missing"
          },
          "304": {
            "description": "Thumbnail unchanged"
          },
          "503": {
            "description": "Image transforms unavailable; use the original image endpoint."
          }
        },
        "security": [],
        "servers": [
          {
            "url": "/",
            "description": "The signed-in website (SITE_HOST), not the API host"
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "mode",
            "in": "query",
            "description": "Whole frame or object crop.",
            "schema": {
              "type": "string",
              "enum": ["frame", "object"],
              "default": "frame"
            }
          },
          {
            "name": "size",
            "in": "query",
            "description": "Maximum thumbnail side.",
            "schema": {
              "type": "integer",
              "enum": [256, 512],
              "default": 256
            }
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "svk_…",
        "description": "API key created in the website. Never put it in a URL."
      },
      "AccessSession": {
        "type": "apiKey",
        "in": "cookie",
        "name": "CF_Authorization",
        "description": "Signed-in Cloudflare Access browser session; checked by Access and the Worker."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "string"
          }
        }
      },
      "ApiKey": {
        "type": "object",
        "required": [
          "id",
          "name",
          "prefix",
          "scope",
          "cameras",
          "created_at",
          "expires_at",
          "last_used_at",
          "rotated_at",
          "revoked_at"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "prefix": {
            "type": "string",
            "description": "A masked identifier; never a usable key."
          },
          "scope": {
            "type": "string",
            "enum": ["footage:read", "processor:run", "models:write", "models:sync", "workshop:run", "agent"]
          },
          "cameras": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "last_used_at": {
            "type": ["string", "null"],
            "format": "date-time"
          },
          "rotated_at": {
            "type": ["string", "null"],
            "format": "date-time"
          },
          "revoked_at": {
            "type": ["string", "null"],
            "format": "date-time"
          },
          "pipeline_id": {
            "type": "string",
            "description": "Present only on processor keys. Immutable pipeline fingerprint."
          },
          "device_id": {
            "type": ["string", "null"],
            "description": "Only device sync keys. Restricts model downloads to this device assignment."
          }
        }
      },
      "Recording": {
        "type": "object",
        "required": [
          "object_key",
          "cam",
          "start",
          "size",
          "sha256",
          "duration_s",
          "frames",
          "width",
          "height",
          "bitrate",
          "codec",
          "download_url"
        ],
        "properties": {
          "object_key": {
            "type": "string"
          },
          "cam": {
            "type": "string"
          },
          "start": {
            "type": "string",
            "format": "date-time"
          },
          "size": {
            "type": "integer",
            "minimum": 0,
            "description": "Original file bytes."
          },
          "sha256": {
            "type": "string",
            "description": "Hex SHA-256 of the original file."
          },
          "duration_s": {
            "type": ["number", "null"]
          },
          "frames": {
            "type": ["integer", "null"]
          },
          "width": {
            "type": ["integer", "null"]
          },
          "height": {
            "type": ["integer", "null"]
          },
          "bitrate": {
            "type": ["integer", "null"]
          },
          "codec": {
            "type": ["string", "null"]
          },
          "download_url": {
            "type": "string",
            "format": "uri",
            "description": "Authenticated streaming endpoint; send the same Bearer key. Supports byte ranges. This is not a presigned URL."
          }
        }
      },
      "Cameras": {
        "type": "object",
        "required": ["cameras"],
        "properties": {
          "cameras": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "Identity": {
        "type": "object",
        "required": ["key_id", "scope", "cameras"],
        "properties": {
          "key_id": {
            "type": "string"
          },
          "scope": {
            "type": "string",
            "enum": ["footage:read", "processor:run", "models:write", "models:sync", "workshop:run", "agent"]
          },
          "cameras": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "pipeline_id": {
            "type": "string",
            "description": "Present only on processor keys. Immutable pipeline fingerprint."
          },
          "device_id": {
            "type": ["string", "null"],
            "description": "Only device sync keys. Restricts model downloads to this device assignment."
          }
        }
      },
      "RecordingPage": {
        "type": "object",
        "required": ["camera", "from", "to", "as_of", "recordings", "next_cursor", "next_url"],
        "properties": {
          "camera": {
            "type": "string"
          },
          "from": {
            "type": "string",
            "format": "date-time"
          },
          "to": {
            "type": "string",
            "format": "date-time"
          },
          "as_of": {
            "type": "string",
            "format": "date-time"
          },
          "recordings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Recording"
            }
          },
          "next_cursor": {
            "type": ["string", "null"]
          },
          "next_url": {
            "type": ["string", "null"],
            "format": "uri"
          }
        }
      },
      "KeyList": {
        "type": "object",
        "required": ["keys", "cameras", "max_active_keys", "api_base_url", "environment"],
        "properties": {
          "keys": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ApiKey"
            }
          },
          "cameras": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "max_active_keys": {
            "type": "integer"
          },
          "api_base_url": {
            "type": "string",
            "format": "uri"
          },
          "environment": {
            "type": "string",
            "enum": ["development", "production"]
          },
          "pipelines": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Registered pipelines; empty while inference is disabled."
          },
          "devices": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "KeyResult": {
        "type": "object",
        "required": ["key"],
        "properties": {
          "key": {
            "$ref": "#/components/schemas/ApiKey"
          }
        }
      },
      "CreatedKey": {
        "type": "object",
        "required": ["key", "token"],
        "properties": {
          "key": {
            "$ref": "#/components/schemas/ApiKey"
          },
          "token": {
            "type": "string",
            "description": "Shown only in this response. Store it securely; it cannot be retrieved again."
          }
        }
      },
      "Lease": {
        "type": "object",
        "properties": {
          "generation": {
            "type": "integer",
            "minimum": 1
          },
          "lease_token": {
            "type": "string",
            "format": "uuid"
          }
        },
        "required": ["generation", "lease_token"]
      },
      "Pipeline": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "model_sha256": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "code_sha256": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "config_sha256": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "config": {
            "type": "object"
          }
        },
        "required": ["id", "model_sha256", "code_sha256", "config_sha256", "config"]
      },
      "JobInput": {
        "type": "object",
        "properties": {
          "object_key": {
            "type": "string"
          },
          "cam": {
            "type": "string"
          },
          "start": {
            "type": "string",
            "format": "date-time"
          },
          "size": {
            "type": "integer",
            "minimum": 0,
            "description": "Original file bytes."
          },
          "sha256": {
            "type": "string",
            "description": "Hex SHA-256 of the original file."
          },
          "duration_s": {
            "type": ["number", "null"]
          },
          "frames": {
            "type": ["integer", "null"]
          },
          "width": {
            "type": ["integer", "null"]
          },
          "height": {
            "type": ["integer", "null"]
          },
          "codec": {
            "type": ["string", "null"]
          },
          "download_url": {
            "type": "string",
            "format": "uri",
            "description": "Authenticated streaming endpoint; send the same Bearer key. Supports byte ranges. This is not a presigned URL."
          }
        },
        "required": [
          "object_key",
          "cam",
          "start",
          "size",
          "sha256",
          "duration_s",
          "frames",
          "width",
          "height",
          "codec",
          "download_url"
        ]
      },
      "ClaimedJob": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "generation": {
            "type": "integer"
          },
          "lease_token": {
            "type": "string"
          },
          "lease_until": {
            "type": "string",
            "format": "date-time"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "input": {
            "$ref": "#/components/schemas/JobInput"
          },
          "pipeline": {
            "$ref": "#/components/schemas/Pipeline"
          }
        },
        "required": ["id", "generation", "lease_token", "lease_until", "expires_at", "input", "pipeline"]
      },
      "Track": {
        "type": "object",
        "properties": {
          "track_id": {
            "type": "integer",
            "minimum": 1
          },
          "label": {
            "type": "string",
            "enum": ["plane", "wildlife", "meteor", "unresolved"]
          },
          "score": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "points": {
            "type": "array",
            "minItems": 2,
            "maxItems": 4000,
            "items": {
              "type": "object",
              "properties": {
                "t": {
                  "type": "number",
                  "minimum": 0,
                  "description": "Seconds from the recording first presentation timestamp."
                },
                "box": {
                  "type": "array",
                  "minItems": 4,
                  "maxItems": 4,
                  "items": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 1
                  },
                  "description": "Normalized x1,y1,x2,y2."
                },
                "score": {
                  "type": "number",
                  "minimum": 0,
                  "maximum": 1
                }
              },
              "required": ["t", "box", "score"]
            }
          },
          "evidence_sha256": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "classification_basis": {
            "type": "string",
            "description": "Baseline outputs uncalibrated_model_prediction; labels are not independently verified."
          }
        },
        "required": ["track_id", "label", "score", "points"]
      },
      "InferenceResult": {
        "type": "object",
        "properties": {
          "provenance": {
            "type": "object",
            "properties": {
              "input_sha256": {
                "type": "string",
                "pattern": "^[a-f0-9]{64}$"
              },
              "model_sha256": {
                "type": "string",
                "pattern": "^[a-f0-9]{64}$"
              },
              "code_sha256": {
                "type": "string",
                "pattern": "^[a-f0-9]{64}$"
              },
              "config_sha256": {
                "type": "string",
                "pattern": "^[a-f0-9]{64}$"
              },
              "runtime": {
                "type": "object"
              }
            },
            "required": ["input_sha256", "model_sha256", "code_sha256", "config_sha256", "runtime"]
          },
          "metrics": {
            "type": "object",
            "properties": {
              "processed_seconds": {
                "type": "number"
              },
              "sampled_frames": {
                "type": "integer"
              },
              "decoded_frames": {
                "type": "integer"
              },
              "elapsed_seconds": {
                "type": "number"
              }
            },
            "required": ["processed_seconds", "sampled_frames", "decoded_frames", "elapsed_seconds"]
          },
          "tracks": {
            "type": "array",
            "maxItems": 256,
            "items": {
              "$ref": "#/components/schemas/Track"
            }
          }
        },
        "required": ["provenance", "metrics", "tracks"]
      },
      "ModelArtifact": {
        "type": "object",
        "properties": {
          "sha256": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "bytes": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1073741824
          },
          "filename": {
            "type": "string"
          },
          "format": {
            "type": "string"
          }
        },
        "required": ["sha256", "bytes", "filename", "format"],
        "additionalProperties": false
      },
      "ArtifactChunk": {
        "type": "object",
        "properties": {
          "sha256": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "bytes": {
            "type": "integer",
            "minimum": 1,
            "maximum": 8388608
          }
        },
        "required": ["sha256", "bytes"],
        "additionalProperties": false
      },
      "ModelVersion": {
        "type": "object",
        "properties": {
          "family": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9._-]{0,63}$"
          },
          "version": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9._-]{0,63}$"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "task": {
            "enum": ["object-detection", "image-classification", "feature-classification", "image-encoder"]
          },
          "adapter": {
            "enum": ["ultralytics", "unsupported"]
          },
          "classes": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "integer",
                  "minimum": 0
                },
                "name": {
                  "type": "string"
                }
              },
              "required": ["id", "name"],
              "additionalProperties": false
            },
            "maxItems": 1000
          },
          "input": {
            "type": "object",
            "additionalProperties": true
          },
          "evaluations": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            },
            "maxItems": 50
          },
          "caveats": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "maxItems": 50
          },
          "dependencies": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "maxItems": 16
          },
          "artifacts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ModelArtifact"
            },
            "maxItems": 16
          },
          "source_manifest": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "Optional original training/checkpoint creation time, including timezone. Separate from the date a version was added to the registry."
          }
        },
        "required": [
          "family",
          "version",
          "name",
          "description",
          "task",
          "adapter",
          "classes",
          "input",
          "evaluations",
          "artifacts"
        ],
        "additionalProperties": false
      },
      "ModelParameters": {
        "type": "object",
        "properties": {
          "imgsz": {
            "type": "integer",
            "minimum": 32,
            "maximum": 2048,
            "multipleOf": 32
          },
          "confidence": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "iou": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "device": {
            "enum": ["auto", "cpu", "mps", "cuda"]
          }
        },
        "required": ["imgsz", "confidence", "iou", "device"],
        "additionalProperties": false
      },
      "ModelSelection": {
        "type": "object",
        "properties": {
          "slot": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9._-]{0,63}$"
          },
          "family": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9._-]{0,63}$"
          },
          "version": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9._-]{0,63}$"
          },
          "sha256": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "parameters": {
            "$ref": "#/components/schemas/ModelParameters"
          }
        },
        "required": ["slot", "family", "version", "sha256", "parameters"],
        "additionalProperties": false
      },
      "DeployedModel": {
        "type": "object",
        "properties": {
          "slot": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9._-]{0,63}$"
          },
          "model": {
            "$ref": "#/components/schemas/ModelVersion"
          },
          "artifact": {
            "$ref": "#/components/schemas/ModelArtifact"
          },
          "parameters": {
            "$ref": "#/components/schemas/ModelParameters"
          }
        },
        "required": ["slot", "model", "artifact", "parameters"],
        "additionalProperties": false
      },
      "ModelDeployment": {
        "type": "object",
        "properties": {
          "schema_version": {
            "const": 1
          },
          "device_id": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9._-]{0,63}$"
          },
          "revision": {
            "type": "string",
            "format": "uuid"
          },
          "models": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DeployedModel"
            },
            "maxItems": 16
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": ["schema_version", "device_id", "revision", "models", "created_at"],
        "additionalProperties": false
      },
      "ModelDevice": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9._-]{0,63}$"
          },
          "revision": {
            "type": ["string", "null"]
          },
          "reported_revision": {
            "type": ["string", "null"]
          },
          "status": {
            "enum": ["pending", "ready", "error"]
          },
          "error": {
            "type": ["string", "null"]
          },
          "last_seen_at": {
            "type": ["string", "null"]
          },
          "updated_at": {
            "type": "string"
          },
          "deployment": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/ModelDeployment"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "id",
          "revision",
          "reported_revision",
          "status",
          "error",
          "last_seen_at",
          "updated_at",
          "deployment"
        ],
        "additionalProperties": false
      },
      "ModelCreationMetadata": {
        "type": "object",
        "readOnly": true,
        "properties": {
          "date": {
            "type": ["string", "null"],
            "description": "Original recorded date or timestamp. Legacy checkpoint timestamps may omit a timezone; no timezone is inferred."
          },
          "source": {
            "enum": ["publisher", "checkpoint", "legacy-manifest", null]
          },
          "legacy_date": {
            "type": ["string", "null"],
            "description": "Preserved legacy training date, including when it differs from the checkpoint."
          },
          "status": {
            "enum": ["available", "not-recorded", "unavailable"]
          }
        },
        "required": ["date", "source", "legacy_date", "status"],
        "additionalProperties": false
      },
      "ModelCatalogEntry": {
        "type": "object",
        "properties": {
          "family": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9._-]{0,63}$"
          },
          "version": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9._-]{0,63}$"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "task": {
            "enum": ["object-detection", "image-classification", "feature-classification", "image-encoder"]
          },
          "adapter": {
            "enum": ["ultralytics", "unsupported"]
          },
          "classes": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "integer",
                  "minimum": 0
                },
                "name": {
                  "type": "string"
                }
              },
              "required": ["id", "name"],
              "additionalProperties": false
            },
            "maxItems": 1000
          },
          "input": {
            "type": "object",
            "additionalProperties": true
          },
          "evaluations": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            },
            "maxItems": 50
          },
          "caveats": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "maxItems": 50
          },
          "dependencies": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "maxItems": 16
          },
          "artifacts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ModelArtifact"
            },
            "maxItems": 16
          },
          "source_manifest": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "Optional original training/checkpoint creation time, including timezone. Separate from the date a version was added to the registry."
          },
          "registered_at": {
            "type": "string",
            "format": "date-time",
            "readOnly": true,
            "description": "When the immutable version was added to the registry."
          },
          "creation": {
            "$ref": "#/components/schemas/ModelCreationMetadata"
          }
        },
        "required": [
          "family",
          "version",
          "name",
          "description",
          "task",
          "adapter",
          "classes",
          "input",
          "evaluations",
          "artifacts",
          "registered_at",
          "creation"
        ],
        "additionalProperties": false
      },
      "WorkshopDeletionPreview": {
        "type": "object",
        "required": [
          "kind",
          "id",
          "name",
          "revision",
          "images",
          "saved_images",
          "versions",
          "active_runs",
          "linked_workflows"
        ],
        "properties": {
          "kind": {
            "type": "string",
            "enum": ["workflow", "bucket"]
          },
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "revision": {
            "type": "integer",
            "minimum": 1
          },
          "images": {
            "type": "integer",
            "minimum": 0
          },
          "saved_images": {
            "type": "integer",
            "minimum": 0
          },
          "versions": {
            "type": "integer",
            "minimum": 0
          },
          "active_runs": {
            "type": "integer",
            "minimum": 0
          },
          "linked_workflows": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["id", "name"],
              "properties": {
                "id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "WorkshopDeletionResult": {
        "type": "object",
        "required": ["revision", "document"],
        "properties": {
          "revision": {
            "type": "integer",
            "minimum": 1
          },
          "document": {
            "type": "object",
            "description": "Complete updated Workshop schema 3 document, including cleared bucket selections.",
            "additionalProperties": true
          }
        }
      }
    }
  }
}