Endpoints

All endpoints are under https://api.vitrified.glass/v1/. Bearer auth required.

Attestations

POST /v1/attestations

Submit a new attestation.

Request:

{
  "artifact": { "sha256": "9f86d081884c7d65..." },
  "metadata": {
    "schema": "purl",
    "purl": "pkg:npm/[email protected]"
  }
}

Response (201 Created):

{
  "id": "sub_01J...",
  "leaf_sha256": "...",
  "status": "queued",
  "submitted_at": "2026-05-31T12:34:56Z",
  "metadata": { ... },
  "warnings": []
}

GET /v1/attestations/:id

Fetch a submission. If the bundle is ready, the response includes bundle.

Response (200 OK):

{
  "id": "sub_01J...",
  "leaf_sha256": "...",
  "status": "witnessed",
  "submitted_at": "...",
  "witnessed_at": "...",
  "metadata": { ... },
  "bundle": { /* see /docs/concepts/proof-bundle */ }
}

GET /v1/attestations

List submissions with filters and cursor-based pagination.

Query parameters: limit (default 50, max 200), cursor, schema, status, submitted_after, submitted_before.

Response:

{
  "data": [{/* submission */}],
  "next_cursor": "cur_..."
}

PATCH /v1/attestations/:id

Correct metadata on a submission whose validation failed. The leaf is not affected; only the indexed metadata changes.

DELETE /v1/attestations/:id

Redact metadata for a submission. The bundle and leaf remain; an audit log entry records the deletion.

Bundles

GET /v1/attestations/:id/bundle

Fetch only the proof bundle for a submission. Useful for clients that don't want the metadata overhead.

GET /v1/attestations/:id/bundle.json

Same as above; returns Content-Type: application/json and Content-Disposition: attachment for direct browser download.

Batches

GET /v1/batches/:id

Fetch batch metadata including the root hash and the witnesses that landed for the batch.

GET /v1/batches

List batches.

Webhooks

POST /v1/webhooks

Create a webhook subscription.

{
  "url": "https://example.com/vitrified-webhook",
  "events": ["attestation.witnessed", "attestation.partial", "attestation.failed"],
  "secret": "whsec_..." <!-- pragma: allowlist secret -->
}

GET /v1/webhooks, DELETE /v1/webhooks/:id

List and delete subscriptions.

Webhook delivery format

Every delivery includes a Vitrified-Signature header. Validate with the verifyWebhook helper in your SDK. Delivery body:

{
  "id": "evt_01J...",
  "type": "attestation.witnessed",
  "created": "...",
  "data": {
    "submission_id": "sub_01J...",
    "bundle_url": "https://api.vitrified.glass/v1/attestations/sub_01J.../bundle"
  }
}

The full event catalog is in spec/webhook-events.md.

Exports

POST /v1/exports

Create a continuous export to a customer-controlled destination.

{
  "destination": {
    "kind": "s3",
    "bucket": "my-attestations",
    "prefix": "vitrified/",
    "role_arn": "arn:aws:iam::123456789012:role/VitrifiedExport"
  },
  "filter": { "schema": "slsa.provenance.v1" }
}

Destinations: s3, gcs, azure_blob, git_repo.

GET /v1/exports, GET /v1/exports/:id

List exports; fetch a single export's status and recent delivery history.

DELETE /v1/exports/:id

Stop an export.

Trust roots

GET /v1/service/trust_roots

Fetch the currently published trust roots: TSA certificate chains, Sigstore log key, Vitrified DSSE signing key fingerprint, OpenTimestamps calendar URLs, EVM contract addresses.

Mirrored at https://verify.vitrified.glass/trust_roots.json for CDN-backed access.

Service

GET /v1/service/health

Health probe. Returns 200 OK with { "status": "ok" } when the service is operational.

GET /v1/service/me

Returns the API key's principal: project, scopes, rate limits, recent usage.

See also

• API overview — authentication, errors, rate limits.
• Concepts: proof bundle — the shape of the bundle returned by /v1/attestations/:id/bundle.