Skip to main content

Record

A Record attaches creator-declared distribution intent and display metadata to a signature.

A lookup always returns coarse guidance (evaluated server-side). It may additionally return a field-filtered Record: the owning partner receives the full Record, a partner the owner has granted access to receives only the granted fields, and all other lookers receive no Record. The full Record is always readable by its owning partner via GET /signature/{signature_id}/record.

Consistency rules (enforced on write):

  • share_state must be set
  • private and unrestricted Records must not carry any distribution fields
  • restricted Records may carry any subset of the distribution fields (allowed_publish_urls, allowed_source_urls, allowed_from, allowed_to), including none — the fields form a permit list, so a restricted Record with none of them permits no locations yet and conditions can be added later as they become known
  • custom_fields are display/metadata only and may be set under any share state

Contradictory combinations are rejected.

Size limits (enforced on write): at most 100 patterns per URL-pattern list, each at most 2048 characters; at most 32 custom_fields entries with keys of 1-64 characters and string values of at most 1024 characters; a Record without c2pa_manifest_store must not exceed 64 KiB when serialized.

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

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"
}