Skip to main content

LookupSignatureResponse

job objectrequired
job_idstringrequired

The ID of the job

typeJobType (string)required

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]

statusJobStatus (string)required

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

Possible values: [failed_to_fetch_from_url, image_already_protected, image_load_failed, image_too_large, image_too_small, internal]

messagestringrequired

A developer-facing error message

output_urlstring

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

output_url_expires_atstring<date-time>

The date and time the output URL will expire

signature_id object

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

oneOf
string

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.

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

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_stateShareState (string)required

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.

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_stateShareState (string)required

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].

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.

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

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

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

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

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. Disclosure to other parties is governed by the creator's record-access policy (managed by SASHA 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

created_atstring<date-time>required

The date and time the job was created

updated_atstring<date-time>required

The date and time the job was last updated

LookupSignatureResponse
{
  "job": {
    "job_id": "string",
    "type": "embed-signature",
    "status": "pending",
    "error": {
      "code": "failed_to_fetch_from_url",
      "message": "string"
    },
    "output_url": "string",
    "output_url_expires_at": "2024-07-29T15:51:28.071Z",
    "signature_id": "string",
    "creator_id": 0,
    "guidance": {
      "share_state": "private",
      "advice": "allowed",
      "message": "string"
    },
    "record": {
      "share_state": "private",
      "allowed_publish_urls": [
        "string"
      ],
      "allowed_source_urls": [
        "string"
      ],
      "allowed_from": "2024-07-29T15:51:28.071Z",
      "allowed_to": "2024-07-29T15:51:28.071Z",
      "byline": "string",
      "purchase_url": "string",
      "licensee": "string",
      "asset_source_id": "string",
      "custom_fields": {},
      "created_at": "2024-07-29T15:51:28.071Z",
      "updated_at": "2024-07-29T15:51:28.071Z"
    },
    "created_at": "2024-07-29T15:51:28.071Z",
    "updated_at": "2024-07-29T15:51:28.071Z"
  }
}