{"openapi":"3.0.3","info":{"title":"queryd-cf","version":"0.1.0-cf","description":"Broadcast audio search API. Create a job with remote file URLs or an upload session, then poll the job, matches, logs, and callback deliveries.\n\n## Authentication\nAuthentication is optional. When the Worker has an `ADMIN_TOKEN` configured, send it as either `Authorization: Bearer <token>` or `x-admin-token: <token>`. When `ADMIN_TOKEN` is not configured, `/api/*` is open.\nUse the Authorize button above to set either credential. `/api/health` and `/api/health/ready` never require authentication."},"servers":[{"url":"/","description":"Current host"}],"tags":[{"name":"Health","description":"Unauthenticated liveness and readiness probes."},{"name":"Uploads","description":"Two-step upload flow: create a session, upload each file, then complete the session."},{"name":"Jobs","description":"Create and manage search jobs."},{"name":"System","description":"Runtime limits and service statistics."}],"security":[{"bearerAuth":[]},{"adminToken":[]},{}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"ADMIN_TOKEN","description":"Send `Authorization: Bearer <ADMIN_TOKEN>`."},"adminToken":{"type":"apiKey","in":"header","name":"x-admin-token","description":"Alternative to the Bearer header: send the `ADMIN_TOKEN` directly in `x-admin-token`."}},"schemas":{"Scope":{"type":"object","required":["streams","dates"],"properties":{"streams":{"type":"object","required":["mode"],"properties":{"mode":{"type":"string","enum":["all","ids","country"]},"ids":{"type":"array","items":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$"},"description":"Required when mode is ids.","example":["056d990a-7b48-4e95-b91e-ce59ca2701e8"]},"country":{"type":"string","description":"Required when mode is country. Matched case-insensitively against stream metadata.country.","example":"Uganda"}}},"dates":{"type":"object","required":["mode"],"properties":{"mode":{"type":"string","enum":["date","range"]},"date":{"type":"string","format":"date","description":"Required when mode is date.","example":"2026-11-20"},"from":{"type":"string","format":"date","description":"Required when mode is range.","example":"2026-11-01"},"to":{"type":"string","format":"date","description":"Required when mode is range. Must be on or after from; ranges are limited to 366 days.","example":"2026-11-07"}}},"daily_time_window":{"type":"object","required":["start","end"],"description":"Optional local-time window. Both start and end are required when this object is present. The planner also includes the day before the requested date so recordings that span midnight are covered.","properties":{"start":{"type":"string","pattern":"^([01][0-9]|2[0-3]):[0-5][0-9]$","example":"06:00","description":"Inclusive start time in HH:MM (24-hour)."},"end":{"type":"string","pattern":"^([01][0-9]|2[0-3]):[0-5][0-9]$","example":"10:00","description":"Exclusive end time in HH:MM (24-hour)."},"basis":{"type":"string","enum":["stream_local"],"default":"stream_local","description":"Only stream_local is supported."},"match":{"type":"string","enum":["overlap"],"default":"overlap","description":"Only overlap is supported."}}}}},"CreateJobRequest":{"type":"object","required":["scope"],"description":"Provide exactly one file source: `files` (remote URLs) or `upload_id` (a completed upload session). `file_ids` narrows an upload session to specific files. `scope` is always required.","properties":{"files":{"type":"array","minItems":1,"description":"Remote audio files. Provide this or upload_id, not both.","items":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"Absolute http(s) URL. Credentials in the URL are rejected.","example":"https://example.com/clip.ogg"},"id":{"oneOf":[{"type":"string"},{"type":"integer"}]},"name":{"type":"string","example":"clip.ogg"}}}},"upload_id":{"type":"string","description":"An upload session id. Provide this or files, not both."},"file_ids":{"type":"array","items":{"type":"string"},"description":"Optional subset of upload file ids to use."},"scope":{"$ref":"#/components/schemas/Scope"},"callback_url":{"type":"string","format":"uri","description":"Optional absolute http(s) webhook URL. Deliveries are signed with X-Queryd-Signature."}}},"CreateUploadRequest":{"type":"object","required":["files"],"description":"Supported audio extensions: mp3, wav, flac, ogg, opus, m4a, aac, wma, aiff, aif. File count and size limits come from GET /api/settings.","properties":{"files":{"type":"array","minItems":1,"items":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"clip.ogg"},"size":{"type":"integer","description":"Expected size in bytes.","example":1234},"content_type":{"type":"string","example":"audio/ogg"}}}}}},"UploadSession":{"type":"object","properties":{"upload_id":{"type":"string","example":"8238fd3c9c6794b8d96c54a8"},"files":{"type":"array","items":{"type":"object","properties":{"file_id":{"type":"string","example":"1"},"name":{"type":"string","example":"clip.ogg"},"key":{"type":"string","example":"staging/8238fd3c9c6794b8d96c54a8/1.ogg"},"upload_url":{"type":"string","format":"uri"},"presigned":{"type":"boolean","example":true},"expires_at":{"type":"string","format":"date-time"}}}}}},"UploadComplete":{"type":"object","properties":{"upload_id":{"type":"string"},"files":{"type":"array","items":{"type":"object","properties":{"file_id":{"type":"string"},"name":{"type":"string"},"key":{"type":"string"},"size_bytes":{"type":"integer"},"content_type":{"type":"string"}}}}}},"Job":{"type":"object","properties":{"id":{"type":"integer","example":42},"status":{"type":"string","enum":["queued","planning","querying","paused","completed","failed","cancelled"]},"stage":{"type":"string","example":"query"},"progress":{"type":"number","format":"float","minimum":0,"maximum":1,"example":0.95},"error":{"type":"string"},"scope":{"type":"string","description":"The normalized scope JSON string.","example":"{\"streams\":{\"mode\":\"ids\",\"ids\":[\"...\"]},\"dates\":{\"mode\":\"date\",\"date\":\"2026-11-20\"}}"},"callback_url":{"type":"string","format":"uri"},"requested_by":{"type":"string","example":"api"},"total_files":{"type":"integer","example":1},"total_indexes":{"type":"integer","example":2},"processed_indexes":{"type":"integer","example":2},"total_matches":{"type":"integer","example":17},"cancel_requested":{"type":"boolean"},"pause_requested":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"started_at":{"type":"string","format":"date-time","nullable":true},"completed_at":{"type":"string","format":"date-time","nullable":true},"updated_at":{"type":"string","format":"date-time"}}},"JobFile":{"type":"object","properties":{"id":{"type":"integer","example":7},"query_id":{"type":"integer","example":42},"original_name":{"type":"string","example":"clip.ogg"},"stored_name":{"type":"string"},"source_id":{"type":"string"},"source_url":{"type":"string","format":"uri"},"staging_key":{"type":"string","example":"staging/8238fd3c9c6794b8d96c54a8/1.ogg"},"size_bytes":{"type":"integer","example":1234},"content_type":{"type":"string","example":"audio/ogg"},"created_at":{"type":"string","format":"date-time"}}},"IndexTask":{"type":"object","properties":{"id":{"type":"integer","example":11},"query_id":{"type":"integer","example":42},"stream_id":{"type":"string","example":"056d990a-7b48-4e95-b91e-ce59ca2701e8"},"date":{"type":"string","format":"date","example":"2026-11-20"},"build_id":{"type":"string","example":"20261121T125634Z-9"},"build_prefix":{"type":"string"},"timeline_key":{"type":"string"},"data_key":{"type":"string"},"lock_key":{"type":"string"},"timezone":{"type":"string","example":"Africa/Nairobi"},"status":{"type":"string","enum":["pending","running","querying","done","failed","skipped"]},"size_bytes":{"type":"integer","example":33174474},"matches":{"type":"integer","example":5},"error":{"type":"string"},"attempts":{"type":"integer","example":1},"next_attempt_at":{"type":"string","format":"date-time","nullable":true},"started_at":{"type":"string","format":"date-time","nullable":true},"completed_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"Match":{"type":"object","properties":{"id":{"type":"integer"},"query_id":{"type":"integer"},"index_task_id":{"type":"integer"},"file_id":{"type":"integer"},"file_ref_id":{"type":"string"},"file_name":{"type":"string"},"file_url":{"type":"string"},"query_path":{"type":"string"},"resource_id":{"type":"string"},"stream_id":{"type":"string"},"date":{"type":"string","format":"date"},"recording_start_time":{"type":"string","format":"date-time"},"occurrence_time":{"type":"string","format":"date-time"},"reference_start_ms":{"type":"integer"},"reference_stop_ms":{"type":"integer"},"match_count":{"type":"integer"},"score":{"type":"number","format":"float"},"timeline_start_ms":{"type":"integer"},"timeline_end_ms":{"type":"integer"},"created_at":{"type":"string","format":"date-time"}}},"RuntimeSettings":{"type":"object","properties":{"max_upload_files":{"type":"integer","example":20},"max_upload_mb":{"type":"integer","example":200},"max_total_upload_mb":{"type":"integer","example":1000},"max_indexes_per_job":{"type":"integer","example":100},"max_index_size_gb":{"type":"integer","example":8},"allow_private_urls":{"type":"boolean","example":false},"max_attempts":{"type":"integer","example":3},"retry_initial_seconds":{"type":"integer","example":30},"retry_max_seconds":{"type":"integer","example":1800},"jobs_days":{"type":"integer","example":30},"logs_days":{"type":"integer","example":30}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","example":"at least one file URL or upload_id is required"}}},"JobDetail":{"type":"object","properties":{"job":{"$ref":"#/components/schemas/Job"},"files":{"type":"array","items":{"$ref":"#/components/schemas/JobFile"}},"indexes":{"type":"array","items":{"$ref":"#/components/schemas/IndexTask"}}}},"JobList":{"type":"object","properties":{"jobs":{"type":"array","items":{"$ref":"#/components/schemas/Job"}},"counts":{"type":"object","additionalProperties":{"type":"integer"},"example":{"queued":1,"planning":0,"downloading":0,"querying":2,"paused":0,"completed":5,"failed":0,"cancelled":0}}}},"MatchesResponse":{"type":"object","properties":{"matches":{"type":"array","items":{"$ref":"#/components/schemas/Match"}},"total":{"type":"integer","example":17}}},"LogsResponse":{"type":"object","properties":{"entries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"query_id":{"type":"integer"},"index_task_id":{"type":"integer"},"level":{"type":"string"},"stage":{"type":"string"},"message":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}}},"service":{"type":"array","items":{"type":"string"},"description":"Service-level log lines. Only present on GET /api/jobs/logs.","example":[]}}},"CallbacksResponse":{"type":"object","properties":{"deliveries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"query_id":{"type":"integer"},"event":{"type":"string","example":"job.completed"},"url":{"type":"string","format":"uri"},"status_code":{"type":"integer"},"attempt":{"type":"integer"},"success":{"type":"integer"},"error":{"type":"string"},"response_body":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}}}}}},"parameters":{"id":{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"example":42},"uploadId":{"name":"uploadId","in":"path","required":true,"schema":{"type":"string"},"example":"8238fd3c9c6794b8d96c54a8"},"fileId":{"name":"fileId","in":"path","required":true,"schema":{"type":"string"},"example":"1"},"limit":{"name":"limit","in":"query","description":"Page size. Defaults and caps vary by endpoint (jobs 100/500, matches 500/2000, logs 300/2000, callbacks 100/500).","schema":{"type":"integer","minimum":1},"example":100},"offset":{"name":"offset","in":"query","description":"Number of records to skip. Defaults to 0.","schema":{"type":"integer","minimum":0},"example":0},"status":{"name":"status","in":"query","schema":{"type":"string","enum":["queued","planning","querying","paused","completed","failed","cancelled"]}},"fileIdQuery":{"name":"file_id","in":"query","schema":{"type":"integer"},"example":7},"streamIdQuery":{"name":"stream_id","in":"query","schema":{"type":"string"},"example":"056d990a-7b48-4e95-b91e-ce59ca2701e8"},"level":{"name":"level","in":"query","schema":{"type":"string","enum":["debug","info","error"]}},"search":{"name":"search","in":"query","schema":{"type":"string"}}},"responses":{"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid admin token. Only returned when ADMIN_TOKEN is configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/health":{"get":{"tags":["Health"],"summary":"Liveness probe","security":[],"responses":{"200":{"description":"Service is alive","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"version":{"type":"string","example":"0.1.0-cf"},"olaf_version":{"type":"string","example":"2026.10.19"},"uptime_seconds":{"type":"integer","example":0},"storage_configured":{"type":"boolean","example":true}}}}}}}}},"/api/health/ready":{"get":{"tags":["Health"],"summary":"Readiness probe (checks D1 and R2)","security":[],"responses":{"200":{"description":"Ready","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ready"}}}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/uploads":{"post":{"tags":["Uploads"],"summary":"Create an upload session","description":"Returns one upload URL per file. When R2 presign credentials are configured the URL points directly at R2; otherwise it points at the Worker fallback endpoint.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUploadRequest"},"example":{"files":[{"name":"clip.ogg","size":1234,"content_type":"audio/ogg"}]}}}},"responses":{"201":{"description":"Upload session created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadSession"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid admin token. Only returned when ADMIN_TOKEN is configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/uploads/{uploadId}/{fileId}":{"put":{"tags":["Uploads"],"summary":"Upload a file (Worker fallback)","description":"Only used when the upload URL returned by POST /api/uploads points at the Worker.","parameters":[{"name":"uploadId","in":"path","required":true,"schema":{"type":"string"},"example":"8238fd3c9c6794b8d96c54a8"},{"name":"fileId","in":"path","required":true,"schema":{"type":"string"},"example":"1"}],"requestBody":{"required":true,"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"responses":{"200":{"description":"File stored","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"size":{"type":"integer"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid admin token. Only returned when ADMIN_TOKEN is configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"File too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/uploads/{uploadId}/complete":{"post":{"tags":["Uploads"],"summary":"Complete an upload session","description":"Verifies every staging object exists, marks the session complete, and returns the uploaded files.","parameters":[{"name":"uploadId","in":"path","required":true,"schema":{"type":"string"},"example":"8238fd3c9c6794b8d96c54a8"}],"responses":{"200":{"description":"Upload completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadComplete"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid admin token. Only returned when ADMIN_TOKEN is configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/jobs":{"get":{"tags":["Jobs"],"summary":"List jobs","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["queued","planning","querying","paused","completed","failed","cancelled"]}},{"name":"limit","in":"query","description":"Page size. Defaults and caps vary by endpoint (jobs 100/500, matches 500/2000, logs 300/2000, callbacks 100/500).","schema":{"type":"integer","minimum":1},"example":100},{"name":"offset","in":"query","description":"Number of records to skip. Defaults to 0.","schema":{"type":"integer","minimum":0},"example":0}],"responses":{"200":{"description":"Jobs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobList"}}}},"401":{"description":"Missing or invalid admin token. Only returned when ADMIN_TOKEN is configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Jobs"],"summary":"Create a search job","description":"Provide either remote file URLs or a completed upload_id, plus a scope. The job is queued immediately; poll GET /api/jobs/{id} for progress.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateJobRequest"},"examples":{"urlJob":{"summary":"Search a stream for a remote audio file","value":{"files":[{"url":"https://example.com/clip.ogg","name":"clip.ogg"}],"scope":{"streams":{"mode":"ids","ids":["056d990a-7b48-4e95-b91e-ce59ca2701e8"]},"dates":{"mode":"date","date":"2026-11-20"}},"callback_url":"https://example.com/webhooks/queryd"}},"uploadJob":{"summary":"Search using a previously completed upload","value":{"upload_id":"8238fd3c9c6794b8d96c54a8","file_ids":["1"],"scope":{"streams":{"mode":"ids","ids":["056d990a-7b48-4e95-b91e-ce59ca2701e8"]},"dates":{"mode":"date","date":"2026-11-20"}}}},"countryRangeJob":{"summary":"Search all streams in a country over a date range with a daily window","value":{"files":[{"url":"https://example.com/clip.ogg"}],"scope":{"streams":{"mode":"country","country":"Uganda"},"dates":{"mode":"range","from":"2026-11-01","to":"2026-11-07"},"daily_time_window":{"start":"06:00","end":"10:00","basis":"stream_local","match":"overlap"}}}}}}}},"responses":{"201":{"description":"Job created","content":{"application/json":{"schema":{"type":"object","properties":{"job":{"$ref":"#/components/schemas/Job"}}},"example":{"job":{"id":42,"status":"queued","stage":"queued","progress":0,"error":"","scope":"{\"streams\":{\"mode\":\"ids\",\"ids\":[\"056d990a-7b48-4e95-b91e-ce59ca2701e8\"]},\"dates\":{\"mode\":\"date\",\"date\":\"2026-11-20\"}}","callback_url":"","requested_by":"api","total_files":1,"total_indexes":0,"processed_indexes":0,"total_matches":0,"cancel_requested":false,"pause_requested":false,"created_at":"2026-11-22T09:15:05.002Z","started_at":null,"completed_at":null,"updated_at":"2026-11-22T09:15:05.437Z"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid admin token. Only returned when ADMIN_TOKEN is configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/jobs/logs":{"get":{"tags":["Jobs"],"summary":"List logs across all jobs","parameters":[{"name":"level","in":"query","schema":{"type":"string","enum":["debug","info","error"]}},{"name":"search","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Page size. Defaults and caps vary by endpoint (jobs 100/500, matches 500/2000, logs 300/2000, callbacks 100/500).","schema":{"type":"integer","minimum":1},"example":100},{"name":"offset","in":"query","description":"Number of records to skip. Defaults to 0.","schema":{"type":"integer","minimum":0},"example":0}],"responses":{"200":{"description":"Logs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LogsResponse"}}}},"401":{"description":"Missing or invalid admin token. Only returned when ADMIN_TOKEN is configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/jobs/{id}":{"get":{"tags":["Jobs"],"summary":"Get a job with files and index tasks","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"example":42}],"responses":{"200":{"description":"Job detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobDetail"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid admin token. Only returned when ADMIN_TOKEN is configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/jobs/{id}/matches":{"get":{"tags":["Jobs"],"summary":"List matches for a job","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"example":42},{"name":"file_id","in":"query","schema":{"type":"integer"},"example":7},{"name":"stream_id","in":"query","schema":{"type":"string"},"example":"056d990a-7b48-4e95-b91e-ce59ca2701e8"},{"name":"limit","in":"query","description":"Page size. Defaults and caps vary by endpoint (jobs 100/500, matches 500/2000, logs 300/2000, callbacks 100/500).","schema":{"type":"integer","minimum":1},"example":100},{"name":"offset","in":"query","description":"Number of records to skip. Defaults to 0.","schema":{"type":"integer","minimum":0},"example":0}],"responses":{"200":{"description":"Matches","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatchesResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid admin token. Only returned when ADMIN_TOKEN is configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/jobs/{id}/logs":{"get":{"tags":["Jobs"],"summary":"List logs for a job","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"example":42},{"name":"level","in":"query","schema":{"type":"string","enum":["debug","info","error"]}},{"name":"search","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Page size. Defaults and caps vary by endpoint (jobs 100/500, matches 500/2000, logs 300/2000, callbacks 100/500).","schema":{"type":"integer","minimum":1},"example":100},{"name":"offset","in":"query","description":"Number of records to skip. Defaults to 0.","schema":{"type":"integer","minimum":0},"example":0}],"responses":{"200":{"description":"Logs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LogsResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid admin token. Only returned when ADMIN_TOKEN is configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/jobs/{id}/callbacks":{"get":{"tags":["Jobs"],"summary":"List callback deliveries for a job","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"example":42},{"name":"limit","in":"query","description":"Page size. Defaults and caps vary by endpoint (jobs 100/500, matches 500/2000, logs 300/2000, callbacks 100/500).","schema":{"type":"integer","minimum":1},"example":100}],"responses":{"200":{"description":"Deliveries","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallbacksResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid admin token. Only returned when ADMIN_TOKEN is configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/jobs/{id}/pause":{"post":{"tags":["Jobs"],"summary":"Pause a job","description":"Stops running containers, leaves pending indexes queued, and emits a job.paused callback.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"example":42}],"responses":{"200":{"description":"Paused or already terminal","content":{"application/json":{"schema":{"type":"object","properties":{"job":{"$ref":"#/components/schemas/Job"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid admin token. Only returned when ADMIN_TOKEN is configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/jobs/{id}/resume":{"post":{"tags":["Jobs"],"summary":"Resume a paused job","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"example":42}],"responses":{"200":{"description":"Resumed","content":{"application/json":{"schema":{"type":"object","properties":{"job":{"$ref":"#/components/schemas/Job"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid admin token. Only returned when ADMIN_TOKEN is configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Job is not paused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/jobs/{id}/cancel":{"post":{"tags":["Jobs"],"summary":"Cancel a job","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"example":42}],"responses":{"200":{"description":"Cancelled or cancellation requested","content":{"application/json":{"schema":{"type":"object","properties":{"job":{"$ref":"#/components/schemas/Job"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid admin token. Only returned when ADMIN_TOKEN is configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/stats":{"get":{"tags":["System"],"summary":"Service statistics and limits","responses":{"200":{"description":"Stats","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"version":{"type":"string","example":"0.1.0-cf"},"olaf_version":{"type":"string","example":"2026.10.19"},"uptime_seconds":{"type":"integer","example":0},"jobs":{"type":"object","additionalProperties":{"type":"integer"},"example":{"queued":0,"planning":0,"downloading":0,"querying":0,"paused":0,"completed":1,"failed":0,"cancelled":0}},"active_jobs":{"type":"integer","example":0},"max_active_jobs":{"type":"integer","example":4},"indexes_queried":{"type":"integer","example":12},"matches_total":{"type":"integer","example":471},"storage":{"type":"object","properties":{"configured":{"type":"boolean","example":true},"bucket":{"type":"string","example":"broadcast-index-archive"},"uploads_bucket":{"type":"string","example":"spaza-queryd-uploads"}}},"limits":{"$ref":"#/components/schemas/RuntimeSettings"},"disk":{"type":"object","properties":{"free_bytes":{"type":"integer","example":0},"total_bytes":{"type":"integer","example":0}}}}}}}},"401":{"description":"Missing or invalid admin token. Only returned when ADMIN_TOKEN is configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/settings":{"get":{"tags":["System"],"summary":"Runtime limits","responses":{"200":{"description":"Settings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RuntimeSettings"}}}},"401":{"description":"Missing or invalid admin token. Only returned when ADMIN_TOKEN is configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}