{"openapi":"3.1.0","info":{"title":"Travinci Actors API","version":"1.0.0 (actors 0.2.0)","description":"Self-hosted collection platform. Authenticate with `Authorization: Bearer tva_<prefix>_<secret>`.\n\nEffective access = workspace permissions ∩ key permissions ∩ actor availability. Runs, schedules, datasets, exports, comparisons and entity history of actors a key may not use respond 404.\n\nStarting a run returns 202 immediately: poll `GET /runs/{id}` (or receive a webhook) and read `run.collection.state` — an HTTP success is never a statement about collection success.\n\nEvery response carries `X-Request-Id`; errors are `{error, code, requestId, details?}`. Branch on `code`.\n\nUnknown values are `null`; missing metrics are never reported as 0."},"servers":[{"url":"/api/v1"}],"security":[{"bearer":[]}],"tags":[{"name":"Connection"},{"name":"Actors"},{"name":"Runs"},{"name":"Results"},{"name":"Archive"},{"name":"Sources"},{"name":"Schedules"},{"name":"Comparisons"},{"name":"Webhooks"},{"name":"Keys"},{"name":"Workspace"},{"name":"Administration"},{"name":"Platform administration"}],"paths":{"/connection":{"get":{"tags":["Connection"],"operationId":"testConnection","summary":"Validate the key and the service without starting a job","x-required-scopes":[],"security":[{"bearer":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Connection"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"503":{"$ref":"#/components/responses/E503"}}}},"/archive/runs/{id}":{"get":{"tags":["Archive"],"operationId":"getRunArchive","summary":"Archive status of a run: counts by state, thumbnail states, uploaded bytes and per-item object references","x-required-scopes":["datasets:read"],"security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Resource ID"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":10000,"default":5000}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunArchive"}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}}},"/archive/items/{id}/thumbnail":{"get":{"tags":["Archive"],"operationId":"getArchiveThumbnail","summary":"Archived thumbnail: 302 to a short-lived presigned bucket URL; json=1 returns the URL, inline=1 streams the image same-origin","x-required-scopes":["datasets:read"],"security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Resource ID"},{"name":"json","in":"query","required":false,"schema":{"type":"string","enum":["1"]},"description":"Return {url, expiresAt} instead of redirecting"},{"name":"inline","in":"query","required":false,"schema":{"type":"string","enum":["1"]},"description":"Stream the image bytes"}],"responses":{"200":{"description":"json=1: the presigned URL; inline=1: the image","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArchiveThumbnailUrl"}},"image/*":{"schema":{"type":"string","format":"binary"}}}},"302":{"description":"Location: presigned URL valid for ARCHIVE_PRESIGN_SECONDS (Cache-Control: private, no-store)","headers":{"Location":{"schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"503":{"$ref":"#/components/responses/E503"}}}},"/capabilities":{"get":{"tags":["Connection"],"operationId":"getCapabilities","summary":"Effective permissions, allowed actors with input schemas, credential requirements, collection status, limits and usage","x-required-scopes":[],"security":[{"bearer":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Capabilities"}}}},"401":{"$ref":"#/components/responses/E401"},"503":{"$ref":"#/components/responses/E503"}}}},"/me":{"get":{"tags":["Connection"],"operationId":"whoAmI","summary":"Workspace and key identity","x-required-scopes":[],"security":[{"bearer":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/E401"}}}},"/actors":{"get":{"tags":["Actors"],"operationId":"listActors","summary":"Public actor catalogue (no key required)","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"actors":{"type":"array","items":{"$ref":"#/components/schemas/Actor"}}}}}}}}}},"/health":{"get":{"tags":["Connection"],"operationId":"health","summary":"Liveness (no key)","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/health/ready":{"get":{"tags":["Connection"],"operationId":"ready","summary":"Readiness of database, queue and workers (no key)","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"503":{"description":"Degraded","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/session":{"get":{"tags":["Connection"],"operationId":"sessionStatus","summary":"Dashboard operator sign-in mode and session state (browser only)","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"tags":["Connection"],"operationId":"signIn","summary":"Dashboard operator sign-in: sets an HttpOnly SameSite=Strict session cookie (12 h admin session). Account mode (a super-admin account exists): { email, password }, 5 failures in 15 min lock the client out (429). Automatic when DASHBOARD_LOGIN=local and no account exists; otherwise { password }","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}}},"delete":{"tags":["Connection"],"operationId":"signOut","summary":"Revoke the dashboard session","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/profile":{"get":{"tags":["Connection"],"operationId":"getProfile","summary":"Super-admin profile (browser session only): the account, the current workspace and every workspace","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/E401"}}},"patch":{"tags":["Connection"],"operationId":"updateProfile","summary":"Change the super-admin email and/or password: { currentPassword, email?, password? }; a new password signs out the account's other sessions","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"}}}},"/profile/switch":{"post":{"tags":["Connection"],"operationId":"switchWorkspace","summary":"Switch the dashboard session to another workspace: { workspaceId } (super-admin session)","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}}},"/activate":{"get":{"tags":["Connection"],"operationId":"checkActivation","summary":"Check a customer activation link: ?token= → { email, expiresAt } (does not consume it)","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/E400"}}},"post":{"tags":["Connection"],"operationId":"activateAccount","summary":"Set a customer password with a single-use, expiring activation link: { token, password }","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/E400"},"403":{"$ref":"#/components/responses/E403"}}}},"/admin/workspaces":{"get":{"tags":["Administration"],"operationId":"adminListWorkspaces","summary":"Super Admin: every workspace with members, limits (null = unlimited) and usage, plus the customer preset","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"}}},"post":{"tags":["Administration"],"operationId":"adminCreateWorkspace","summary":"Super Admin: create a workspace, its owner (existing or new customer), membership and quota policy in one transaction; returns a single-use activation link for a new owner","responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}}},"/admin/workspaces/{id}":{"get":{"tags":["Administration"],"operationId":"adminGetWorkspace","summary":"Super Admin: one workspace","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Resource ID"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}},"patch":{"tags":["Administration"],"operationId":"adminUpdateWorkspace","summary":"Super Admin: { name?, limits? (partial; null = unlimited, 0 = none), allowedActors?, allowedScopes?, disabled? }; reductions apply to new work only","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Resource ID"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}}},"/admin/workspaces/{id}/members":{"get":{"tags":["Administration"],"operationId":"adminListMembers","summary":"Super Admin: workspace members","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Resource ID"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}},"put":{"tags":["Administration"],"operationId":"adminSetMember","summary":"Super Admin: add or update a member { accountId } | { email, displayName? }, role owner|member, scopes?, actors?","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Resource ID"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}},"delete":{"tags":["Administration"],"operationId":"adminRemoveMember","summary":"Super Admin: remove a member (?accountId=); its sessions in the workspace end, data is kept","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Resource ID"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}}},"/admin/accounts":{"get":{"tags":["Administration"],"operationId":"adminListAccounts","summary":"Super Admin: every account with its memberships","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"}}},"post":{"tags":["Administration"],"operationId":"adminCreateAccount","summary":"Super Admin: create a customer account { email, displayName? } with a single-use activation link","responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"}}}},"/admin/accounts/{id}":{"patch":{"tags":["Administration"],"operationId":"adminUpdateAccount","summary":"Super Admin: suspend or reactivate a customer { status }; suspension ends its sessions at once","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Resource ID"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}}},"/admin/accounts/{id}/activation":{"post":{"tags":["Administration"],"operationId":"adminActivationLink","summary":"Super Admin: a new single-use activation link for a customer (earlier unused links stop working)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Resource ID"}],"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}}},"/openapi.json":{"get":{"tags":["Connection"],"operationId":"openApi","summary":"This document","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/runs":{"get":{"tags":["Runs"],"operationId":"listRuns","summary":"Runs of actors the key may use, newest first","x-required-scopes":["runs:read"],"security":[{"bearer":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["QUEUED","RUNNING","SUCCEEDED","FAILED","CANCELLED"]}},{"name":"actorId","in":"query","required":false,"schema":{"type":"string"}},{"name":"scheduleId","in":"query","required":false,"schema":{"type":"string"}},{"name":"before","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Page: createdAt of the last run seen"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"runs":{"type":"array","items":{"$ref":"#/components/schemas/Run"}}}}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"}}},"post":{"tags":["Runs"],"operationId":"startRun","summary":"Validate input, enforce access and queue a run (returns immediately)","x-required-scopes":["runs:write"],"security":[{"bearer":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"Retries with the same key return the original run (200, created=false)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["actorId","input"],"properties":{"actorId":{"type":"string","enum":["linkedin-profile","linkedin-posts","instagram-posts","facebook-posts","tiktok-posts","x-posts","youtube-videos","web-business","linkedin-company","news-feeds","google-trends-rss"]},"input":{"$ref":"#/components/schemas/RunInput"},"collection":{"type":"object","description":"Shared collection preferences. Policy-approved public sources are served from shared snapshots unless sharing is off.","properties":{"sharing":{"type":"string","enum":["auto","off"],"default":"auto"},"maxAgeSeconds":{"type":"integer","minimum":60,"maximum":2592000}}}}}}}},"responses":{"200":{"description":"Idempotent replay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunCreated"}}}},"202":{"description":"Accepted (queued). Not a statement about collection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunCreated"}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"},"503":{"$ref":"#/components/responses/E503"}}}},"/runs/{id}":{"get":{"tags":["Runs"],"operationId":"getRun","summary":"Status, progress, per-source diagnostics with coverage, completeness and dataset reference (logs with logs:read; shared runs add sharing.references and sharing.physical)","x-required-scopes":["runs:read"],"security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Resource ID"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"run":{"$ref":"#/components/schemas/Run"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}},"logs":{"type":"array","items":{"$ref":"#/components/schemas/Log"}},"sharing":{"type":"object","description":"Shared runs only","properties":{"references":{"type":"array","items":{"$ref":"#/components/schemas/SnapshotReference"}},"physical":{"$ref":"#/components/schemas/PhysicalAttribution"}}}}}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}}},"/runs/{id}/cancel":{"post":{"tags":["Runs"],"operationId":"cancelRun","summary":"Cancel (queued: immediately; running: within one heartbeat, records kept)","x-required-scopes":["runs:cancel"],"security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Resource ID"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"run":{"$ref":"#/components/schemas/Run"}}}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}}},"/runs/{id}/logs":{"get":{"tags":["Runs"],"operationId":"getRunLogs","summary":"Redacted diagnostics","x-required-scopes":["runs:read","logs:read"],"security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Resource ID"},{"name":"after","in":"query","required":false,"schema":{"type":"integer","minimum":0},"description":"Return logs after this id"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":2000}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"logs":{"type":"array","items":{"$ref":"#/components/schemas/Log"}},"nextAfter":{"type":["integer","null"]}}}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}}},"/runs/{id}/dataset":{"get":{"tags":["Results"],"operationId":"listResults","summary":"Paginated records with filters and explicit totals (format=csv|ndjson streams the complete export)","x-required-scopes":["datasets:read"],"security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Resource ID"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":5000,"default":500}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0}},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["json","csv","ndjson"],"default":"json"},"description":"csv/ndjson require datasets:export"},{"name":"recordType","in":"query","required":false,"schema":{"type":"string","enum":["post","comment","profile","business","account","article","trend"]}},{"name":"platform","in":"query","required":false,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":200},"description":"Full-text match on the record"},{"name":"since","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"until","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"sourceKey","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResultsPage"}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}}},"/runs/{id}/export":{"get":{"tags":["Results"],"operationId":"exportResults","summary":"Complete export of the (filtered) dataset; truncation above EXPORT_MAX_ITEMS is declared, never silent","x-required-scopes":["datasets:read","datasets:export"],"security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Resource ID"},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["json","csv","ndjson"],"default":"json"}},{"name":"recordType","in":"query","required":false,"schema":{"type":"string","enum":["post","comment","profile","business","account","article","trend"]}},{"name":"platform","in":"query","required":false,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":200},"description":"Full-text match on the record"},{"name":"since","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"until","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"sourceKey","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Streamed export","headers":{"X-Total-Count":{"schema":{"type":"string"}},"X-Exported-Count":{"schema":{"type":"string"}},"X-Export-Complete":{"schema":{"type":"string"}},"X-Export-Truncated":{"schema":{"type":"string"}},"X-Run-Status":{"schema":{"type":"string"}},"X-Final-Dataset":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportJson"}},"application/x-ndjson":{"schema":{"type":"string"}},"text/csv":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}}},"/schedules":{"get":{"tags":["Schedules"],"operationId":"listSchedules","x-required-scopes":["schedules:read"],"security":[{"bearer":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"schedules":{"type":"array","items":{"$ref":"#/components/schemas/Schedule"}}}}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"}}},"post":{"tags":["Schedules"],"operationId":"createSchedule","summary":"Create a live schedule; it runs with the creating key’s authority, re-checked at every occurrence","x-required-scopes":["schedules:write"],"security":[{"bearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduleInput"}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"schedule":{"$ref":"#/components/schemas/Schedule"}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}}}},"/schedules/{id}":{"get":{"tags":["Schedules"],"operationId":"getSchedule","x-required-scopes":["schedules:read"],"security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Resource ID"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}},"patch":{"tags":["Schedules"],"operationId":"updateSchedule","x-required-scopes":["schedules:write"],"security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Resource ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}},"delete":{"tags":["Schedules"],"operationId":"deleteSchedule","x-required-scopes":["schedules:write"],"security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Resource ID"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}}},"/schedules/{id}/pause":{"post":{"tags":["Schedules"],"operationId":"pauseSchedule","x-required-scopes":["schedules:write"],"security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Resource ID"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}}},"/schedules/{id}/resume":{"post":{"tags":["Schedules"],"operationId":"resumeSchedule","summary":"Resume; the caller becomes the owner (needs runs:write)","x-required-scopes":["schedules:write","runs:write"],"security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Resource ID"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}}},"/schedules/{id}/trigger":{"post":{"tags":["Schedules"],"operationId":"triggerSchedule","summary":"Run now with the caller’s authority","x-required-scopes":["runs:write","schedules:read"],"security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Resource ID"}],"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunCreated"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"}}}},"/schedules/{id}/events":{"get":{"tags":["Schedules"],"operationId":"listScheduleEvents","x-required-scopes":["schedules:read"],"security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Resource ID"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}}},"/comparisons":{"get":{"tags":["Comparisons"],"operationId":"compareRuns","summary":"Field and metric changes between two runs (both must be visible to the key)","x-required-scopes":["comparisons:read"],"security":[{"bearer":[]}],"parameters":[{"name":"base","in":"query","required":false,"schema":{"type":"string"}},{"name":"target","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"includeUnchanged","in":"query","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Comparison"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}}},"/comparisons/schedule/{id}":{"get":{"tags":["Comparisons"],"operationId":"compareLatestScheduleRuns","x-required-scopes":["comparisons:read"],"security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Resource ID"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Comparison"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}}},"/entities":{"get":{"tags":["Comparisons"],"operationId":"listEntities","summary":"Entities observed by runs of actors the key may use","x-required-scopes":["comparisons:read"],"security":[{"bearer":[]}],"parameters":[{"name":"platform","in":"query","required":false,"schema":{"type":"string"}},{"name":"type","in":"query","required":false,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"}}}},"/entities/history":{"get":{"tags":["Comparisons"],"operationId":"entityHistory","x-required-scopes":["comparisons:read"],"security":[{"bearer":[]}],"parameters":[{"name":"key","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}}},"/usage":{"get":{"tags":["Workspace"],"operationId":"getUsage","summary":"Consumption and remaining applicable limits (workspace and calling key)","x-required-scopes":["usage:read"],"security":[{"bearer":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Usage"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"}}}},"/webhooks":{"get":{"tags":["Webhooks"],"operationId":"listWebhooks","x-required-scopes":["webhooks:manage"],"security":[{"bearer":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"endpoints":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}},"events":{"type":"array","items":{"type":"string"}}}}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"}}},"post":{"tags":["Webhooks"],"operationId":"createWebhook","summary":"Register a completion webhook; the signing secret is returned once","x-required-scopes":["webhooks:manage"],"security":[{"bearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"HTTPS, public address"},"events":{"type":"array","items":{"type":"string","enum":["run.succeeded","run.failed","run.cancelled","records.expired","records.deleted","records.restricted"]}},"description":{"type":"string"}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"endpoint":{"allOf":[{"$ref":"#/components/schemas/WebhookEndpoint"},{"type":"object","properties":{"secret":{"type":"string"}}}]}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"503":{"$ref":"#/components/responses/E503"}}}},"/webhooks/{id}":{"get":{"tags":["Webhooks"],"operationId":"getWebhook","summary":"Endpoint with recent deliveries and attempt logs","x-required-scopes":["webhooks:manage"],"security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Resource ID"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"endpoint":{"$ref":"#/components/schemas/WebhookEndpoint"},"deliveries":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}}}}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}},"patch":{"tags":["Webhooks"],"operationId":"updateWebhook","x-required-scopes":["webhooks:manage"],"security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Resource ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"events":{"type":"array"},"status":{"type":"string","enum":["ACTIVE","DISABLED"]},"description":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}},"delete":{"tags":["Webhooks"],"operationId":"deleteWebhook","x-required-scopes":["webhooks:manage"],"security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Resource ID"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}}},"/webhooks/{id}/test":{"post":{"tags":["Webhooks"],"operationId":"testWebhook","summary":"Queue a signed webhook.test event","x-required-scopes":["webhooks:manage"],"security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Resource ID"}],"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}}},"/webhooks/deliveries/{id}/redeliver":{"post":{"tags":["Webhooks"],"operationId":"redeliverWebhook","summary":"Re-send with the same event ID","x-required-scopes":["webhooks:manage"],"security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Resource ID"}],"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}}},"/tombstones":{"get":{"tags":["Results"],"operationId":"listTombstones","summary":"Expiry, deletion and restriction notices: delete these identity keys from any copies you keep","x-required-scopes":["datasets:read"],"security":[{"bearer":[]}],"parameters":[{"name":"after","in":"query","required":false,"schema":{"type":"integer","minimum":0}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"tombstones":{"type":"array","items":{"$ref":"#/components/schemas/Tombstone"}},"nextAfter":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"}}}},"/sources/lookup":{"get":{"tags":["Sources"],"operationId":"lookupSource","summary":"Canonical source key, sharing policy, business identity and shared-snapshot freshness (starts no job)","x-required-scopes":["runs:read"],"security":[{"bearer":[]}],"parameters":[{"name":"actorId","in":"query","required":true,"schema":{"type":"string"}},{"name":"url","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourceLookup"}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"}}}},"/subscriptions":{"get":{"tags":["Sources"],"operationId":"listSubscriptions","summary":"Watchlist of shared sources kept fresh for this workspace","x-required-scopes":["runs:read"],"security":[{"bearer":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"subscriptions":{"type":"array","items":{"$ref":"#/components/schemas/Subscription"}}}}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"}}},"post":{"tags":["Sources"],"operationId":"createSubscription","summary":"Watch a shareable source (records are read from the shared snapshot, not copied)","x-required-scopes":["runs:write"],"security":[{"bearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["actorId","url"],"properties":{"actorId":{"type":"string"},"url":{"type":"string"},"maxAgeSeconds":{"type":"integer","minimum":300,"maximum":2592000},"tier":{"type":"string","enum":["recent","standard"]}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"subscription":{"$ref":"#/components/schemas/Subscription"}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}}}},"/subscriptions/{id}":{"get":{"tags":["Sources"],"operationId":"getSubscription","x-required-scopes":["runs:read"],"security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Resource ID"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"subscription":{"$ref":"#/components/schemas/Subscription"}}}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}},"delete":{"tags":["Sources"],"operationId":"deleteSubscription","x-required-scopes":["runs:write"],"security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Resource ID"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}}},"/subscriptions/{id}/records":{"get":{"tags":["Sources"],"operationId":"listSubscriptionRecords","summary":"Records of the current shared snapshot with provenance","x-required-scopes":["datasets:read"],"security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Resource ID"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResultsPage"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}}},"/admin/policies":{"get":{"tags":["Platform administration"],"operationId":"adminListPolicies","summary":"Source policies (operator workspace only)","x-required-scopes":["platform:admin"],"security":[{"bearer":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"policies":{"type":"array","items":{"$ref":"#/components/schemas/SourcePolicy"}}}}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"}}}},"/admin/policies/{id}":{"patch":{"tags":["Platform administration"],"operationId":"adminUpdatePolicy","summary":"Change sharing/retention/attribution/robots policy; disabling sharing withdraws shared snapshots and notifies subscribers","x-required-scopes":["platform:admin"],"security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"e.g. web:public-html"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcePolicyPatch"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"policy":{"$ref":"#/components/schemas/SourcePolicy"},"withdrawn":{"type":["object","null"]}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}}},"/admin/sources":{"get":{"tags":["Platform administration"],"operationId":"adminListSources","summary":"Shared source library with freshness, identity and health","x-required-scopes":["platform:admin"],"security":[{"bearer":[]}],"parameters":[{"name":"platform","in":"query","required":false,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"schema":{"type":"string"}},{"name":"identity","in":"query","required":false,"schema":{"type":"string","enum":["verified","corroborated","uncertain","personal","unverified"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"}}}},"/admin/sources/{id}":{"get":{"tags":["Platform administration"],"operationId":"adminGetSource","x-required-scopes":["platform:admin"],"security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Resource ID"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}}},"/admin/sources/{id}/refresh":{"post":{"tags":["Platform administration"],"operationId":"adminRefreshSource","summary":"Start a bounded refresh now (one in flight per source)","x-required-scopes":["platform:admin"],"security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Resource ID"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}}},"/admin/sources/{id}/data":{"delete":{"tags":["Platform administration"],"operationId":"adminDeleteSourceData","summary":"Delete a source’s shared data; subscribers receive records.deleted tombstones","x-required-scopes":["platform:admin"],"security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Resource ID"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}}},"/admin/usage":{"get":{"tags":["Platform administration"],"operationId":"adminUsage","summary":"Physical collection (requests, bytes, browser time, proxy bytes, failures, cost) versus records served to customers","x-required-scopes":["platform:admin"],"security":[{"bearer":[]}],"parameters":[{"name":"period","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"}}}},"/keys":{"get":{"tags":["Keys"],"operationId":"listKeys","summary":"Keys with status and usage, plus what the caller may grant","x-required-scopes":["keys:manage"],"security":[{"bearer":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"}}},"post":{"tags":["Keys"],"operationId":"createKey","summary":"Issue a key no broader than the caller (integration keys cannot hold administration scopes)","x-required-scopes":["keys:manage"],"security":[{"bearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyInput"}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"allOf":[{"$ref":"#/components/schemas/ApiKey"},{"type":"object","properties":{"key":{"type":"string","description":"Shown once"}}}]}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"}}}},"/keys/{id}":{"get":{"tags":["Keys"],"operationId":"getKey","x-required-scopes":["keys:manage"],"security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Resource ID"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/ApiKey"}}}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}},"patch":{"tags":["Keys"],"operationId":"updateKey","summary":"Change policy; queued runs and schedules owned by the key are re-checked when claimed/fired","x-required-scopes":["keys:manage"],"security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Resource ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"actors":{"type":["array","null"]},"limits":{"$ref":"#/components/schemas/KeyLimits"},"expiresAt":{"type":["string","null"]}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/ApiKey"}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}},"delete":{"tags":["Keys"],"operationId":"revokeKey","summary":"Revoke: queued runs cancelled, running runs stopped (records kept), schedules paused, webhooks disabled","x-required-scopes":["keys:manage"],"security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Resource ID"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}}},"/keys/{id}/rotate":{"post":{"tags":["Keys"],"operationId":"rotateKey","summary":"Replacement with the same policy; ownership of work moves to it; the old key expires after graceSeconds","x-required-scopes":["keys:manage"],"security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Resource ID"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"graceSeconds":{"type":"integer","minimum":0,"maximum":604800,"default":0}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}}},"/credentials":{"get":{"tags":["Workspace"],"operationId":"listCredentials","summary":"Configured platform credentials (values are write-only)","x-required-scopes":["credentials:manage"],"security":[{"bearer":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"}}}},"/credentials/{provider}":{"put":{"tags":["Workspace"],"operationId":"setCredentials","x-required-scopes":["credentials:manage"],"security":[{"bearer":[]}],"parameters":[{"name":"provider","in":"path","required":true,"schema":{"type":"string"},"description":"youtube | x | facebook | instagram | linkedin"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"503":{"$ref":"#/components/responses/E503"}}},"delete":{"tags":["Workspace"],"operationId":"deleteCredentials","x-required-scopes":["credentials:manage"],"security":[{"bearer":[]}],"parameters":[{"name":"provider","in":"path","required":true,"schema":{"type":"string"},"description":"Resource ID"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}}},"/audit":{"get":{"tags":["Workspace"],"operationId":"listAudit","x-required-scopes":["audit:read"],"security":[{"bearer":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"before","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"}}}}},"webhooks":{"run.succeeded":{"post":{"summary":"run.succeeded — signed with Travinci-Signature: t=<unix>,v1=HMAC-SHA256(secret, \"<t>.<raw body>\") hex. Deduplicate on Travinci-Event-Id (at-least-once). Reject timestamps older than 300 s.","parameters":[{"name":"Travinci-Signature","in":"header","required":true,"schema":{"type":"string"}},{"name":"Travinci-Event-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"Travinci-Event-Type","in":"header","required":true,"schema":{"type":"string"}},{"name":"Travinci-Delivery-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"Travinci-Delivery-Attempt","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Any 2xx acknowledges. Other statuses are retried with exponential backoff (up to 8 attempts); redirects are not followed."}}}},"run.failed":{"post":{"summary":"run.failed — signed with Travinci-Signature: t=<unix>,v1=HMAC-SHA256(secret, \"<t>.<raw body>\") hex. Deduplicate on Travinci-Event-Id (at-least-once). Reject timestamps older than 300 s.","parameters":[{"name":"Travinci-Signature","in":"header","required":true,"schema":{"type":"string"}},{"name":"Travinci-Event-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"Travinci-Event-Type","in":"header","required":true,"schema":{"type":"string"}},{"name":"Travinci-Delivery-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"Travinci-Delivery-Attempt","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Any 2xx acknowledges. Other statuses are retried with exponential backoff (up to 8 attempts); redirects are not followed."}}}},"run.cancelled":{"post":{"summary":"run.cancelled — signed with Travinci-Signature: t=<unix>,v1=HMAC-SHA256(secret, \"<t>.<raw body>\") hex. Deduplicate on Travinci-Event-Id (at-least-once). Reject timestamps older than 300 s.","parameters":[{"name":"Travinci-Signature","in":"header","required":true,"schema":{"type":"string"}},{"name":"Travinci-Event-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"Travinci-Event-Type","in":"header","required":true,"schema":{"type":"string"}},{"name":"Travinci-Delivery-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"Travinci-Delivery-Attempt","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Any 2xx acknowledges. Other statuses are retried with exponential backoff (up to 8 attempts); redirects are not followed."}}}},"records.expired":{"post":{"summary":"records.expired — signed with Travinci-Signature: t=<unix>,v1=HMAC-SHA256(secret, \"<t>.<raw body>\") hex. Deduplicate on Travinci-Event-Id (at-least-once). Reject timestamps older than 300 s.","parameters":[{"name":"Travinci-Signature","in":"header","required":true,"schema":{"type":"string"}},{"name":"Travinci-Event-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"Travinci-Event-Type","in":"header","required":true,"schema":{"type":"string"}},{"name":"Travinci-Delivery-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"Travinci-Delivery-Attempt","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Any 2xx acknowledges. Other statuses are retried with exponential backoff (up to 8 attempts); redirects are not followed."}}}},"records.deleted":{"post":{"summary":"records.deleted — signed with Travinci-Signature: t=<unix>,v1=HMAC-SHA256(secret, \"<t>.<raw body>\") hex. Deduplicate on Travinci-Event-Id (at-least-once). Reject timestamps older than 300 s.","parameters":[{"name":"Travinci-Signature","in":"header","required":true,"schema":{"type":"string"}},{"name":"Travinci-Event-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"Travinci-Event-Type","in":"header","required":true,"schema":{"type":"string"}},{"name":"Travinci-Delivery-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"Travinci-Delivery-Attempt","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Any 2xx acknowledges. Other statuses are retried with exponential backoff (up to 8 attempts); redirects are not followed."}}}},"records.restricted":{"post":{"summary":"records.restricted — signed with Travinci-Signature: t=<unix>,v1=HMAC-SHA256(secret, \"<t>.<raw body>\") hex. Deduplicate on Travinci-Event-Id (at-least-once). Reject timestamps older than 300 s.","parameters":[{"name":"Travinci-Signature","in":"header","required":true,"schema":{"type":"string"}},{"name":"Travinci-Event-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"Travinci-Event-Type","in":"header","required":true,"schema":{"type":"string"}},{"name":"Travinci-Delivery-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"Travinci-Delivery-Attempt","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Any 2xx acknowledges. Other statuses are retried with exponential backoff (up to 8 attempts); redirects are not followed."}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","bearerFormat":"tva_<12 hex>_<43 base64url>"}},"responses":{"E400":{"description":"INVALID_REQUEST | COMMENTS_NOT_SUPPORTED | LIMIT_EXCEEDS_WORKSPACE | WEBHOOK_URL_FORBIDDEN","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E401":{"description":"UNAUTHENTICATED | INVALID_KEY | KEY_REVOKED | KEY_EXPIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E403":{"description":"FEATURE_DENIED (details.scope) | ACTOR_NOT_ALLOWED (details.actorId, allowedActors) | PRIVILEGE_ESCALATION | CROSS_ORIGIN | WORKSPACE_DISABLED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E404":{"description":"NOT_FOUND | UNKNOWN_ACTOR (resources of actors the key may not use are also 404) | THUMBNAIL_UNAVAILABLE (details.status, details.reason)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E429":{"description":"RATE_LIMITED | KEY_LIMIT | USAGE_LIMIT | QUEUE_FULL (Retry-After when applicable)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E503":{"description":"DATABASE_UNAVAILABLE | QUEUE_UNAVAILABLE | SERVICE_UNAVAILABLE | ARCHIVE_UNAVAILABLE (dependency outage; retry)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Tombstone":{"type":"object","properties":{"id":{"type":"integer"},"createdAt":{"type":"string"},"reason":{"type":"string","enum":["retention_expired","deleted","policy_restricted"]},"runId":{"type":["string","null"]},"snapshotId":{"type":["string","null"]},"sourceKey":{"type":["string","null"]},"identityKeys":{"type":"array","items":{"type":"string"}}}},"SourceLookup":{"type":"object","properties":{"sourceKey":{"type":"string"},"canonicalUrl":{"type":"string"},"components":{"type":"object"},"policy":{"type":["object","null"]},"businessIdentity":{"$ref":"#/components/schemas/BusinessIdentity"},"snapshot":{"type":["object","null"]},"cooldownUntil":{"type":["string","null"]}}},"BusinessIdentity":{"type":"object","properties":{"status":{"type":"string","enum":["verified","corroborated","uncertain","personal","unverified"]},"evidence":{"type":"array","items":{"type":"object"}},"method":{"type":"string"}}},"Subscription":{"type":"object","properties":{"id":{"type":"string"},"sourceKey":{"type":"string"},"actorId":{"type":"string"},"url":{"type":"string"},"tier":{"type":"string"},"maxAgeSeconds":{"type":"integer"},"status":{"type":"string"},"businessIdentity":{"$ref":"#/components/schemas/BusinessIdentity"},"snapshot":{"type":["object","null"]},"cooldownUntil":{"type":["string","null"]},"lastError":{"type":["object","null"]}}},"SourcePolicy":{"type":"object","properties":{"id":{"type":"string"},"platform":{"type":"string"},"collectionMethod":{"type":"string"},"shareable":{"type":"boolean"},"reviewStatus":{"type":"string","enum":["unreviewed","approved","restricted"]},"retentionDays":{"type":["integer","null"]},"maxAgeSeconds":{"type":"integer"},"attribution":{"type":"string"},"sharedFields":{"type":["array","null"]},"deleteOnRequest":{"type":"boolean"},"robotsMode":{"type":"string","enum":["respect","override"]},"robotsOverrideHosts":{"type":"array","items":{"type":"string"}},"retentionAppliesFrom":{"type":"string"},"notes":{"type":"string"}}},"SourcePolicyPatch":{"type":"object","properties":{"shareable":{"type":"boolean"},"reviewStatus":{"type":"string"},"retentionDays":{"type":["integer","null"]},"maxAgeSeconds":{"type":"integer"},"attribution":{"type":"string"},"sharedFields":{"type":["array","null"]},"deleteOnRequest":{"type":"boolean"},"robotsMode":{"type":"string","enum":["respect","override"]},"robotsOverrideHosts":{"type":"array","items":{"type":"string"}},"notes":{"type":"string"}}},"Error":{"type":"object","required":["error","code","requestId"],"properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string"},"details":{"type":"object"}}},"Connection":{"type":"object","properties":{"ok":{"const":true},"workspace":{"$ref":"#/components/schemas/Workspace"},"key":{"$ref":"#/components/schemas/KeySummary"},"service":{"type":"object","properties":{"apiVersion":{"type":"string"},"actorVersion":{"type":"string"},"database":{"type":"string"},"queue":{"type":"string"},"queueDriver":{"type":"string"},"workers":{"type":"object","properties":{"live":{"type":"integer"}}},"acceptingRuns":{"type":"boolean"},"processingRuns":{"type":"boolean"}}}}},"Workspace":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"}}},"KeySummary":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"prefix":{"type":"string"},"kind":{"type":"string","enum":["integration","admin"]},"scopes":{"type":"array","items":{"type":"string"}},"actors":{"type":["array","null"],"items":{"type":"string"},"description":"null = all actors the workspace allows"},"limits":{"$ref":"#/components/schemas/KeyLimits"},"expiresAt":{"type":["string","null"]}}},"KeyLimits":{"type":"object","description":"Each bounded by the workspace limit and the issuer’s own limit","properties":{"maxItemsPerRun":{"type":"integer","minimum":1},"maxRequestsPerRun":{"type":"integer","minimum":1},"maxActiveRuns":{"type":"integer","minimum":1},"monthlyRuns":{"type":"integer","minimum":0},"requestsPerMinute":{"type":"integer","minimum":1}}},"KeyInput":{"type":"object","required":["name","scopes"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"kind":{"type":"string","enum":["integration","admin"],"default":"integration"},"scopes":{"type":"array","items":{"type":"string","enum":["runs:read","runs:write","datasets:read","logs:read","runs:cancel","datasets:export","comments:collect","schedules:read","schedules:write","comparisons:read","webhooks:manage","usage:read","keys:manage","credentials:manage","audit:read","platform:admin"]}},"actors":{"type":["array","null"],"items":{"type":"string","enum":["linkedin-profile","linkedin-posts","instagram-posts","facebook-posts","tiktok-posts","x-posts","youtube-videos","web-business","linkedin-company","news-feeds","google-trends-rss"]}},"limits":{"$ref":"#/components/schemas/KeyLimits"},"expiresAt":{"type":["string","null"],"format":"date-time"}}},"ApiKey":{"allOf":[{"$ref":"#/components/schemas/KeySummary"},{"type":"object","properties":{"description":{"type":"string"},"status":{"type":"string","enum":["active","revoked","expired","rotated"]},"createdAt":{"type":"string"},"lastUsedAt":{"type":["string","null"]},"revokedAt":{"type":["string","null"]},"rotatedFrom":{"type":["string","null"]},"rotatedTo":{"type":["string","null"]},"usage":{"type":"object","properties":{"period":{"type":"string"},"runs":{"type":"integer"},"items":{"type":"integer"},"requests":{"type":"integer"},"activeRuns":{"type":"integer"},"schedules":{"type":"integer"}}}}}]},"Actor":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"platform":{"type":"string"},"recordTypes":{"type":"array","items":{"type":"string"}},"inputSchema":{"type":"object"},"capabilities":{"type":"object","additionalProperties":{"type":"string","enum":["live","fixture","blocked","none"]}},"liveVerification":{"type":"object"}}},"Capabilities":{"type":"object","properties":{"workspace":{"$ref":"#/components/schemas/Workspace"},"key":{"$ref":"#/components/schemas/KeySummary"},"features":{"type":"array","items":{"type":"object","properties":{"scope":{"type":"string"},"label":{"type":"string"},"granted":{"type":"boolean"}}}},"actors":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Actor"},{"type":"object","properties":{"collectionStatus":{"type":"string","enum":["live","partial","blocked"]},"features":{"type":"object","properties":{"submit":{"type":"boolean"},"comments":{"type":"boolean"},"schedules":{"type":"boolean"},"export":{"type":"boolean"}}},"credentials":{"type":["object","null"],"properties":{"provider":{"type":"string"},"required":{"type":"array","items":{"type":"string"}},"configured":{"type":"boolean"}}}}}]}},"deniedActors":{"type":"array","items":{"type":"object"}},"limits":{"type":"object"},"usage":{"type":"object"}}},"RunInput":{"type":"object","description":"See each actor’s inputSchema in /capabilities; unsupported fields are rejected.","properties":{"urls":{"type":"array","items":{"type":"string","format":"uri"}},"maxItems":{"type":"integer"},"maxPagesPerSource":{"type":"integer"},"maxRequests":{"type":"integer"},"timeoutSeconds":{"type":"integer"},"render":{"type":"string","enum":["auto","http","browser"]},"method":{"type":"string","enum":["auto","public-web","official-api"]},"since":{"type":"string","format":"date-time"},"until":{"type":"string","format":"date-time"},"incremental":{"type":"boolean"},"includeComments":{"type":"boolean","description":"Requires comments:collect"},"maxCommentsPerPost":{"type":"integer"},"demo":{"type":"boolean","description":"Labelled synthetic fixtures; no network"}}},"RunCreated":{"type":"object","properties":{"run":{"$ref":"#/components/schemas/Run"},"created":{"type":"boolean"}}},"Run":{"type":"object","properties":{"id":{"type":"string"},"actorId":{"type":"string"},"actorVersion":{"type":"string"},"status":{"type":"string","enum":["QUEUED","RUNNING","SUCCEEDED","FAILED","CANCELLED"]},"input":{"$ref":"#/components/schemas/RunInput"},"createdAt":{"type":"string"},"startedAt":{"type":["string","null"]},"finishedAt":{"type":["string","null"]},"attempt":{"type":"integer"},"maxAttempts":{"type":"integer"},"cancelRequested":{"type":"boolean"},"checkpointAt":{"type":["string","null"]},"progress":{"type":"object"},"stats":{"type":"object","properties":{"items":{"type":"integer","description":"Stored rows of every type (usage)"},"duplicates":{"type":"integer"},"requests":{"type":"integer"},"pages":{"type":"integer"},"durationMs":{"type":"integer"},"countsByType":{"$ref":"#/components/schemas/CountsByType"}}},"outcome":{"type":["object","null"],"properties":{"complete":{"type":"boolean"},"incompleteReasons":{"type":"array","items":{"type":"string"}},"sources":{"type":"integer","description":"Root sources (kind source); comment child tasks are not counted here"},"failedSources":{"type":"integer"},"commentTasks":{"type":"integer","description":"Comment child tasks (kind comments) the run scheduled; absent on runs recorded before it was reported"},"discovery":{"type":"object","description":"Site crawls only (web-business crawl=site): URLs discovered from sitemaps, links, rendered links and pagination, and what became of them","properties":{"discovered":{"type":"integer"},"enqueued":{"type":"integer"},"duplicates":{"type":"integer"},"overflow":{"type":"integer","description":"Discovered beyond maxPages; counted in remaining"},"fetched":{"type":"integer"},"failed":{"type":"integer"},"remaining":{"type":"integer","description":"In-scope URLs not fetched because a limit or blocker stopped the run"}}},"coverage":{"$ref":"#/components/schemas/Coverage"},"unavailable":{"type":"array","items":{"$ref":"#/components/schemas/UnavailableField"}}}},"error":{"type":["object","null"],"description":"Why the run failed: the first failed source’s code and message when every source failed (a message names the host and, for bot protection, what can be done), or a run-level stop","properties":{"code":{"type":"string","description":"e.g. ROBOTS_DENIED, ACCESS_WALL, ACCESS_DENIED, NO_RESPONSE (inferred bot protection: the site accepted the connection but sent no HTTP response on two attempts), PLATFORM_REJECTED, CREDENTIALS_REQUIRED, RATE_LIMITED, TIMEOUT (the run’s own time limit before any record, or every source failed on a transport timeout), KEY_REVOKED, ACCESS_REVOKED"},"message":{"type":"string"},"details":{"type":"object","description":"Shared runs: the failed refresh’s details (stoppedBy, protection, status, host, phase, inferred, attempts; see Source.error.details)","properties":{"stoppedBy":{"type":"string"},"protection":{"type":"string"}}}}},"scheduleId":{"type":["string","null"]},"dataset":{"type":"object","properties":{"runId":{"type":"string"},"itemCount":{"type":"integer"},"counts":{"$ref":"#/components/schemas/CountsByType"}}},"collection":{"type":"object","description":"What was actually collected. `complete` requires every source to reach a natural end or requested boundary (enumeration and pagination complete) and, when comments were requested, their collection to be complete or the platform to not expose them at all; dates and metrics a source never exposes are listed in `unavailable` and never make a collection partial.","properties":{"state":{"type":"string","enum":["pending","complete","partial","empty","failed","cancelled"]},"terminal":{"type":"boolean"},"complete":{"type":"boolean"},"itemCount":{"type":"integer"},"incompleteReasons":{"type":"array","items":{"type":"string"},"description":"Stop reasons (see Source.stopReason) plus COMMENTS_REQUIRES_OVERRIDE | COMMENTS_REQUIRES_API | COMMENTS_PERMISSION_MISSING | COMMENTS_FAILED"},"coverage":{"oneOf":[{"$ref":"#/components/schemas/Coverage"},{"type":"null"}]},"unavailable":{"type":"array","items":{"$ref":"#/components/schemas/UnavailableField"}}}}}},"ArchiveThumbnail":{"type":"object","properties":{"status":{"type":"string","enum":["pending","saved","missing","failed","none"]},"key":{"type":["string","null"]},"sourceUrl":{"type":["string","null"]},"contentType":{"type":["string","null"]},"bytes":{"type":["integer","null"]},"sha256":{"type":["string","null"]},"downloadedAt":{"type":["string","null"]},"reason":{"type":["string","null"],"description":"Why no thumbnail was saved: not_an_image | access_denied | robots_denied | too_large | http_<n> | network_unavailable | timeout"}}},"ArchiveItem":{"type":"object","properties":{"id":{"type":"integer"},"datasetItemId":{"type":"integer"},"runId":{"type":"string"},"entityKey":{"type":"string"},"recordType":{"type":["string","null"]},"platform":{"type":["string","null"]},"status":{"type":"string","enum":["pending","archived","partial","failed"],"description":"archived: record + thumbnail (or no image); partial: record saved, thumbnail missing/failed; failed: record upload failed after ARCHIVE_MAX_ATTEMPTS"},"attempts":{"type":"integer"},"nextAttemptAt":{"type":["string","null"]},"lastError":{"type":["string","null"]},"archivedAt":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"record":{"type":"object","properties":{"key":{"type":["string","null"]},"sha256":{"type":["string","null"]},"bytes":{"type":["integer","null"]}}},"thumbnail":{"$ref":"#/components/schemas/ArchiveThumbnail"}}},"RunArchive":{"type":"object","properties":{"runId":{"type":"string"},"runStatus":{"type":"string"},"enabled":{"type":"boolean"},"total":{"type":"integer"},"counts":{"type":"object","properties":{"pending":{"type":"integer"},"archived":{"type":"integer"},"partial":{"type":"integer"},"failed":{"type":"integer"}}},"thumbnails":{"type":"object","properties":{"pending":{"type":"integer"},"saved":{"type":"integer"},"missing":{"type":"integer"},"failed":{"type":"integer"},"none":{"type":"integer"}}},"uploadedBytes":{"type":"integer"},"truncated":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/ArchiveItem"}},"manifest":{"type":"object","nullable":true,"description":"Site crawls only: the run-level crawl manifest object (travinci/v1/tenants/<tenant>/web/crawl/<runId>/manifest.json), queued when the run is final and listed apart from the records","properties":{"id":{"type":"integer"},"status":{"type":"string","enum":["pending","archived","partial","failed"]},"attempts":{"type":"integer"},"nextAttemptAt":{"type":["string","null"]},"lastError":{"type":["string","null"]},"archivedAt":{"type":["string","null"]},"key":{"type":["string","null"]},"sha256":{"type":["string","null"]},"bytes":{"type":["integer","null"]}}}}},"ArchiveThumbnailUrl":{"type":"object","properties":{"id":{"type":"integer"},"url":{"type":"string","description":"Presigned bucket URL; do not log"},"expiresAt":{"type":"string"},"expiresSeconds":{"type":"integer"},"contentType":{"type":["string","null"]},"bytes":{"type":["integer","null"]}}},"CountsByType":{"type":"object","description":"Stored rows per record type (post, account, comment, business, article, trend; profile for the legacy profile actor). maxItems bounds primary records (post, business, article, trend, profile) only; account rows never count and comments are bounded per post by maxCommentsPerPost.","properties":{"post":{"type":"integer"},"account":{"type":"integer"},"comment":{"type":"integer"},"business":{"type":"integer"},"article":{"type":"integer"},"trend":{"type":"integer"},"profile":{"type":"integer"}}},"CoverageDimension":{"type":"object","required":["state","reason"],"properties":{"state":{"type":"string","enum":["na","not_requested","complete","not_exposed","partial","blocked","failed"],"page":{"type":"integer"},"document":{"type":"integer"}},"reason":{"type":"string","description":"A stop reason or availability state explaining the state"},"detail":{"type":"object"}}},"Coverage":{"type":"object","description":"What the run (or source) could and could not collect, per dimension. States: complete | partial | not_exposed (the source never exposes it) | not_requested | blocked (reachable with credentials, permission or an administrator robots override) | failed | na. enumeration: were the items of the feed readable at all (not_exposed = POSTS_NOT_EXPOSED). pagination: was the end reached (partial = a limit such as MAX_ITEMS/MAX_PAGES; not_exposed = PAGINATION_NOT_EXPOSED). metadata: publication dates (reason relative_only = only relative texts such as \"1 month ago\" were available; publishedAt stays null). engagement: likes/comments/views/shares, detail holds each metric's state: present | not_exposed | requires_api | requires_override | enrichment_budget | transport_failed (the actor's own request for the metric failed at the transport level, so this run could not read it; a retry may succeed; engagement.enrichment.code names the failed request's code) | enriched | partial; explanations holds the actor's reason per missing metric (the same states), and the dimension is failed with reason transport_failed when no metric was read because those requests failed. comments: detail {collected (comment records stored), totalKnown (sum of the posts' comment counts, null when unknown), posts, postsWithKnownTotal, postsWithTasks}; reason collected | disabled | no_comments | not_exposed | permission_missing | requires_api | requires_override | failed.","properties":{"enumeration":{"$ref":"#/components/schemas/CoverageDimension"},"pagination":{"$ref":"#/components/schemas/CoverageDimension"},"metadata":{"$ref":"#/components/schemas/CoverageDimension"},"engagement":{"$ref":"#/components/schemas/CoverageDimension"},"comments":{"$ref":"#/components/schemas/CoverageDimension"}}},"UnavailableField":{"type":"object","properties":{"field":{"type":"string","description":"publishedAt | metrics.likes | metrics.comments | metrics.views | metrics.shares | comments"},"reason":{"type":"string","description":"The availability state behind the gap: not_exposed | relative_only | mixed | requires_api | requires_override | enrichment_budget | transport_failed (this run's request for it failed; a retry may succeed) | hidden, with the platform wall appended when one explains it (e.g. \"requires_api (platform ACCESS_DENIED HTTP 401)\")"}}},"Source":{"type":"object","properties":{"sourceKey":{"type":"string"},"url":{"type":"string"},"kind":{"type":"string","enum":["source","comments","account"]},"status":{"type":"string","enum":["pending","collecting","complete","partial","failed"]},"stopReason":{"type":["string","null"],"description":"TERMINAL_PAGE: The source reported no further pages. DATE_BOUNDARY: Reached records older than the requested date range. INCREMENTAL_BOUNDARY: Reached records already collected by an earlier run (incremental refresh). SINGLE_PAGE: This source type is a single page with no pagination. EMPTY_FEED: The source was fetched successfully and contains no items. MAX_ITEMS: Run item limit reached. MAX_PAGES: Per-source page limit reached. MAX_COMMENTS: Per-post comment limit reached. REPEATED_CURSOR: The source returned a cursor it had already returned; stopped to avoid a loop. NO_NEW_RECORDS: Consecutive pages contained no new records; stopped to avoid an overlap loop. NEXT_PAGE_DISALLOWED: The next page is disallowed by robots.txt. PAGINATION_NOT_EXPOSED: The public page does not expose further pages without signing in. POSTS_NOT_EXPOSED: The page was readable but exposes no posts (for example an account page whose timeline is loaded only by signed-in clients). COMMENTS_NOT_EXPOSED: Comments are not exposed in the public response. COMMENTS_REQUIRES_API: Comments are served only by an endpoint robots.txt disallows; they need the official API key or an administrator robots override. COMMENTS_REQUIRES_OVERRIDE: Comments are served only by an endpoint robots.txt disallows; they need an administrator robots override for the host. COMMENTS_PERMISSION_MISSING: Comments were requested, but this API key lacks the comments:collect permission. CREDENTIALS_REQUIRED: The official API requires credentials that are not configured. REQUEST_BUDGET: Run request budget exhausted. ROBOTS_DENIED: robots.txt disallows this URL for our user agent. ACCESS_WALL: A sign-in, consent or verification wall was returned. ACCESS_DENIED: The source returned 401/403. PLATFORM_REJECTED: The platform rejected the request (for example HTTP 999 or 451). RATE_LIMITED: The source rate limited the collector. NO_PUBLIC_DATA: No recognisable public records were present. PARSE_FAILED: The response was fetched but could not be parsed. ENRICHMENT_BUDGET: The per-record enrichment budget was exhausted; enumeration is unaffected, some metadata or engagement fields are missing. CANCELLED: The run was cancelled. TIMEOUT: The run reached its time limit, or one request to this source timed out (its error then carries details.phase and transient: true); a transport timeout fails that source only. NETWORK_BLOCKED: This network blocks the site (DNS sinkhole); the source itself was never reached. COMMENT_CEILING: The run reached its comment-row ceiling; this post’s comments were not requested. NO_RESPONSE: The site accepted the connection (TLS completed) but sent no HTTP response on two attempts. Bot-protection services treat non-browser clients this way, though an origin that is down or overloaded can look the same, so this is reported as an inferred platform stop (details.inferred: true, details.attempts), never bypassed and not retried past the second attempt. Transport failures (NETWORK_ERROR, DNS_FAILED, TLS_ERROR, TOO_MANY_REDIRECTS, …) keep the transport’s own code."},"pages":{"type":"integer"},"records":{"type":"integer"},"methods":{"type":"array","items":{"type":"string"}},"error":{"type":["object","null"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","description":"Who stopped the source and what the transport learned","properties":{"stoppedBy":{"type":"string","enum":["platform","transport","travinci-robots-policy","run","proxy","travinci-proxy-budget"],"description":"platform: the site refused or, inferred, never answered (ACCESS_DENIED, NO_RESPONSE, RATE_LIMITED, PLATFORM_REJECTED, …); transport: the network failed before any answer (TIMEOUT with a phase, DNS_FAILED, TLS_ERROR, NETWORK_BLOCKED, …); travinci-robots-policy: our robots preflight, no request sent; run: the run itself (a shared refresh still pending when the run finished); proxy: the configured proxy refused the tunnel or its credentials (PROXY_REJECTED, PROXY_AUTH_FAILED); travinci-proxy-budget: the run’s proxy transfer budget (PROXY_BUDGET)"},"protection":{"type":"string","enum":["akamai","cloudflare","imperva","perimeterx","datadome"],"description":"Bot-protection provider named by the 401/403/503 signature (ACCESS_DENIED)"},"status":{"type":"integer","description":"HTTP status when one was received"},"host":{"type":"string"},"phase":{"type":"string","enum":["connect","tls","response","body","run"],"description":"Where a TIMEOUT or NO_RESPONSE stood: connect (no TCP connection), tls (handshake not completed), response (TLS done, no HTTP response: NO_RESPONSE), body (response started, not finished); run for a shared refresh still in progress when the run finished"},"transient":{"type":"boolean","description":"true for a transport failure a later attempt may not see (a TIMEOUT at connect, tls or body is retried within the run and fails only its source); false for a NO_RESPONSE verdict, which is final for the run"},"inferred":{"type":"boolean","description":"NO_RESPONSE: the bot-protection reading is inferred from the silence, not read from a provider signature"},"attempts":{"type":"integer","description":"NO_RESPONSE: requests that completed TLS and got no HTTP response before the verdict (2)"}}}}},"coverage":{"oneOf":[{"$ref":"#/components/schemas/Coverage"},{"type":"null"}],"description":"Root sources only"}}},"SnapshotReference":{"type":"object","properties":{"position":{"type":"integer"},"sourceUrl":{"type":"string"},"sourceKey":{"type":"string"},"mode":{"type":"string","enum":["reused","joined","refreshed","stale-fallback","failed","waiting"]},"snapshotId":{"type":["string","null"]},"snapshotStatus":{"type":["string","null"]},"collectedAt":{"type":["string","null"]},"cacheAgeSeconds":{"type":["integer","null"]},"expiresAt":{"type":["string","null"]},"tier":{"type":["string","null"]},"servedItems":{"type":"integer"},"snapshotRecords":{"type":"integer"},"businessIdentity":{"$ref":"#/components/schemas/BusinessIdentity"},"attribution":{"type":["string","null"]},"resolvedAt":{"type":["string","null"]},"refreshRunId":{"type":["string","null"],"description":"The physical refresh job (shared-pool run) that produced or is producing the snapshot"},"refreshRunStatus":{"type":["string","null"]},"refreshTransport":{"type":["object","null"],"properties":{"requests":{"type":"integer"},"bytesIn":{"type":"integer"},"wireBytes":{"type":"integer"},"proxyBytes":{"type":"integer"},"browserMs":{"type":"integer"}}},"startedRefreshRunId":{"type":["string","null"],"description":"The physical job this run started or joined, even when it failed (the served snapshot may come from another job)"},"startedRefreshStatus":{"type":["string","null"]},"startedRefreshTransport":{"type":["object","null"],"properties":{"requests":{"type":"integer"},"bytesIn":{"type":"integer"},"wireBytes":{"type":"integer"},"proxyBytes":{"type":"integer"},"browserMs":{"type":"integer"}}},"lastRefreshAttemptAt":{"type":["string","null"]},"lastSuccessfulRefreshAt":{"type":["string","null"]},"failureReason":{"type":["object","null"],"description":"The failed refresh’s own error (code, message naming the host, details.stoppedBy / details.protection for bot protection)","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"}}},"detail":{"type":"object"}}},"PhysicalAttribution":{"type":"object","description":"Requests and bytes of the refresh job(s) a shared run is served from; the run itself made none (run.transport is null and stats.requests is 0). The top-level totals cover the jobs this run caused (references in mode refreshed or joined); `earlier` covers the jobs that produced the snapshots it merely reused (mode reused or stale-fallback), collected for someone else before this run.","properties":{"refreshRunId":{"type":["string","null"],"description":"Set when exactly one physical job served the run"},"refreshRunIds":{"type":"array","items":{"type":"string"}},"requests":{"type":"integer"},"bytesIn":{"type":"integer"},"wireBytes":{"type":"integer"},"proxyBytes":{"type":"integer"},"browserMs":{"type":"integer"},"earlier":{"type":"object","description":"Physical work of the refresh job(s) behind reused and stale-fallback snapshots; made before this run and not attributed to it","properties":{"refreshRunIds":{"type":"array","items":{"type":"string"}},"requests":{"type":"integer"},"bytesIn":{"type":"integer"},"wireBytes":{"type":"integer"},"proxyBytes":{"type":"integer"},"browserMs":{"type":"integer"}}}}},"Log":{"type":"object","properties":{"id":{"type":"integer"},"at":{"type":"string"},"level":{"type":"string"},"message":{"type":"string"}}},"Record":{"type":"object","description":"post | comment | account | business | article | trend (profile is legacy). Unknown values are null. Shared records add `snapshot` {id, collectedAt, cacheAgeSeconds, shared, mode, attribution, expiresAt}; businessIdentity {status: verified|corroborated|uncertain|personal}.","properties":{"recordType":{"type":"string"},"platform":{"type":"string"},"id":{"type":["string","null"]},"url":{"type":["string","null"]},"author":{"type":["string","null"]},"text":{"type":["string","null"]},"publishedAt":{"type":["string","null"]},"publishedAtPrecision":{"type":["string","null"],"enum":["date",null],"description":"`date` when the source gives a day without a time: publishedAt is then midnight UTC of that day and should be shown as a date, not a local time"},"archive":{"type":"object","description":"Archive state of post/page/document records of direct runs (absent otherwise); thumbnails via GET /archive/items/{id}/thumbnail","properties":{"id":{"type":"integer"},"status":{"type":"string","enum":["pending","archived","partial","failed"]},"attempts":{"type":"integer"},"lastError":{"type":["string","null"]},"archivedAt":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"record":{"type":"object","properties":{"key":{"type":["string","null"]},"sha256":{"type":["string","null"]},"bytes":{"type":["integer","null"]}}},"thumbnail":{"type":"object","properties":{"status":{"type":"string","enum":["pending","saved","missing","failed","none"]},"key":{"type":["string","null"]},"contentType":{"type":["string","null"]},"bytes":{"type":["integer","null"]},"reason":{"type":["string","null"]}}}}},"publishedText":{"type":["string","null"],"description":"The source’s own date text (for example \"1 month ago\"); kept when no absolute date can be derived and alongside publishedAt when both exist"},"authorRedacted":{"type":"boolean","description":"Comments only: true when the commenter’s name, ID and URL were dropped (every commenter except the account itself)"},"comments":{"type":"object","description":"Posts only: the platform’s own comment count versus the comment records downloaded for this post","required":["state","collected","total"],"properties":{"state":{"type":"string","enum":["collected","partial","pending","not_requested","not_exposed","disabled","requires_api","requires_override","permission_missing","failed","unavailable"],"description":"pending: the post’s comments task has not run yet; its outcome is written back to the post when the task ends"},"collected":{"type":["integer","null"]},"total":{"type":["integer","null"],"description":"null when the platform does not expose the count"},"reason":{"type":"string"}}},"snapshot":{"type":"object","description":"Shared-collection provenance; present on records served from a shared snapshot","properties":{"id":{"type":["string","null"]},"collectedAt":{"type":["string","null"]},"cacheAgeSeconds":{"type":["integer","null"]},"shared":{"type":"boolean"},"mode":{"type":["string","null"],"enum":["reused","joined","refreshed","stale-fallback","failed","waiting",null]},"attribution":{"type":["string","null"]},"expiresAt":{"type":["string","null"]}}},"metrics":{"type":"object","additionalProperties":{"type":["integer","null"]}},"identity":{"type":"object","properties":{"key":{"type":"string"},"confidence":{"type":"string"}}},"sourceUrl":{"type":"string"},"collectedAt":{"type":"string"},"collectionMethod":{"type":"string","enum":["public-html","browser-rendered","public-feed","official-api","demo-fixture"]}}},"ResultsPage":{"type":"object","properties":{"runId":{"type":"string"},"runStatus":{"type":"string"},"finalDataset":{"type":"boolean","description":"false while the run is still collecting"},"total":{"type":"integer"},"offset":{"type":"integer"},"limit":{"type":"integer"},"count":{"type":"integer"},"nextOffset":{"type":["integer","null"]},"hasMore":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/Record"}}}},"ExportJson":{"type":"object","properties":{"runId":{"type":"string"},"runStatus":{"type":"string"},"finalDataset":{"type":"boolean"},"total":{"type":"integer"},"exported":{"type":"integer"},"complete":{"type":"boolean"},"truncated":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/Record"}}}},"Schedule":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"actorId":{"type":"string"},"input":{"$ref":"#/components/schemas/RunInput"},"cron":{"type":"string"},"timezone":{"type":"string"},"status":{"type":"string","enum":["ACTIVE","PAUSED"]},"missedRunPolicy":{"type":"string"},"overlapPolicy":{"type":"string"},"nextRunAt":{"type":["string","null"]},"createdByKeyId":{"type":["string","null"]}}},"ScheduleInput":{"type":"object","required":["name","actorId","input","cron"],"properties":{"name":{"type":"string"},"actorId":{"type":"string"},"input":{"$ref":"#/components/schemas/RunInput"},"cron":{"type":"string"},"timezone":{"type":"string","default":"UTC"},"missedRunPolicy":{"type":"string","enum":["run_latest","skip"]},"overlapPolicy":{"type":"string","enum":["skip","queue"]},"graceSeconds":{"type":"integer"}}},"Comparison":{"type":"object","properties":{"summary":{"type":"object"},"entities":{"type":"array","items":{"type":"object"}},"notes":{"type":"array","items":{"type":"string"}}}},"Usage":{"type":"object","properties":{"period":{"type":"string"},"limits":{"type":"object"},"usage":{"type":"object"},"key":{"type":"object"},"remaining":{"type":"object"},"perRun":{"type":"object"}}},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["ACTIVE","DISABLED"]},"disabledReason":{"type":["string","null"]}}},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string"},"eventId":{"type":"string"},"eventType":{"type":"string"},"status":{"type":"string","enum":["pending","delivering","delivered","failed"]},"attempts":{"type":"integer"},"maxAttempts":{"type":"integer"},"nextAttemptAt":{"type":["string","null"]},"lastStatus":{"type":["integer","null"]},"lastError":{"type":["string","null"]},"log":{"type":"array","items":{"type":"object"}}}},"WebhookEvent":{"type":"object","properties":{"id":{"type":"string","description":"Event ID (stable across retries)"},"type":{"type":"string","enum":["run.succeeded","run.failed","run.cancelled","records.expired","records.deleted","records.restricted"]},"apiVersion":{"const":"1"},"createdAt":{"type":"string"},"workspace":{"$ref":"#/components/schemas/Workspace"},"data":{"type":"object","properties":{"run":{"$ref":"#/components/schemas/Run"}}},"links":{"type":"object","properties":{"run":{"type":"string"},"dataset":{"type":"string"},"export":{"type":"string"}}}}}}}}