Read a card’s statements

A card’s signed statements, newest first, each with what a client checks it with. The same address without .json is the page that checks them.

GET/{kind}/{card}/statements.json

Access: Public; API key optional
Client: Browser fetch supported

Other addresses#

/{kind}/{card}/statements

Parameters#

Name	Location	Meaning
`kind`Required	Path	u for a person, o for an organisation.
`card`Required	Path	The card’s permanent number or its current alias.
`before`	Query	Only statements before this log position: next of the page before.
`limit`	Query	1 to 100, 20 by default.

Request examples#

cURL

curl -fsS 'https://veil.rip/u/1/statements.json'

Response#

HTTP 200application/json

The card’s statements.

Field	Type	Meaning
`card`	`object`	n, type, name, token and url of the card.
`total`	`integer`	How many statements the card has in the log, retractions included.
`statements`	`array<object>`	This page, newest first.
`next`	`integer \| null`	The before of the next page, or null.
`feed`	`string`	The card’s Atom feed.

Expand a nested object for its fields. Types ending in null allow a null value; optional fields may be absent. Other fields are present in that object.

Statement

Field	Type	Meaning
`id`	`integer`	The entry’s position in the log: the statement’s permanent id.
`kind`	`string`	statement or alert.
`n`	`integer`	The card the statement is by.
`signer`	`object`	n and token of the person card whose key signed: the card itself, or an owner or admin of an organisation.
`statement`	`string`	The statement as signed, canonical JSON. Its fields are repeated below for display.
`salt`	`string`	32 bytes in hex: c of the entry is SHA-256(salt ‖ statement).
`entry`	`string`	The log entry with its signature, as the log holds it.
`i`	`integer`	The entry’s position in the log (the same as id).
`publishedAt`	`string \| null`	The earliest cosignature on the first checkpoint holding the entry.
`checkpoint`	`object \| null`	size and note of the cosigned checkpoint that dates the entry. Null when the log could not be read.
`inclusion`	`array<string> \| null`	The entry’s RFC 6962 inclusion proof in that checkpoint, hex, deepest first.
`title`	`string`	The title, 1 to 200 characters.
`text`	`string`	The text, 1 to 4 000 characters, line breaks kept.
`link`	`string \| null`	An optional https link.
`retracts`	`integer \| null`	The id of the statement this one retracts.
`retractedBy`	`object \| null`	id, publishedAt and title of the statement that retracts this one.
`url`	`string`	The statement’s page.

Response headers#

Header	Value	Meaning
`Content-Type`	`application/json`	Use the declared media type before choosing a parser.
`Date`	`HTTP date`	Server time. Compare it with your clock when signing requests.
`Cache-Control`	`no-cache`	Ask again each time: a new statement or alert shows at once.

What to verify#

Check each item before you show it as the card’s: canonical statement, c = SHA-256(salt ‖ statement), the entry’s signature over "veil-rubrica:card-entry:v2\n" and the entry without signature, with a key active for the signer at position i (from the signer’s authority versions), and the inclusion in a checkpoint signed by the log and cosigned by a quorum. The list itself is the server’s word: it can leave out an entry.

Errors#

API errors return an error object. Use error.code for program logic; error.message is English text for people and can change. Response and error guide

HTTP	Code	Meaning and next step
400	`invalid_parameter`	A path, query or body field is missing, malformed or outside its accepted range. Correct the field named in `error.message` before sending again.
400	`wrong_format`	The request or the read belongs to the other log format than this server’s: a v1 record on a format 2 log, or a format 2 read on a format 1 log. Read `format` in GET /v1/log (absent means 1) and send the shape of that format.
404	`not_found`	The requested card, key, alias, code or resource was not found. Check the identifier. Temporary codes and previews may already have expired or been used.
410	`erased`	The card existed and was erased or removed. The response also carries its public erasure receipt. Stop using this card as current authority. Retain only the public receipt if needed.

Shared request errors

HTTP Code Meaning and next step

429

HTTP	Code	Meaning and next step
429	`rate_limited`	An anonymous, signed-request or API-key allowance was exceeded. Wait at least `Retry-After` seconds. Share a queue and retry budget across your workers.
500	`internal_error`	An unexpected server error occurred. Internal details are not returned. Retry reads with bounded backoff. Check write results before sending a new signed operation.
503	`busy`	The application has reached a temporary concurrency or database limit. Wait `Retry-After` seconds and retry with bounded backoff.

rate_limited

An anonymous, signed-request or API-key allowance was exceeded.

Wait at least Retry-After seconds. Share a queue and retry budget across your workers.

500

internal_error

An unexpected server error occurred. Internal details are not returned.

Retry reads with bounded backoff. Check write results before sending a new signed operation.

503

busy

The application has reached a temporary concurrency or database limit.

Wait Retry-After seconds and retry with bounded backoff.

Read this entry as JSON