ListJobsResponse

jobs object[]required

List of jobs

Array [

job_idstringrequired

The ID of the job

typeJobTyperequired

The type of the job:

embed-signature: The job is to embed a SASHA Signature into an image
lookup-signature: The job is to check if an image is already protected with SASHA Signature

Possible values: [embed-signature, lookup-signature]

statusJobStatusrequired

The status of the job:

pending: The job has been accepted and is waiting to be processed
completed: The job is completed successfully
failed: The job failed with an error

Possible values: [pending, completed, failed]

error object

The error that occurred while processing the job, if the job status is failed

codestringrequired

Error codes:

failed_to_fetch_from_url: There was an issue fetching image from the provided image URL
image_already_protected: The image is already protected with SASHA Signature
image_load_failed: The image is not a valid image e.g. corrupted or invalid format
image_too_large: The image is too large to process
image_too_small: The image is too small to process
internal: An internal error occurred
media_load_failed: The media could not be read from the URL, or the server hosting it does not support range requests
media_too_large: The media exceeds the size limit
media_too_long: The media exceeds the duration limit
unsupported_media_format: The media is not in a supported format

Possible values: [failed_to_fetch_from_url, image_already_protected, image_load_failed, image_too_large, image_too_small, internal, media_load_failed, media_too_large, media_too_long, unsupported_media_format]

messagestringrequired

A developer-facing error message

Example: Unsupported image format

output_urlstring

The URL of the result media file (only populated if job status is completed and type is embed-signature)

Example: https://storage.example.com/processed-image.jpg

output_url_expires_atstring<date-time>

The date and time the output URL will expire

Example: 2025-01-01T00:00:00Z

signature_id object

The Signature identifier (populated when job status is completed). Will be null if no signature was found in the image.

oneOf

SignatureID
null

The globally unique identifier of the SASHA Signature embedded into the image.

The SignatureID is an unsigned 64-bit integer.

In JSON representation, the SignatureID is represented as a string.

SignatureID

The globally unique identifier of the SASHA Signature embedded into the image.

The SignatureID is an unsigned 64-bit integer.

In JSON representation, the SignatureID is represented as a string.

Example: 12345678901234567890

creator_idinteger<uint32>

The Creator ID of the business entity that owns the found signature (populated when job status is completed, type is lookup-signature, and a signature was found — that is, exactly when signature_id is populated). A lookup never reports a signature without its creator.

Possible values: >= 0 and <= 4294967295

Example: 1234567890

guidance object

SASHA-evaluated distribution guidance for the found signature (populated when job status is completed, type is lookup-signature, and an active signature was found). A signature without a Record yields guidance with the private share state.

share_stateShareStaterequired

The creator-declared share state of a protected media item:

private: The creator declared that the media is not intended to be distributed anywhere public
unrestricted: The creator declared no distribution restrictions for the media
restricted: The creator declared that the media is intended to be distributed only where the Record's distribution fields permit

A share state describes only the intent the creator has declared to SASHA. It is not a statement about the legal status of the media; rights such as copyright apply independently.

Possible values: [private, unrestricted, restricted]

advicestringrequired

The verdict for the queried location and time:

allowed: Presence of the media at the queried location at the current time is consistent with the creator's declared distribution intent
not_allowed: Presence of the media at the queried location at the current time conflicts with the creator's declared distribution intent, or the creator declared the media as not intended for public distribution
inconclusive: No conclusive verdict could be produced, typically because the share state is restricted and no publish_url or source_url was supplied with the lookup

Possible values: [allowed, not_allowed, inconclusive]

messagestring

Human-readable explanation of the verdict, e.g. "Only allowed on example.com".

Populated at the server's discretion, typically when advice is not_allowed or inconclusive. For developer convenience only: English, not localized, and the wording is not stable across releases — never parse or branch on it; use advice and share_state for program logic. The text may name domains from the Record's allowed URL patterns (domain names are public knowledge and are not masked); it never carries full URL patterns or other raw Record content.

Example: Only allowed on news.example.com

record object

A field-filtered Record for the found signature. Populated only when job status is completed, type is lookup-signature, an active signature was found, and the partner is the owning creator (full Record) or has been granted access (granted fields only). Absent for all other lookers and never present for revoked signatures.

Availability is time-bounded: the disclosed Record is retained for a limited window after completion, so it may be absent on jobs fetched later even though guidance remains. Use GET /signature/{signature_id}/record for durable read-back of a Record you own.

share_stateShareStaterequired

The creator-declared share state of a protected media item:

private: The creator declared that the media is not intended to be distributed anywhere public
unrestricted: The creator declared no distribution restrictions for the media
restricted: The creator declared that the media is intended to be distributed only where the Record's distribution fields permit

A share state describes only the intent the creator has declared to SASHA. It is not a statement about the legal status of the media; rights such as copyright apply independently.

Possible values: [private, unrestricted, restricted]

allowed_publish_urlsstring[]

URL patterns the browser-facing display URL of the media is allowed to match (only meaningful with the restricted share state).

Pattern syntax:

https only. The scheme may be omitted; https is implied.
A host with no path matches any path on that host: https://cdn.example.com.
A path ending in / matches that prefix: https://news.example.com/articles/ matches /articles/123 but not /archive/9. A path not ending in / must match exactly.
*. is a subdomain wildcard, and is only allowed as the leftmost label: https://*.example.com. It cannot appear elsewhere, so https://example.com/* is not a valid pattern — omit the path instead. The base of a wildcard must have at least two labels and must not be a public suffix.
No userinfo, no query string, no fragment, no IP literals, no localhost.

A pattern that does not parse is rejected with an INVALID_PATTERN field violation naming the entry, e.g. allowed_publish_urls[1].

Example: ["https://news.example.com/articles/"]

allowed_source_urlsstring[]

URL patterns the storage/CDN address of the media bytes is allowed to match (only meaningful with the restricted share state).

Same pattern syntax as allowed_publish_urls.

Example: ["https://cdn.example.com"]

allowed_fromstring<date-time>

The media is not allowed to be available before this time (supports embargo dates)

allowed_tostring<date-time>

The media is not allowed to be available after this time

bylinestring

Display text the publisher is expected to show alongside the media (e.g. photographer credit).

Plain text, no control characters. Consumers must always treat this value as text, never as markup.

Possible values: <= 256 characters

Example: Photo by Jane Doe

purchase_urlstring<uri>

URL where the media can be purchased or licensed.

Must be a well-formed https URL without userinfo, and must not point at an IP literal or localhost.

Possible values: <= 2048 characters

Example: https://license.example.com/photos/123

licenseestring

Legal business name of the entity that has licensed the media asset. Aids enforcers when the licence agreement is not bound to a specific location.

Plain text, no control characters. Consumers must always treat this value as text, never as markup.

Possible values: <= 256 characters

Example: Example Media Group Ltd.

asset_source_idstring

The creator's own upstream source ID for the asset: the creator's identifier for the media in their own system.

Opaque text, no control characters. A UUID (RFC 9562) is recommended but not required. Consumers must always treat this value as text, never as markup.

Possible values: <= 256 characters

Example: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d

custom_fields object

Custom fields, keyed by a creator-chosen name. Custom fields are display/metadata only: they never participate in distribution guidance evaluation, so they may be set under any share state. Each custom field is disclosed to other parties like any other Record field: to the creators the owner has granted it to, or to every looker once the owner marks it public. SASHA manages these settings on the creator's behalf.

property name* FieldValue

A typed value for a custom Record field. Exactly one property is set, which pins the value's type. Custom fields are display/metadata only and never participate in distribution guidance evaluation.

boolean_valueboolean

string_valuestring

int32_valueinteger<int32>

double_valuenumber<double>

uuid_valuestring<byte>

A UUID per RFC 9562 as its 16 raw bytes, base64-encoded.

created_atstring<date-time>

The date and time the Record was first created

updated_atstring<date-time>

The date and time the Record was last replaced

warnings object[]

What the job left out of its result without failing (only populated if job status is completed and type is embed-signature). Empty or absent when nothing was left out. The protected media was still produced; each warning names what was not preserved. A failed job reports its cause in error instead.

Array [

codestringrequired

Warning codes. More codes may be added; treat an unknown code as a warning described by message alone.

stream_not_preserved: A stream of the input, e.g. an audio, subtitle or data stream or an additional video stream, could not be carried into the output and was left out. The protected video was produced. Returned for video jobs.

Possible values: [stream_not_preserved]

messagestringrequired

A developer-facing warning message that names what was left out.

Example: Audio stream 2 (opus) could not be carried into the MP4 output and was left out.

]

created_atstring<date-time>required

The date and time the job was created

Example: 2025-01-01T00:00:00Z

updated_atstring<date-time>required

The date and time the job was last updated

Example: 2025-01-01T00:00:00Z

]

ListJobsResponse
{
  "jobs": [
    {
      "job_id": "string",
      "type": "embed-signature",
      "status": "pending",
      "error": {
        "code": "failed_to_fetch_from_url",
        "message": "Unsupported image format"
      },
      "output_url": "https://storage.example.com/processed-image.jpg",
      "output_url_expires_at": "2025-01-01T00:00:00Z",
      "signature_id": "12345678901234567890",
      "creator_id": 1234567890,
      "guidance": {
        "share_state": "private",
        "advice": "allowed",
        "message": "Only allowed on news.example.com"
      },
      "record": {
        "share_state": "private",
        "allowed_publish_urls": [
          "https://news.example.com/articles/"
        ],
        "allowed_source_urls": [
          "https://cdn.example.com"
        ],
        "allowed_from": "2024-07-29T15:51:28.071Z",
        "allowed_to": "2024-07-29T15:51:28.071Z",
        "byline": "Photo by Jane Doe",
        "purchase_url": "https://license.example.com/photos/123",
        "licensee": "Example Media Group Ltd.",
        "asset_source_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
        "custom_fields": {},
        "created_at": "2024-07-29T15:51:28.071Z",
        "updated_at": "2024-07-29T15:51:28.071Z"
      },
      "warnings": [
        {
          "code": "stream_not_preserved",
          "message": "Audio stream 2 (opus) could not be carried into the MP4 output and was left out."
        }
      ],
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-01-01T00:00:00Z"
    }
  ]
}