API & SDK

API reference

A small, stable REST surface. Authenticate with an API key in the x-signata-api-key header; the verification response contract is versioned (api_version: 2026-01-01) so additive changes never break you.

Machine-readable spec

The full OpenAPI document is served at /openapi.json. Generate a typed client, or import it into Postman or Insomnia. The examples below show the load-bearing fields; the spec is exhaustive.

Authentication & scopes

Every request (except the public health and JWKS endpoints) requires an API key. Keys carry scopes; a request without the required scope returns 403. The admin scope satisfies any check.

scopes

verify:read       POST /api/v1/verify, read events
sign:write        POST /api/v1/sign
provenance:read   GET  /api/v1/provenance/{assetHash}
admin             workspace CRUD (keys, trust, policies, webhooks, …)

Two optional headers apply broadly: idempotency-key makes POSTs safe to retry, and x-request-id is echoed back to correlate logs.

Verify

POST/api/v1/verify

scope: verify:read

Verify an asset. The request body is the raw asset bytes (application/octet-stream), not multipart form data. Returns the full verification response.

Response fields

VerificationResponse

api_version    contract version (e.g. 2026-01-01)
verdict        verified | provenance_present_untrusted | tampered | no_provenance | error
verdict_label  human label for the verdict
summary        one neutral sentence (never "real"/"fake")
signer         { name, trusted, key_thumbprint? }  (trusted is a policy decision)
binding        { algorithm, matches, computed_hash, claimed_hash? }
signature      { valid, format: "c2pa" | "signata" | "none" }
ai             { disclosure, generated, edited, generator? }
claim          { generator, actions[], assertions[], ingredients[] } | null
recovered_via  "embedded" | "transparency_log" | null
reasons        machine-readable reason codes for the verdict
policy         { actions, matched_rule? }  (when a workspace policy ran)
event_id       id of the recorded event

See Quickstart for a complete example response.

Sign

POST/api/v1/sign

scope: sign:write

Attach a Content Credential to an asset, append a record to the transparency log, and return the credentialed bytes plus a receipt.

Request

POST /api/v1/sign
x-signata-api-key: pk_live_xxx
idempotency-key: 7c1f...e9      # optional; safe retries
content-type: application/octet-stream

<raw asset bytes>

# Sign options are passed as query params or an x-signata-sign-options
# JSON header, e.g. { "title": "...", "ai": { "generated": true } }.

200 OK: SignResponse

{
  "api_version": "2026-01-01",
  "manifest_id": "mf_3k9d2",
  "asset": { "hash": "b1946ac9...d8e0f3a2", "format": "image/png", "size": 184320 },
  "format": "c2pa",
  "signer": { "name": "Acme Newsroom", "key_id": "key_a1b2" },
  "transparency": {
    "seq": 4127,
    "entry_hash": "9f2c...001a",
    "log_root": "9f2c...001a"
  },
  "credentialed_asset_base64": "iVBORw0KGgoAAAANS..."
}

Recover provenance

GET/api/v1/provenance/{assetHash}

scope: provenance:read

Soft-binding recovery. Look up the transparency-log record for a content hash. found: false simply means no record matches that hash. It is not an error and not a claim about authenticity.

200 OK: ProvenanceLookupResponse

{
  "api_version": "2026-01-01",
  "found": true,
  "asset_hash": "b1946ac9...d8e0f3a2",
  "record": {
    "manifest_id": "mf_3k9d2",
    "seq": 4127,
    "entry_hash": "9f2c...001a",
    "prev_hash": "7a3e...88bd",
    "format": "c2pa",
    "signer": { "name": "Acme Newsroom", "key_id": "key_a1b2" },
    "ai": { "generated": false, "edited": false },
    "created_at": "2026-01-14T09:21:03.000Z"
  },
  "log_root": "9f2c...001a"
}

Keys & operations

GET/.well-known/jwks.json

public

The JSON Web Key Set for Signata’s signing identities. Public keys only. Use it to verify Signata-issued signatures independently. No authentication required.

GET/api/health

public

Liveness probe. Returns 200 when the process is up. No dependencies are checked.

GET/api/ready

public

Readiness probe. Returns 200 only when dependencies (database, and Redis when configured) are reachable. Wire it to your orchestrator’s readiness gate.

GET/api/v1/transparency/verify

scope: verify:read

Re-verify the entire transparency-log hash chain and report the current log_root, length, and the first inconsistent entry if any. See the transparency log.

Workspace resources

The following are standard CRUD collections (GET list, POST create, GET /{id} read, PATCH /{id} update, DELETE /{id} where it makes sense). Unless noted they require the admin scope. The OpenAPI spec documents each field.

/api/v1/signing-identitiesscope: admin

Signing identities. The named keys you sign with. List, create, rotate, and disable. Private key material is held server-side (from KMS in production) and never returned.

/api/v1/trustscope: admin

Trust list. The signers your workspace trusts, bound by key thumbprint. Add a known issuer or a custom thumbprint, and remove entries. Drives verified vs provenance_present_untrusted.

/api/v1/policiesscope: admin

Policies. Ordered verdict→action rules (allow / label / disclose / review / block / webhook). First matching rule wins; a fallback applies when none match.

/api/v1/api-keysscope: admin

API keys. Issue and revoke keys with scopes (verify:read, sign:write, provenance:read, admin) and an environment tag. The secret is shown once at creation.

/api/v1/webhooksscope: admin

Webhooks. Subscriptions notified on verification and policy events. Each delivery is HMAC-signed (x-signata-webhook-signature) so you can verify authenticity.

/api/v1/reviewsscope: admin

Reviews. The human-review queue. When a policy returns the review action, the verification lands here to be resolved.

/api/v1/eventsscope: verify:read

Events. A read-only feed of verification and sign events for analytics, keyed by event_id. Filterable by verdict, source, and time.

/api/v1/auditscope: admin

Audit log. An append-only record of administrative actions (key issuance, trust changes, policy edits) for compliance.

/api/v1/settingsscope: admin

Settings. Workspace-level configuration: default policy, allowed origins for the badge, and display preferences.

Errors

Errors are JSON with a stable error code and a human message. Common codes: unauthorized (401, missing/invalid key), forbidden (403, missing scope), invalid_request (400), not_found (404), and rate_limited (429). The error verdict, by contrast, appears in a successful verify response when the input couldn’t be read as a supported asset.