{"openapi":"3.0.2","info":{"title":"api2convert Task API","description":"Task API for api2convert.\n\n## Authentication\n\nEvery operation needs a credential. There are three, and they all travel in the same\n`Authorization: Bearer` header:\n\n- **API secret** (`sec_\u2026`) \u2014 long-lived, unscoped, created from your account page. This is the credential you start with. It never expires, so treat it the way you would a password.\n- **Task token** (`tsk_\u2026`) \u2014 short-lived, minted from your secret with `POST \/token`. Lasts between 60 and 86400 seconds, and `DELETE \/token\/{token}` kills it immediately. Use this anywhere the secret itself should not go.\n- **OAuth2 access token** \u2014 for applications acting on behalf of a customer who is not you. Carries scopes, so it is refused on operations the customer did not grant.\n\nA secret may also be sent as an `x-token-secret` header. It is additionally accepted as a `?secret=` query parameter, which is **deprecated**: a credential in a URL is written down by access logs, `Referer` headers and browser history.\n\n## Webhooks\n\nAn async run can POST its result to a URL you supply. Every delivery carries `X-Tasknode-Timestamp`, `X-Tasknode-Key-Id` and `X-Tasknode-Signature` \u2014 an HMAC-SHA256 of `\u0022{timestamp}.{body}\u0022` in hex, using the webhook key shown beside your API secret. Verify the signature AND the timestamp: the timestamp is signed so that you can reject a replayed delivery, which the signature alone cannot tell you about.\n\n## Browsers\n\nThis API can be called from browser JavaScript: CORS is open to any origin and the rate-limit headers are exposed. Your API secret is REFUSED from a browser (403 `SECRET_NOT_ALLOWED_FROM_BROWSER`), as is any credential in the query string \u2014 mint a short-lived token server-side and send that instead. Server-side callers are unaffected.\n\n## Per-key controls\n\nEach API secret carries an environment label, a rate cap, an expiry and an optional scope list, all set with `PATCH \/secret\/{id}`. A field you omit is left alone; sending it as `null` clears it. A cap only ever NARROWS your plan limit, and a scope list only ever narrows what the key may do \u2014 leaving it empty is the unrestricted default, not \u0022no permissions\u0022.\n\n## Revoking a credential\n\nAll three can be revoked through the API. `DELETE \/token\/{token}` kills one task token; `DELETE \/secret\/{id}` deletes a secret AND every token minted from it and every JWT signed with its key; `POST \/oauth\/revoke` is RFC 7009 for OAuth2 tokens. Deleting a secret requires the secret itself \u2014 a credential derived from it cannot destroy it.\n\n## Rate limits\n\nLimits are per credential and derived from your plan. Every response carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`; exceeding the window returns `429` with `Retry-After`. Read the headers rather than guessing the limit \u2014 it changes with your plan.\n\n## Retention, size and time\n\n- **Retention** \u2014 a stored file is deleted 24 hours (86400 seconds) after it is written. Deletion is automatic and needs no call from you: every node is swept hourly and removes what has passed the window, so fetch a stored output inside it \u2014 there is no extension, and the only way back to the bytes afterwards is to run the app again. Read the window as a fetch-by deadline rather than an erase-at moment: a file goes on the first sweep at or after it, and a node out of contact with this sat keeps its files longer until contact is restored.\n- **Upload** \u2014 this API publishes no maximum request body. A body that is too large is refused with `413` and the code `PAYLOAD_TOO_LARGE`, in the same JSON envelope as every other error, and **the cap that actually applied is in `max_bytes` on that refusal** \u2014 read it from there rather than assuming one. Your plan may set a smaller cap, and a proxy in front of the node refuses before the node does at a limit we have not measured; publishing a number before that measurement exists would promise a body size this API cannot be relied on to accept.\n- **Synchronous run** \u2014 `POST \/run\/\u2026` waits at most 27 seconds, counted from the moment the request arrives, for the app to finish and then answers `408` `TASK_TIMEOUT` in the JSON envelope. The task itself keeps running: read it back with `GET \/task\/{task_id}`, or use `POST \/async\/run\/\u2026` with a webhook for anything that may take longer.\n\nThese three are GENERATED from the values this sat enforces rather than typed into the document, and they are repeated machine-readably under the `x-sat-published-limits` extension at the root of this document. None of them will be reduced without an RFC 9745 `Deprecation` header and a `Sunset` date announced at least one full release ahead.\n\nThe full data-handling posture \u2014 what is encrypted at rest and what is not yet, who holds the keys, what an erasure destroys, which sub-processors see your files, and where they are stored \u2014 is published as `docs\/task-api-security-posture.md` and is the document to quote in a security questionnaire. It states the window above the same way this bullet does, as a fetch-by deadline rather than an erase-at moment.\n\n## Errors\n\nEvery failure is `{\u0022message\u0022: \u0022\u2026\u0022, \u0022code\u0022: \u0022\u2026\u0022}`. Branch on `code`: it is a stable symbol, the message is not. The codes derived from the HTTP status are listed below and repeated under the `x-sat-error-codes` extension; individual operations document further codes of their own.\n\nEach code says whether the SAME request may be retried unchanged, and the extension carries it as `retryable` with a `retry_after_seconds`. A retryable answer that names an interval carries it in the `Retry-After` header, jittered per response above the published number so that clients do not return in lock-step; wait at least the header\u0027s value. One status can carry more than one code \u2014 `503` is the generic `SERVICE_UNAVAILABLE` and also the storage-plane refusals \u2014 so branch on the code and never on the status alone. `507 STORAGE_QUOTA_EXCEEDED` means your account is out of allowance and is never a server-capacity condition: that is `503 STORAGE_BACKPRESSURE`, which is retryable.\n\n- `API_FAILURE` \u2014 Returned by the node for a condition the HTTP status alone does not name. *Not retryable.*\n- `BAD_REQUEST` (`400`) \u2014 Bad Request *Not retryable.*\n- `CONFLICT` (`409`) \u2014 Conflict *Not retryable.*\n- `FILE_UNREADABLE` \u2014 The file exists but this node could not turn its bytes back into plaintext. *Not retryable.*\n- `FORBIDDEN` (`403`) \u2014 Forbidden *Not retryable.*\n- `INSUFFICIENT_CREDITS` (`402`) \u2014 Payment Required *Not retryable.*\n- `KEY_UNAVAILABLE` (`503`) \u2014 The key for this file could not be obtained from the key service right now. Retry after the interval in the Retry-After header. *Retryable; the response carries `Retry-After` of at least 30 s.*\n- `NOT_FOUND` (`404`) \u2014 Not Found *Not retryable.*\n- `PAYLOAD_TOO_LARGE` (`413`) \u2014 Content Too Large *Not retryable.*\n- `RATE_LIMITED` (`429`) \u2014 Too Many Requests *Retryable; the response carries no `Retry-After`, use your own back-off.*\n- `SERVICE_UNAVAILABLE` (`503`) \u2014 Service Unavailable *Retryable; the response carries no `Retry-After`, use your own back-off.*\n- `SHRED_JOURNAL_UNAPPLIED` (`503`) \u2014 This sat is holding an erasure repair open and will not mint or unwrap file keys until an operator completes it. Retry after the interval in the Retry-After header. *Retryable; the response carries `Retry-After` of at least 300 s.*\n- `STORAGE_BACKPRESSURE` (`503`) \u2014 The node that took this request is shedding writes because its own disk is under pressure. Nothing is wrong with your account, your plan or your request: retry after the interval in the Retry-After header. Distinct from STORAGE_QUOTA_EXCEEDED, which means your account is out of allowance and retrying will not help. *Retryable; the response carries `Retry-After` of at least 300 s.*\n- `STORAGE_CLUSTER_UNAVAILABLE` (`503`) \u2014 The storage cluster holding this file did not answer. Nothing is lost: retry after the interval in the Retry-After header. *Retryable; the response carries `Retry-After` of at least 60 s.*\n- `STORAGE_OBJECT_MISSING` (`503`) \u2014 The file is recorded but its stored copy could not be found on any tier. The operators have been alerted. A retry cannot help, and the response carries no Retry-After. *Not retryable.*\n- `STORAGE_QUOTA_EXCEEDED` (`507`) \u2014 Insufficient Storage *Not retryable.*\n- `STORAGE_UNAVAILABLE` (`503`) \u2014 The file is stored, but its only copy is on a machine that is temporarily unreachable. Nothing is lost: retry after the interval in the Retry-After header. *Retryable; the response carries `Retry-After` of at least 60 s.*\n- `TASK_TIMEOUT` (`408`) \u2014 Request Timeout *Not retryable.*\n- `UNAUTHORIZED` (`401`) \u2014 Unauthorized *Not retryable.*\n- `UNPROCESSABLE` (`422`) \u2014 Unprocessable Content *Not retryable.*\n- `UPSTREAM_FAILURE` (`502`) \u2014 Bad Gateway *Retryable; the response carries no `Retry-After`, use your own back-off.*","contact":{"name":"Qaamgo","email":"info@qaamgo.com"},"license":{"name":"MIT","url":"https:\/\/opensource.org\/license\/mit\/"},"version":"1.0.0"},"servers":[{"url":"https:\/\/task.api2convert.com\/v1","description":"api2convert Task API"}],"paths":{"\/task\/upload":{"post":{"summary":"Upload one or more input files","description":"multipart\/form-data upload. Each part becomes a file record with `file_type: \u0022input\u0022`, whose `file_id` can then be passed to any run operation. The two storage fields, `persistence` and `durable_sync`, are form parts beside the file; a raw-body upload (`Content-Type: application\/octet-stream`) has no form parts and may send them as query parameters of the same name instead. The form part wins where both are present. Both are judged BEFORE any byte is written, so a refused upload costs nothing.","operationId":"file-upload","requestBody":{"content":{"multipart\/form-data":{"schema":{"properties":{"file":{"type":"string","format":"binary"},"persistence":{"description":"The durability class of the uploaded file. One of `durable`, `ephemeral`. `ephemeral` is the default: the file lives for the published retention window and is then collected. `durable` counts against your storage quota, is replicated to a storage cluster, and is kept until you delete it; it is refused with `422 PERSISTENCE_NOT_AVAILABLE` on a service that does not offer durable storage yet. Any other word answers `400`. This is the durability class only \u2014 \u0022retention\u0022 is the time-to-live and is never a spelling of this \u2014 and `durable_sync` is a flag on `durable`, not a value here. Case-insensitive.","type":"string","default":"ephemeral","enum":["durable","ephemeral"]},"durable_sync":{"description":"A flag on `persistence: durable`, never a persistence of its own: withhold the answer until a storage cluster holds the file, so a `200` means the copy is already off this node. Refused with `422` beside any other persistence, with `422` while this service does not offer the synchronous flush, and with `422` when it is not a boolean. A flush that does not confirm discards the upload and answers `503`: retry it.","type":"boolean","default":false}},"type":"object"}}}},"responses":{"200":{"description":"The stored file records. Each carries the `persistence` that LANDED, which is what central recorded, not merely what was asked.","content":{"application\/json":{"schema":{"type":"array","items":{"$ref":"#\/components\/schemas\/FileItem"}}}}},"400":{"$ref":"#\/components\/responses\/BadRequestException"},"401":{"$ref":"#\/components\/responses\/UnauthorizedException"},"403":{"$ref":"#\/components\/responses\/ForbiddenException"},"413":{"$ref":"#\/components\/responses\/PayloadTooLargeException"},"422":{"$ref":"#\/components\/responses\/UnprocessableException"},"429":{"$ref":"#\/components\/responses\/RequestLimitException"},"503":{"$ref":"#\/components\/responses\/ServiceUnavailableException"},"507":{"$ref":"#\/components\/responses\/StorageQuotaException"}},"security":[{"secret":[]},{"token":[]},{"secretHeader":[]},{"secretQuery":[]},{"oauth2":["jobs:write"]}]}},"\/files":{"get":{"summary":"List your files, newest first","operationId":"file-list","parameters":[{"$ref":"#\/components\/parameters\/Limit"},{"$ref":"#\/components\/parameters\/Cursor"},{"$ref":"#\/components\/parameters\/Order"},{"name":"file_type","in":"query","description":"Restrict to `input` or `output` files.","required":false,"schema":{"type":"string","enum":["input","output"]}},{"name":"task_id","in":"query","description":"Restrict to the files belonging to one task.","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"A cursor page of file records","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/FileListPage"}}}},"401":{"$ref":"#\/components\/responses\/UnauthorizedException"}},"security":[{"secret":[]},{"token":[]},{"secretHeader":[]},{"secretQuery":[]},{"oauth2":["jobs:read"]}]}},"\/task\/file\/{file_id}":{"get":{"summary":"Download a file","description":"Responds with the file BYTES. By default the response also carries `Content-Disposition: attachment`, which makes a browser save it; pass `download=inline` to omit that header and have the browser render it instead. The response body is the same either way.","operationId":"file-get","parameters":[{"$ref":"#\/components\/parameters\/FileId"},{"$ref":"#\/components\/parameters\/Download"}],"responses":{"200":{"$ref":"#\/components\/responses\/FileDownload"},"401":{"$ref":"#\/components\/responses\/UnauthorizedException"},"404":{"$ref":"#\/components\/responses\/NotFoundException"},"503":{"$ref":"#\/components\/responses\/ServiceUnavailableException"}},"security":[{"secret":[]},{"token":[]},{"secretHeader":[]},{"secretQuery":[]},{"jwt":[]}]},"delete":{"summary":"Delete a file","description":"The file is unavailable immediately: every later read answers 404 and no new download URL can be minted for it. Its bytes are removed asynchronously from every copy we hold (the node that served it, the warm store, and the off-site replica); the last copy is gone within 72 hours of this call. A file that another of your resources still references keeps its bytes until that reference is deleted too, and the window then starts from that deletion. Your storage usage is reduced by the file\u0027s size at the time of this call, not when its bytes are removed.","operationId":"file-delete","parameters":[{"$ref":"#\/components\/parameters\/FileId"}],"responses":{"204":{"$ref":"#\/components\/responses\/DeletedResource"},"404":{"$ref":"#\/components\/responses\/NotFoundException"}},"security":[{"secret":[]},{"token":[]},{"secretHeader":[]},{"secretQuery":[]},{"oauth2":["jobs:write"]}]}},"\/task\/file\/{file_id}\/{file_name}":{"get":{"summary":"Download a file under its own name","description":"Identical to `\/task\/file\/{file_id}`, with the file name in the path so that a client saving the response by URL gets the right name. This is the form the signed URLs returned by a completed task use.","operationId":"file-get-named","parameters":[{"$ref":"#\/components\/parameters\/FileId"},{"name":"file_name","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#\/components\/parameters\/Download"}],"responses":{"200":{"$ref":"#\/components\/responses\/FileDownload"},"401":{"$ref":"#\/components\/responses\/UnauthorizedException"},"404":{"$ref":"#\/components\/responses\/NotFoundException"},"503":{"$ref":"#\/components\/responses\/ServiceUnavailableException"}},"security":[{"secret":[]},{"token":[]},{"secretHeader":[]},{"secretQuery":[]},{"jwt":[]}]}},"\/tasks":{"get":{"summary":"List your tasks, newest first","operationId":"task-list","parameters":[{"$ref":"#\/components\/parameters\/Limit"},{"$ref":"#\/components\/parameters\/Cursor"},{"$ref":"#\/components\/parameters\/Order"},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["incomplete","queued","processing","complete","failed"]}},{"name":"operation","in":"query","description":"Restrict to one operation, as `category\/path` (the same value a task reports as `operation_path`).","required":false,"schema":{"type":"string"}},{"name":"created_from","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"created_to","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"include_deleted","in":"query","description":"Include tasks you have deleted. Deleting a task is a soft delete, so it stays retrievable this way.","required":false,"schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"A cursor page of tasks","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/TaskListPage"}}}},"401":{"$ref":"#\/components\/responses\/UnauthorizedException"}},"security":[{"secret":[]},{"token":[]},{"secretHeader":[]},{"secretQuery":[]},{"oauth2":["jobs:read"]}]}},"\/task\/{task_id}":{"get":{"summary":"Get task basic information","operationId":"task-get","parameters":[{"name":"task_id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Return the requested task"},"404":{"description":"Not found"}},"security":[{"secret":[]},{"token":[]},{"secretHeader":[]},{"secretQuery":[]},{"oauth2":["jobs:read"]}]},"delete":{"summary":"Delete the task with id `task_id`","operationId":"task-delete","parameters":[{"name":"task_id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"204":{"description":"Resource deleted successfully \u2014 no content returned."}},"security":[{"secret":[]},{"token":[]},{"secretHeader":[]},{"secretQuery":[]},{"oauth2":["jobs:write"]}]}},"\/task\/{task_id}\/full":{"get":{"summary":"Get task full information","description":"Everything `\/task\/{task_id}` returns, plus the input files, any errors and warnings, and the credits the run cost.","operationId":"task-complete-get","parameters":[{"name":"task_id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"$ref":"#\/components\/responses\/TaskItemFullDetail"},"401":{"$ref":"#\/components\/responses\/UnauthorizedException"},"404":{"$ref":"#\/components\/responses\/NotFoundException"}},"security":[{"secret":[]},{"token":[]},{"secretHeader":[]},{"secretQuery":[]},{"oauth2":["jobs:read"]}]}},"\/storage":{"get":{"summary":"Your storage quota, usage and retention","description":"What your plan allows, what you have used against it, which pool it is drawn from, and how long a stored file lives. `limit_bytes` is the same figure the upload endpoints enforce, so the quota shown is the quota applied; a plan lookup that fails answers `200` with `limit_bytes: null` (no quota is enforced then either), never a `500`. Answered with `Cache-Control: private, no-store`: never cache it.","operationId":"storage-get","responses":{"200":{"description":"The storage status of the authenticated account","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/StorageStatus"}}}},"401":{"$ref":"#\/components\/responses\/UnauthorizedException"},"403":{"$ref":"#\/components\/responses\/ForbiddenException"},"502":{"$ref":"#\/components\/responses\/BadGatewayException"}},"security":[{"secret":[]},{"token":[]},{"secretHeader":[]},{"secretQuery":[]},{"oauth2":["profile"]}]}},"\/token":{"post":{"summary":"Mint a short-lived task token","description":"Authenticate with your `sec_` secret. The plaintext token comes back as `plain_token`, ONCE \u2014 only its hash is stored, so it cannot be recovered. Use the returned `prefix` to inspect or revoke it. A task token may not mint another token.","operationId":"token-create","requestBody":{"required":false,"content":{"application\/json":{"schema":{"properties":{"expires_in":{"description":"Requested lifetime in seconds. Clamped to the maximum your plan allows, and in any case to between 60 and 86400. Defaults to 3600.","type":"integer","default":3600,"maximum":86400,"minimum":60}},"type":"object"}}}},"responses":{"201":{"description":"The minted token","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/TokenItem"}}}},"401":{"$ref":"#\/components\/responses\/UnauthorizedException"}},"security":[{"secret":[]},{"token":[]},{"secretHeader":[]},{"secretQuery":[]},{"jwt":[]}]}},"\/token\/{token}":{"get":{"summary":"Inspect a token","operationId":"token-show","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The token record, without the plaintext","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/TokenItem"}}}},"404":{"$ref":"#\/components\/responses\/NotFoundException"}},"security":[{"secret":[]},{"token":[]},{"secretHeader":[]},{"secretQuery":[]},{"jwt":[]}]},"delete":{"summary":"Revoke a token immediately","operationId":"token-revoke","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"$ref":"#\/components\/responses\/DeletedResource"},"404":{"$ref":"#\/components\/responses\/NotFoundException"}},"security":[{"secret":[]},{"token":[]},{"secretHeader":[]},{"secretQuery":[]},{"jwt":[]}]}}},"components":{"securitySchemes":{"secret":{"type":"http","scheme":"bearer","description":"Your long-lived API secret (`sec_\u2026`), created from your account page.\nSend it as `Authorization: Bearer sec_\u2026`.\n\nIt does not expire, it is not scoped, and anyone holding it can spend your conversion contract \u2014 so do not ship it to a browser, a mobile app or anything else you do not control. Mint a short-lived token for those (`POST \/token`)."},"token":{"type":"http","scheme":"bearer","description":"A short-lived task token (`tsk_\u2026`) minted from your secret via `POST \/token`.\n\nBounded lifetime, revocable at any moment with `DELETE \/token\/{token}`, and stored here only as a hash \u2014 the plaintext is returned exactly once and cannot be recovered. This is the credential to hand to something that should not hold your secret. A task token may not mint another token."},"jwt":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"An OAuth2 access token, obtained through the `oauth2` flow below.\n\nUsed by partner integrations acting on a customer\u0027s behalf. Unlike a secret or a task token it carries SCOPES, so it is refused on operations the customer did not grant it."},"oauth2":{"type":"oauth2","description":"Authorization code flow, for applications acting on behalf of a customer who is not you.\n\nPKCE (`S256`) is required for public clients and `plain` is refused for every client. Refresh tokens are issued and rotate for public clients. The resulting access token is presented as the `jwt` scheme above.","flows":{"authorizationCode":{"authorizationUrl":"https:\/\/account.api2convert.com\/oauth\/authorize","tokenUrl":"https:\/\/task.api2convert.com\/oauth\/token","refreshUrl":"https:\/\/task.api2convert.com\/oauth\/token","scopes":{"profile":"View your account information","jobs:read":"View your tasks and jobs","jobs:write":"Create tasks and jobs for you","purchases":"Buy subscriptions and credits for you","account:delete":"Send an account deletion request on your behalf"}}}},"secretHeader":{"type":"apiKey","in":"header","name":"x-token-secret","description":"Your `sec_\u2026` secret in a dedicated header, for clients that cannot set `Authorization`. Secret-only: an OAuth2 access token is not accepted here."},"secretQuery":{"type":"apiKey","in":"query","name":"secret","deprecated":true,"description":"**Deprecated.** Your `sec_\u2026` secret as a query parameter.\n\nIt still works, and it should not be used: a credential in a URL is recorded by web-server access logs, `Referer` headers, browser history and any proxy in between. Use `Authorization: Bearer` or `x-token-secret`. Responses to requests using this form carry a `Deprecation` header."}},"parameters":{"FileIdQuery":{"name":"file","in":"query","description":"File Id or File url passed as a query string.\nIf a header `file_id` is present, the header parameter will take precedence.\nIf a `file_id` is passed through the path, the path parameter will take precedence.","required":false,"schema":{"type":"string"}},"FileIdHeader":{"name":"file","in":"header","description":"File Id, File url or File content","required":false,"schema":{"type":"string"}},"FileId":{"name":"file_id","in":"path","required":true,"schema":{"type":"string"}},"TaskId":{"name":"task_id","in":"path","required":true,"schema":{"type":"string"}},"Download":{"name":"download","in":"query","description":"Controls the `Content-Disposition` header only; the body is the\nfile either way. Omit it (or send `download=attachment`) for the default\n`attachment`, which makes a browser save the file. Send `download=inline`\nto omit the header so a browser renders the file instead.","required":false,"schema":{"type":"string","default":"attachment","enum":["attachment","inline"]}},"RunInfo":{"name":"info","in":"query","description":"Answer with the task RECORD instead of the conversion result.\nUseful for inspecting status, credits and output URLs without\ndownloading anything.","required":false,"schema":{"type":"boolean","default":false}},"RunStore":{"name":"store","in":"query","description":"Store the conversion output, or stream it and keep nothing.\n\nDefaults to `true`, which is the behaviour this endpoint has always had:\nthe output is written to your storage, registered as a `file_type:\noutput` file, and the run answers `302` with a signed, expiring download\nURL in `Location`.\n\nSend `store=false` and the output is streamed in the response and never\nwritten to storage; it will not appear in `GET \/v1\/files`, it has no\n`file_id`, and there is nothing to delete afterwards or to expire. The\nrun answers `200` with the bytes in the body instead of a redirect.\n\nRead from the JSON request body first and from this query parameter\nsecond. `StoreFile` is not accepted, in either place. A value that is\nnot a boolean (`true`\/`false`, `1`\/`0`, `yes`\/`no`, `on`\/`off`) answers\n`422 UNPROCESSABLE`, before the conversion runs.\n\nThe default on this route is `true` and will not change without an\nRFC 9745 `Deprecation` header and a `Sunset` date announced at least one\nfull release ahead.\n\nBilling for `store=false` runs is not documented in this contract yet;\ndo not infer it from this parameter\u0027s existence.\n\nThe asynchronous form (`\/async\/run\/\u2026`) takes the same flag with the\nopposite default \u2014 `false` there \u2014 because each side keeps the behaviour\nits existing callers integrated against.","required":false,"schema":{"type":"boolean","default":true}},"RunPersistence":{"name":"persistence","in":"query","description":"The durability class of the run\u0027s OUTPUT files. One of `durable`, `ephemeral`. `ephemeral` is the default: the file lives for the published retention window and is then collected. `durable` counts against your storage quota, is replicated to a storage cluster, and is kept until you delete it; it is refused with `422 PERSISTENCE_NOT_AVAILABLE` on a service that does not offer durable storage yet. Any other word answers `400`. This is the durability class only \u2014 \u0022retention\u0022 is the time-to-live and is never a spelling of this \u2014 and `durable_sync` is a flag on `durable`, not a value here. Case-insensitive.\n\nRead from the JSON request body first and from this query parameter\nsecond. On a multipart run the same field also names the persistence of\nthe uploaded INPUT: one run is one ask.","required":false,"schema":{"type":"string","default":"ephemeral","enum":["durable","ephemeral"]}},"Limit":{"name":"limit","in":"query","description":"Page size. Values above the maximum are clamped rather than rejected.","required":false,"schema":{"type":"integer","default":25}},"Cursor":{"name":"cursor","in":"query","description":"Opaque cursor from a previous page\u0027s `pagination.next_cursor`.\nDo not construct or parse it \u2014 its contents are not part of the contract.\nCursor paging, not offset paging: rows added while you walk a list cannot\nshift a page boundary and make you skip or repeat a record.","required":false,"schema":{"type":"string"}},"Order":{"name":"order","in":"query","required":false,"schema":{"type":"string","default":"desc","enum":["asc","desc"]}}},"responses":{"RequestLimitException":{"description":"Request limit reached","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorItem"}}}},"ServiceUnavailableException":{"description":"Service unavailable. Branch on the body\u0027s `code` \u2014 a 503 is one of: `KEY_UNAVAILABLE` (retryable, Retry-After \u2265 30 s), `SERVICE_UNAVAILABLE` (retryable, no Retry-After), `SHRED_JOURNAL_UNAPPLIED` (retryable, Retry-After \u2265 300 s), `STORAGE_BACKPRESSURE` (retryable, Retry-After \u2265 300 s), `STORAGE_CLUSTER_UNAVAILABLE` (retryable, Retry-After \u2265 60 s), `STORAGE_OBJECT_MISSING` (not retryable), `STORAGE_UNAVAILABLE` (retryable, Retry-After \u2265 60 s). Wait at least the Retry-After header where one is present; never retry a code marked not retryable.","headers":{"Retry-After":{"description":"Seconds to wait before retrying the same request. Present when the code is retryable with an interval (see x-sat-error-codes); jittered per response above the published retry_after_seconds. Absent for a code that is not retryable or carries no hint.","schema":{"type":"integer","minimum":1}}},"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorItem"}}}},"UnauthorizedException":{"description":"Unauthorized request","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorItem"}}}},"TaskItemCreated":{"description":"Return the created task","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/TaskItem"}}}},"TaskItemDetail":{"description":"Return the requested task","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/TaskItem"}}}},"TaskItemFullDetail":{"description":"Return the requested task","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/TaskItemFull"}}}},"FileDownload":{"description":"The file content.","content":{"application\/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"PayloadTooLargeException":{"description":"The upload exceeds the maximum size for your plan","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorItem"}}}},"StorageQuotaException":{"description":"Storing this file would exceed your storage quota. Delete files you no longer need, or wait for them to be collected. Code STORAGE_QUOTA_EXCEEDED: not retryable, and never a server-capacity condition \u2014 that is 503 STORAGE_BACKPRESSURE.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorItem"}}}},"InsufficientCreditsException":{"description":"Not enough credits to run this operation","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorItem"}}}},"NotFoundException":{"description":"Not found","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorItem"}}}},"DeletedResource":{"description":"Resource deleted successfully \u2014 no content returned."},"RequestTimeoutException":{"description":"The synchronous budget is spent: code `TASK_TIMEOUT`. The run waited the published `sync_run_ceiling_seconds` (counted from the request\u0027s arrival) and the app had not finished. The task itself keeps running \u2014 read it back with `GET \/task\/{task_id}` \u2014 and `POST \/async\/run\/\u2026` with a webhook is the form for anything that may take longer. Not retryable as the same synchronous request.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorItem"}}}},"BadRequestException":{"description":"Malformed request: code `BAD_REQUEST`. On the write endpoints this is a `persistence` that is not one of `durable`, `ephemeral` \u2014 the message names the legal spellings.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorItem"}}}},"UnprocessableException":{"description":"Well-formed but refused, before anything ran or was written. Branch on the code: `UNPROCESSABLE` for a `store` or `durable_sync` that is not a boolean, or `durable_sync` beside a persistence other than `durable`; `PERSISTENCE_NOT_AVAILABLE` when `persistence: durable` was asked for on a service that does not offer durable storage yet \u2014 upload with `ephemeral` (the default) or retry once it is offered.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorItem"}}}},"ForbiddenException":{"description":"The credential is valid and may not do this: code `FORBIDDEN`. On `GET \/storage` it is an OAuth2 access token without the `profile` scope; a `sec_` secret or a task token is never scoped and never sees this. On a run (`\/run\/\u2026`, `\/async\/run\/\u2026`) or an upload (`\/task\/upload`) it can also mean that the Task API is not enabled for this account on this service; the `message` then reads \u0022The Task API is not available for this account.\u0022. Nothing is converted, stored or charged, and retrying does not help until it is enabled. Reading, downloading and deleting the tasks and files you already have, and creating tokens, keep working.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorItem"}}}},"BadGatewayException":{"description":"The node could not get an answer from the service behind it: code `UPSTREAM_FAILURE`. Retryable with your own back-off; nothing about your request was wrong.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorItem"}}}}},"schemas":{"TaskItem":{"description":"A task.","required":["task_id","id","status"],"properties":{"task_id":{"type":"integer","example":1},"id":{"type":"integer","example":1},"status":{"type":"string","enum":["incomplete","queued","processing","complete","failed"],"example":"queued"},"operation_path":{"description":"The operation that produced this task, as `category\/path`.","type":"string","nullable":true},"job_id":{"type":"string","nullable":true},"files":{"type":"array","items":{"$ref":"#\/components\/schemas\/FileItem"}}}},"TaskItemFull":{"description":"Full configuration for a Task","required":["task_id","status"],"properties":{"task_id":{"type":"integer","example":"1"},"id":{"type":"integer","example":1},"status":{"type":"string","enum":["incomplete","queued","processing","complete","failed"],"example":"queued"},"files":{"type":"array","items":{"$ref":"#\/components\/schemas\/FileItem"}},"files_input":{"type":"array","items":{"$ref":"#\/components\/schemas\/FileItem"}},"errors":{"type":"array","items":{"type":"string"}},"warnings":{"type":"array","items":{"type":"string"}},"credits":{"type":"integer","minimum":0}}},"FileItem":{"description":"A stored file record.","properties":{"file_id":{"type":"string","example":"F899vc74BC67474c8012X239c11C21RTZ"},"file_name":{"type":"string","example":"photo.png"},"file_size":{"description":"Size in bytes.","type":"integer","example":51234},"file_extension":{"type":"string","example":"png"},"file_type":{"type":"string","enum":["input","output"]},"file_server":{"description":"Origin of the server holding the bytes \u2014 scheme and host with a trailing slash, not a bare hostname.","type":"string","example":"https:\/\/task.example.com\/"},"task_id":{"description":"The task this file belongs to, if any.","type":"integer"},"persistence":{"description":"The durability class this file was stored with: `durable` or `ephemeral`. What LANDED, as central recorded it \u2014 read it back rather than assuming your ask was honoured. `null` on a record whose persistence this node has not been told.","type":"string","enum":["durable","ephemeral"],"nullable":true},"name":{"type":"string"},"size":{"type":"integer"},"extension":{"type":"string"},"type":{"type":"string"},"server":{"type":"string"}}},"StorageStatus":{"description":"The storage status of an account: quota, usage, pool and the retention time-to-live. `retention_policy` is a TTL and nothing else; durability is `persistence`, on each file.","required":["limit_bytes","used_bytes","pool","retention_policy"],"properties":{"limit_bytes":{"description":"Bytes the plan allows. `null` means NO QUOTA \u2014 never 0, which would mean no storage, and never -1. Also `null` when the plan lookup failed, because no quota is enforced then either.","type":"integer","minimum":1,"example":2147483648,"nullable":true},"used_bytes":{"description":"Bytes counted against the quota \u2014 the maintained counter the `507` gate reads.","type":"integer","minimum":0,"example":734003200},"pool":{"description":"The storage pool the account draws from, or `null` when this service publishes no pool placement for the account. Never a guessed label.","type":"string","nullable":true},"retention_policy":{"description":"How long a stored file lives before it is collected. An object so that a later field is an addition, not a break.","required":["ttl_seconds"],"properties":{"ttl_seconds":{"description":"The time-to-live in seconds \u2014 the same `retention_seconds` this document publishes under `x-sat-published-limits`. `null` only when this service publishes no retention figure; never 0 and never \u0022forever\u0022.","type":"integer","minimum":1,"example":86400,"nullable":true}},"type":"object"}}},"FileInput":{"description":"An input file for a run: one of `file_id`, `url` or `data`.","properties":{"file_id":{"description":"The id of a file you uploaded to `\/task\/upload`.","type":"string","example":"F899vc74BC67474c8012X239c11C21RTZ"},"url":{"description":"A publicly reachable URL the conversion engine can fetch.","type":"string","format":"url"},"data":{"description":"The file itself, base64 encoded.","type":"string","example":"--BASE64_ENCODED_FILE--..."},"name":{"type":"string","example":"file.png"}}},"Pagination":{"description":"Cursor paging envelope.","required":["has_more","limit"],"properties":{"next_cursor":{"description":"Pass as `cursor` to fetch the next page. `null` on the last page.","type":"string","nullable":true},"has_more":{"type":"boolean"},"limit":{"type":"integer"}}},"TaskListPage":{"description":"A page of tasks.","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/TaskItem"}},"pagination":{"$ref":"#\/components\/schemas\/Pagination"}}},"FileListPage":{"description":"A page of files.","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/FileItem"}},"pagination":{"$ref":"#\/components\/schemas\/Pagination"}}},"TokenItem":{"description":"A short-lived task token. `plain_token` is present ONLY in the response that mints it and is not recoverable afterwards; only its hash is stored.","properties":{"plain_token":{"description":"The token itself. Returned once, on creation.","type":"string","example":"tsk_0123456789abcdef0123456789abcdef01234567"},"prefix":{"description":"A non-secret handle for this token \u2014 what you pass to `\/token\/{token}` to inspect or revoke it.","type":"string","example":"tsk_0123456789"},"id":{"type":"integer"},"expires_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"revoked_at":{"type":"string","format":"date-time","nullable":true},"active":{"type":"boolean"},"revoked":{"type":"boolean"},"expired":{"type":"boolean"}}},"ErrorItem":{"description":"Error item","required":["code","message"],"properties":{"code":{"description":"Stable symbolic error code. The vocabulary derived from the HTTP status is listed in the description of this document and under its x-sat-error-codes extension.","type":"string","example":"PAYLOAD_TOO_LARGE"},"message":{"type":"string","example":"Something went wrong"},"retry_after":{"description":"Seconds to wait before retrying, for a client that cannot read the Retry-After header. Present only on some retryable refusals (rate limiting, storage backpressure); the header is authoritative.","type":"integer","example":300,"nullable":true}}}}},"security":[{"secret":[]},{"token":[]},{"secretHeader":[]},{"secretQuery":[]},{"jwt":[]}],"x-sat-published-limits":{"retention_seconds":{"published":86400,"enforced":86400,"unit":"seconds","published_source":"binding:tracks-enforced (sat.task.published_retention_seconds unbound) \u2014 the deletion window this sat\u0027s node GC is configured to run is exactly what a customer needs to know, and it is read per sat from StorageTargetFacts::nodeGcTtl() rather than from a literal, so tracking it cannot publish another sat\u0027s window","enforced_source":"default:App\\Tasknode\\Command\\FileGarbageCollectorCommand::DEFAULT_TTL"},"max_upload_bytes":{"published":null,"enforced":1073741824,"unit":"bytes","published_source":"binding:withheld (sat.task.published_upload_cap_bytes unbound) \u2014 DEC-INFRA-10 (ratified, costly-to-reverse) opens \u0022Do not publish 1 GB\u0022 and requires the Cloudflare-PROXIED cap to be MEASURED first \u2014 a 200 MB POST to a proxied task.\u003Cbrand\u003E host and to the per-node origin \u2014 before any number is published. That measurement has not been made: it is recorded as outstanding in docs\/plans\/ledger\/NEEDS-A-HUMAN.md, and docs\/task-api-edge-capacity.md hop 1 has the proxied cap as UNMEASURED (expect ~100 MB on non-Enterprise Cloudflare). The enforced 1 GiB is the ORIGIN\/engine ceiling and is published nowhere; the cap that actually applied to a refused request travels in max_bytes on the 413. Bind the parameter to the measured proxied number and this row publishes it.","enforced_source":"min(App\\Task\\Util\\TaskApiLimitResolver::DEFAULT_MAX_UPLOAD_BYTES, App\\Tasknode\\Util\\RequestFileUtil::MAX_UPLOAD_BYTES)"},"sync_run_ceiling_seconds":{"published":27,"enforced":27,"unit":"seconds","published_source":"binding:tracks-enforced (taskapi_published_sync_ceiling unbound) \u2014 the smaller of the node\u0027s wait loop (TaskApiRequestManager::SYNC_WAIT_BUDGET_SECONDS, which sits strictly under the pool\u0027s kill so the documented 408 can actually be written) and the fpm pool\u0027s request_terminate_timeout is what really ends a synchronous run, and that is the number a customer is planning against; see POOL_TERMINATE_TIMEOUT_SECONDS for where the pool figure is read from","enforced_source":"App\\Tasknode\\Manager\\TaskApiRequestManager::SYNC_WAIT_BUDGET_SECONDS"}},"x-sat-error-codes":{"API_FAILURE":{"status":null,"description":"Returned by the node for a condition the HTTP status alone does not name.","reserved":false,"retryable":false,"retry_after_seconds":null},"BAD_REQUEST":{"status":400,"description":"Bad Request","reserved":false,"retryable":false,"retry_after_seconds":null},"CONFLICT":{"status":409,"description":"Conflict","reserved":false,"retryable":false,"retry_after_seconds":null},"FILE_UNREADABLE":{"status":null,"description":"The file exists but this node could not turn its bytes back into plaintext.","reserved":false,"retryable":false,"retry_after_seconds":null},"FORBIDDEN":{"status":403,"description":"Forbidden","reserved":false,"retryable":false,"retry_after_seconds":null},"INSUFFICIENT_CREDITS":{"status":402,"description":"Payment Required","reserved":false,"retryable":false,"retry_after_seconds":null},"KEY_UNAVAILABLE":{"status":503,"description":"The key for this file could not be obtained from the key service right now. Retry after the interval in the Retry-After header.","reserved":false,"retryable":true,"retry_after_seconds":30},"NOT_FOUND":{"status":404,"description":"Not Found","reserved":false,"retryable":false,"retry_after_seconds":null},"PAYLOAD_TOO_LARGE":{"status":413,"description":"Content Too Large","reserved":false,"retryable":false,"retry_after_seconds":null},"RATE_LIMITED":{"status":429,"description":"Too Many Requests","reserved":false,"retryable":true,"retry_after_seconds":null},"SERVICE_UNAVAILABLE":{"status":503,"description":"Service Unavailable","reserved":false,"retryable":true,"retry_after_seconds":null},"SHRED_JOURNAL_UNAPPLIED":{"status":503,"description":"This sat is holding an erasure repair open and will not mint or unwrap file keys until an operator completes it. Retry after the interval in the Retry-After header.","reserved":false,"retryable":true,"retry_after_seconds":300},"STORAGE_BACKPRESSURE":{"status":503,"description":"The node that took this request is shedding writes because its own disk is under pressure. Nothing is wrong with your account, your plan or your request: retry after the interval in the Retry-After header. Distinct from STORAGE_QUOTA_EXCEEDED, which means your account is out of allowance and retrying will not help.","reserved":false,"retryable":true,"retry_after_seconds":300},"STORAGE_CLUSTER_UNAVAILABLE":{"status":503,"description":"The storage cluster holding this file did not answer. Nothing is lost: retry after the interval in the Retry-After header.","reserved":false,"retryable":true,"retry_after_seconds":60},"STORAGE_OBJECT_MISSING":{"status":503,"description":"The file is recorded but its stored copy could not be found on any tier. The operators have been alerted. A retry cannot help, and the response carries no Retry-After.","reserved":false,"retryable":false,"retry_after_seconds":null},"STORAGE_QUOTA_EXCEEDED":{"status":507,"description":"Insufficient Storage","reserved":false,"retryable":false,"retry_after_seconds":null},"STORAGE_UNAVAILABLE":{"status":503,"description":"The file is stored, but its only copy is on a machine that is temporarily unreachable. Nothing is lost: retry after the interval in the Retry-After header.","reserved":false,"retryable":true,"retry_after_seconds":60},"TASK_TIMEOUT":{"status":408,"description":"Request Timeout","reserved":false,"retryable":false,"retry_after_seconds":null},"UNAUTHORIZED":{"status":401,"description":"Unauthorized","reserved":false,"retryable":false,"retry_after_seconds":null},"UNPROCESSABLE":{"status":422,"description":"Unprocessable Content","reserved":false,"retryable":false,"retry_after_seconds":null},"UPSTREAM_FAILURE":{"status":502,"description":"Bad Gateway","reserved":false,"retryable":true,"retry_after_seconds":null}}}