POST /v1/records

Ingest a cryptographically signed provenance record. Counts as 1 signature against your plan quota.

Authentication required — Authorization: Bearer ctv_key_…

---

Request

POST /v1/records
Content-Type: application/json
Authorization: Bearer ctv_key_abc123

Body

{
  "watermark_id": "wm_7f3kx9mq2",
  "generator_id": "gen_abc123",
  "model": "stable-diffusion-xl",
  "content_hash": "sha3-256:a3f1...",
  "signature": "<ml-dsa base64>",
  "signed_payload": {
    "content_hash": "sha3-256:a3f1...",
    "generator_id": "gen_abc123",
    "model": "stable-diffusion-xl",
    "watermark_id": "wm_7f3kx9mq2"
  }
}

Field	Type	Description
watermark_id	string	Opaque ID embedded in the image watermark
generator_id	string	ID of the registered generator that signed this
model	string	Model name (e.g. stable-diffusion-xl)
content_hash	string	sha3-256:<64 hex chars> — SHA-3 hash of the content
signature	string	ML-DSA signature (base64) over signed_payload canonical JSON
signed_payload	object	The exact payload that was signed

---

Response 201

{
  "token": "ctv_7f3kx9mq2...",
  "record_id": "rec_uuid"
}

Field	Description
token	Compact signed artifact — embed in XMP metadata or pass alongside content
record_id	UUID of the stored provenance record

---

Errors

Status	Code	Meaning
400	—	Validation failed or signature invalid
401	—	Missing or invalid API key
402	signature_limit_reached	Free tier monthly limit hit — upgrade to continue
403	—	Generator does not belong to your organization
404	—	Generator not found or revoked

402 body

{
  "error": "signature_limit_reached",
  "message": "Free tier limit of 500 signatures/month reached. Upgrade at https://certivu.ai/pricing",
  "upgrade_url": "https://certivu.ai/pricing",
  "limit": 500,
  "current": 500
}

---

Fetch a record

GET /v1/records/:record_id

Returns the full ProvenanceRecord. No authentication required.

---

Usage notes

• The content_hash must use format sha3-256:<64 lowercase hex chars>
• signed_payload must be the exact object that was canonically serialized and signed — verification replays this
• Use @certivu/sdk to handle hashing, signing, and submission automatically