Attestations¶

Create an Attestation¶

POST /v1/attestations

Certifies a piece of content. Computes its IPFS CID, records a pending attestation, and queues the commit/reveal transactions. This call returns immediately and does not wait for the chain.

Request Body¶

{
  "content": "The full plain-text body of the article...",
  "chainId": 11155111,
  "url": "https://example-news.com/articles/some-story",
  "metadata": { "author": "Jane Doe" }
}

Field	Type	Required	Description
`content`	`string`	Yes	The exact plain-text content to attest. The IPFS CID and quote-verification hash are derived from this string — any change (even whitespace) produces a different CID.
`chainId`	`number`	No	Chain to publish on. Falls back to your organization's default chain, then the API's own default. `400` if none can be resolved.
`url`	`string`	No	Canonical URL of the published article.
`metadata`	`object`	No	Arbitrary free-form data stored alongside the attestation (not sent on-chain).

Response¶

202 Accepted for a new attestation:

{
  "id": "b3e1a6b0-6e77-4e37-9f0b-1a1a2f9d9c11",
  "status": "pending",
  "contentCid": "bafkreifzjut3te2nhyekklss27nh3k72ysco7y32koao5eei66wof36n5e",
  "chainId": 11155111,
  "authorityAddress": "0xD2f2c95962632B4742703CC058889c624380C748"
}

Field	Type	Description
`id`	`string (uuid)`	Identifier for polling this attestation's status.
`status`	`string`	One of `pending`, `committed`, `confirmed`, `failed`. See status lifecycle.
`contentCid`	`string`	The IPFS CID computed from `content`.
`chainId`	`number`	The chain the attestation will be published on.
`authorityAddress`	`string`	Your organization's authority address this attestation is attributed to.

Idempotent by content

Submitting identical content for the same publisher and chainId again does not create a duplicate. The existing attestation is returned instead, with HTTP 200 (not 202). This makes it safe to retry a request after a network error without double-publishing.

If the content is found to already be attested on-chain under your authority (e.g. published through another tool), the response is returned with status: "confirmed" and 200, and no background work is queued.

Get an Attestation¶

GET /v1/attestations/:id

Returns the current state of a single attestation. Use this to poll after receiving a 202.

Response¶

{
  "id": "b3e1a6b0-6e77-4e37-9f0b-1a1a2f9d9c11",
  "url": "https://example-news.com/articles/some-story",
  "chainId": 11155111,
  "authorityAddress": "0xD2f2c95962632B4742703CC058889c624380C748",
  "contentCid": "bafkreifzjut3te2nhyekklss27nh3k72ysco7y32koao5eei66wof36n5e",
  "status": "confirmed",
  "commitTxHash": "0x1234...",
  "revealTxHash": "0xabcd...",
  "attestationIndex": 4,
  "error": null,
  "childAttestationId": null,
  "childLinkTxHash": null,
  "createdAt": "2026-08-01T19:52:58.304Z",
  "confirmedAt": "2026-08-01T19:54:31.912Z"
}

attestationIndex is set once status is confirmed, and together with contentCid, chainId, and authorityAddress forms a complete attestation reference that can be independently verified.

childAttestationId and childLinkTxHash are set after a successful call to Link a Child Attestation.

A request for an attestation belonging to another publisher, or an unrecognized id, returns 404.

List Attestations¶

GET /v1/attestations?limit=50

Returns attestations for your organization, newest first.

Query param	Default	Max	Description
`limit`	`50`	`200`	Number of results to return.

Response¶

{
  "attestations": [
    { "id": "...", "status": "confirmed", "...": "..." }
  ]
}

Each entry has the same shape as Get an Attestation.

Link a Child Attestation¶

POST /v1/attestations/:id/child

Signals that a newer version of an attested article exists, by setting the attestation's childIpfsHash on-chain to point at another of your attestations. Use this when you've published an edit or replacement and want verifiers following the old article to be able to discover the new one.

Like creating an attestation, this call returns immediately and queues the on-chain transaction in the background — poll GET /v1/attestations/:id to see it land.

Request Body¶

{
  "childAttestationId": "5c9e2f0a-1c3b-4b8e-8f2a-9e7d3c1a2b44"
}

Field	Type	Required	Description
`childAttestationId`	`string (uuid)`	Yes	The `id` of the newer attestation to link to. Must belong to your organization.

The attestation in the URL (:id) — the old one being superseded — must already be confirmed.

Response¶

202 Accepted once the on-chain update has been queued:

{
  "id": "b3e1a6b0-6e77-4e37-9f0b-1a1a2f9d9c11",
  "status": "confirmed",
  "childAttestationId": "5c9e2f0a-1c3b-4b8e-8f2a-9e7d3c1a2b44",
  "childLinkTxHash": null,
  "...": "..."
}

Once the link transaction is mined, childLinkTxHash is populated — poll GET /v1/attestations/:id to confirm.

Overwriting a link

The contract does not restrict setChildIpfsHash to a single call — calling this endpoint again with a different childAttestationId re-submits the transaction and overwrites the previous link on-chain. Re-posting the same childAttestationId after it has already landed is a no-op and returns 200.

A request for an attestation that isn't yet confirmed, or for a childAttestationId that doesn't exist or belong to your organization, returns an error — see Errors.

Status Lifecycle¶

stateDiagram-v2
    [*] --> pending
    pending --> committed: commit tx mined
    committed --> confirmed: reveal tx mined
    pending --> failed: unrecoverable error
    committed --> failed: unrecoverable error
    confirmed --> [*]
    failed --> [*]

Status	Meaning
`pending`	Accepted, not yet submitted on-chain.
`committed`	The commit transaction has been mined; waiting out the reveal delay (~60s).
`confirmed`	The reveal transaction has been mined. `attestationIndex` is now set and the attestation is publicly verifiable.
`failed`	Certification could not complete — see `error` for details. Failures are not retried automatically; see Errors.