Skip to main content

Preview the cost before submitting

Creating a submission consumes credits. To see the cost first, call POST /api/pricing/estimate with the same blobPaths you intend to submit — nothing else is needed. Do this after uploading your assets and before creating the submission — it is read-only and consumes nothing. The asset type and MIME type are derived from the blobPath server-side (the same way the submission does), and the price is computed from a metric measured on the uploaded bytes (video duration, document page count) — so the estimate matches what you are charged when you submit. The measurement is cached, so the submission that follows does not re-read the file.
Each result echoes its blobPath so you can map it back to the file you sent. The response returns the cost per file plus a totalCredits for the batch:
A file with priceable: false can’t be priced, and unpriceableReason says why: unreadable (the file is damaged; export it again), password_protected (remove the password), too_many_pixels (an image over about 179 megapixels; downscale it), or page_count / duration (the metric could not be measured). It costs 0 here and is excluded from totalCredits, but it will be rejected when you create the submission, so fix or re-upload it first.

Creating a submission

A submission is a request to process one or more uploaded assets. After creating a submission, the API queues your assets for processing. Each asset object carries blobPath (the path returned by an upload) and, optionally, previousSubmissionId for versioning and a per-asset sidekickIds list (see Choosing sidekicks below). Do not send filename or contentType in asset objects — they are not part of the schema. The other top-level fields are sidekickIds (required — see below), name (an optional display name for the submission, up to 120 characters — defaults to the first asset’s filename if omitted), metadata (an optional arbitrary object), and externalReference (an optional structured {system, ref} reference to the external work item this submission originates from). Unlike metadata, externalReference is returned on the status endpoint and echoed on the asset.processing.* webhook, so an integration can correlate the completion back without keeping its own mapping. Its system is capped at 64 characters and its ref payload must serialize to under 4 KB; exceeding either is rejected with 422.

Choosing sidekicks

sidekickIds is the submission-level list of sidekicks to run for compliance checking. At least one is required — a submission with no sidekick has nothing to check, so a request that omits sidekickIds or sends an empty list is rejected with 422. To discover which sidekicks your workspace can run — and the asset types each one accepts — call List available sidekicks and use the returned id values. An asset whose type no selected sidekick supports (e.g. a PDF paired only with a video sidekick) is rejected at submit time, so make sure each asset is covered by a sidekick that handles its type. Per-asset selection (optional). Each asset may also carry its own sidekickIds to run only a subset of the sidekicks on that asset. A per-asset list must be a subset of the submission-level sidekickIds; an empty (or omitted) per-asset list means the asset inherits the full submission-level set. Use this when different assets in one submission need different checks — keep the submission-level list as the union of every asset’s selection.
Breaking change (June 2026). sidekickIds was previously optional and accepted an empty list. It is now required with at least one entry. Clients that currently send "sidekickIds": [] must be updated to pass one or more sidekick IDs (fetch them from List available sidekicks) before upgrading.
Testing with a sandbox (sk_test_) key? The asset filename must contain a scenario marker so the sandbox knows which outcome to simulate. See the Sandbox environment guide.

Single asset submission

Multiple asset submission

Submit multiple assets in a single request for batch processing:
The two videos inherit the full submission-level set, while contract.pdf narrows its checks to just the document sidekick via its own sidekickIds. The per-asset list stays a subset of the submission-level sidekickIds.
Each asset is processed independently. Batch related assets into one submission to reduce request volume.

Matching created assets to your inputs

To tell which created asset came from which input, give each asset an externalId of your own — a file id, a row id from your system, anything up to 255 characters. It is echoed on the matching asset in the response:
externalId is optional. Each one must be unique within the submission (a repeat is rejected with 422), and assets you send without one come back without one.
Don’t match created assets to your inputs by their position in the list — the order is not part of the API contract. Use externalId.This matters most if a submission can contain two files with the same filename. Without externalId, a replayed submission can only tell assets apart by filename, so it may pair same-named files with each other’s results. Give every asset an externalId whenever filenames can repeat.

Attaching tags and supporting context

A submission can also carry top-level tags and contextItems (both optional). Tags are key/value labels (found-or-created automatically — no pre-creation or UUID lookup needed). Context items are supporting files or links the review can use. Each entry’s applyTo is "all" (default) or a list of asset blobPaths. A context file is uploaded the same way as an asset — request an upload URL, PUT the bytes, then reference the returned blobPath:
See Tags and supporting context for the full field reference and the allowed contextType values.

Response format

A successful create returns 201 with this shape:
Read the identifier from submissionId (not id). You’ll use it to check status and retrieve results. If a pushed tag is refused by tag governance, the submission still succeeds (201) and the refusal is named in skippedTags instead — see Plain tags and skippedTags.

Safe retries with Idempotency-Key

If a create request times out or the connection drops, you can’t tell whether the submission was created. Retrying without protection risks a second submission — a second review, and a second charge. Send an Idempotency-Key header to make the retry safe. Send the same key again and you get the submission it already created rather than a new one:
How it behaves:
  • You choose the key. Up to 255 characters, opaque to us. Derive it from whatever makes the submission unique in your system — a job id, or a UUID you generate and store before the first attempt. Retries of one submission must reuse the key; a new submission needs a new key.
  • Keys are scoped to your workspace and do not expire. Reusing a key months later still returns the original submission.
  • Concurrent requests are safe. If two requests with the same key arrive at once, one submission is created and both receive it.
  • A replay describes the same submission — the same submissionId, workflowId, ablyChannel and assets, and the status the original 201 reported. It is rebuilt rather than stored, so three things can differ from the first response: skippedTags is always empty (refused tags were reported on the original response only); an asset’s versionGroupId reflects any newer version submitted since; and assets are listed in your retry’s order, matched by externalId — or, for assets sent without one, by filename. Two unlabelled assets with the same filename can’t be told apart, so they may come back in either order: give them an externalId if you need to know which is which. To see where the submission is now, call GET /api/submissions/{submission_id}.
  • Check the Idempotent-Replayed: true header to tell a replay apart, rather than relying on the 200 status alone.
  • Re-uploading before a retry is fine. Each upload returns a new blobPath, so requests are compared on the file name in each blobPath — including the paths in a tag’s or context item’s applyTo — not the full path.
  • List order doesn’t matter. assets, sidekickIds, tags, contextItems and applyTo are compared as sets, so a retry may list them in any order. Everything else — name, metadata, externalReference — is compared exactly as sent.
  • Same key, different request → 409. Changing the files, sidekicks, tags, externalIds or anything else under the same key is treated as a mistake rather than answered with a submission you didn’t ask for. Use a new key.
  • The header is optional. Without it, every request creates a new submission.

Asset versioning

Versioning is explicit. To create a new version of an asset, submit a new submission whose asset references the prior asset through previousSubmissionId. The new submission becomes the next version in the same version group.
1

Upload the revised file

Upload the corrected file and get its blobPath.
2

Reference the previous submission

Include previousSubmissionId on the asset so the API links it as the next version.
3

List versions

Use /submissions/{submission_id}/versions to list all versions in the group.
Example: resubmitting after fixing audio issues.
List all versions in the group:
Response:

Batch submission example

A complete example of uploading multiple files and creating a batch submission:

Status transitions

A submission moves through the statuses below. The terminal states are complete, partial, and failed. A live create returns queued, not submitted. Because assets are admitted to review a few at a time, a submission flips to processing as soon as any asset starts and stays there until every asset has settled — so part of its work may still be waiting while it reads processing. There is no created, completed, or processed status. Use complete for the all-success terminal state and partial for a mixed outcome.

Error handling

If submission creation fails, check these common cases.

Invalid blob path (403)

Ensure the file was uploaded successfully and the blobPath matches the value returned by the upload endpoint exactly.

Previous submission not found (404)

The previousSubmissionId does not resolve to a submission in your workspace.

Asset already submitted (409)

The asset at that blobPath has already been submitted. Use versioning with previousSubmissionId to create a new version.

Idempotency-Key reused for a different request (409)

The Idempotency-Key already created a submission from a different request body. Nothing was created. If this is a new submission, send a new key — see Safe retries with Idempotency-Key.

Request validation failed (422)

Fix the listed fields and resubmit. Common causes:
  • sidekickIds missing or empty — at least one sidekick is required (see Choosing sidekicks).
  • A per-asset sidekickIds is not a subset of the submission-level sidekickIds.
  • Two assets share an externalId — each must be unique within the submission.
  • An asset’s type has no compatible sidekick — e.g. a PDF submitted only with a video sidekick.

Best practices

  • Upload with presigned URLs — request a URL per file and PUT the bytes straight to Azure Blob Storage.
  • Batch related assets — group related files into one submission.
  • Version explicitly — use previousSubmissionId rather than re-submitting the same path.
  • Handle retries — implement exponential backoff for transient failures, and send an Idempotency-Key so a retried create can’t make a duplicate.
  • Label assets with externalId — match created assets to your inputs by identity, not list position.
  • Log submission IDs — save the submissionId for audit trails and support.