Submission policy

This page describes the rules Vitrified applies to a submission between the moment your SDK call hits the API and the moment the leaf lands in the next batch window.

Metadata validation

Every submission declares a metadata schema. Vitrified validates the metadata payload against the corresponding JSON Schema. The full schema set:

• purl — Package URL.
• oci — OCI artifact digest.
• git — commit / tree / blob / tag.
• slsa.provenance.v1 — SLSA v1 provenance predicate.
• intoto.statement.v1 — in-toto v1 statement envelope.
• dsse — opaque DSSE envelope payload.
• generic — free-form structured metadata.

The authoritative schemas live in spec/schemas/.

Validation failure is not a witness failure

If metadata validation fails, the hash is still queued for witnessing in the next batch. The metadata is flagged as draft and you can correct it via a follow-up PATCH. This decouples stamping throughput from metadata correctness so you never lose a witness window to a schema error.

Foot-gun warnings

The submission API surfaces warnings if it can detect that the artifact will likely drift out-of-band of its hash:

Warnings never block (except the hard-block list); they appear in the response body's warnings array and in the dashboard's submission detail view.

Idempotency

Submissions accept an optional Idempotency-Key header. Two requests with the same idempotency key within the retention window (default 24h) return the same submission record, including the same leaf and (eventually) the same bundle. The idempotency key is per-API-key.

The witnessing engine itself is deterministic: even without an idempotency key, two submissions with identical canonicalized envelopes produce the same leaf identifier. The idempotency key only affects whether the API returns a fresh submission record or a deduplicated one.

Rate limits

Default per-API-key limits:

• Submissions: 60 / sec, 10k / hour, 100k / day.
• Reads (bundle fetch, submission lookup): 600 / sec.
• Webhook deliveries from Vitrified to your endpoint: 100 / sec, bursting to 1k.

Limits are advisory at low tiers; higher tiers raise them. The X-RateLimit-* headers carry remaining quota.

Retention

• Proof bundles: retained indefinitely. Bundles are immutable once witnessed.
• Submission metadata: retained for the lifetime of your account; you can delete individual submissions via API, which redacts the metadata but preserves the bundle and its leaf identifier in the audit log.
• Webhook delivery logs: 90 days at default tier; longer on higher tiers.
• Audit log: retained for the lifetime of your account.

See also

• API reference — the HTTP endpoint contracts.
• Webhook events — the events you can subscribe to.