Look up a card

Find the card that holds one exact account, key or fingerprint.

GET/v1/lookup

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

Parameters#

Name	Location	Meaning
`discord`	Query	Stable numeric Discord user ID, 17 to 20 digits.
`github`	Query	Numeric GitHub account ID, not its login name.
`email`	Query	The complete email address.
`domain`	Query	Exact domain, without a final dot. International domains use their ASCII A-label.
`fediverse`	Query	The complete @user@server account.
`key`	Query	An Ed25519 public key in hex or the full composite public key in base64. Also a public key from elsewhere as you would paste it: an OpenSSH line with or without comment, an armoured OpenPGP public key, a minisign public key, an ML-DSA key in base64. URL-encode the value.
`fingerprint`	Query	The 12 words in English or Italian, or the 60 digits. Also the fingerprint of a public key from elsewhere: SHA256:… as ssh-keygen -l prints it, a minisign key ID in 16 hex digits, or the 40 hex digits of an OpenPGP fingerprint, in either case, with or without spaces or 0x. An OpenPGP key ID is not enough.

Request examples#

cURL

curl -fsS 'https://veil.rip/v1/lookup?key=73ad6159583a43f8ad230a215b758db680efcd3ce32ab8e83c622eeca883e68a'

javascript

const response = await fetch("https://veil.rip/v1/lookup?key=73ad6159583a43f8ad230a215b758db680efcd3ce32ab8e83c622eeca883e68a");
const result = await response.json();

Try the request#

Response#

HTTP 200application/json

identity is the short card. match gives the normalised query. takeover describes a pending account transfer when present. Fetch the full card for its proof.

Field	Type	Meaning
`identity`	`CardLite`	Matching short card, without an inclusion proof.
`match`	`object`	by names the lookup parameter; value is its normalised value. For a public key from elsewhere, value is its fingerprint and external gives type, fp, label and addedIn.
`takeover`	`object \| null`	Pending transfer with toIdentity, openedAt and resolvesAt. Null if none.
`alert`	`object \| optional`	When the card’s owner declared the account looked up stolen, abandoned or moved and has not declared it regained: platform, subject, display, state, since, to, logIndex, publishedAt. Show it before anything else. The server’s word: the card’s page checks it.

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.

Short card CardLite

Field	Type	Meaning
`n`	`integer`	Permanent card number.
`url`	`string`	Permanent URL using the card number.
`name`	`string`	Current display name; a hidden name becomes Card followed by its number.
`initials`	`string`	Initials for an image fallback.
`since`	`string`	Version-one date in YYYY-MM-DD UTC.
`id`	`string`	Version-one commitment in hex; the source of the fingerprint.
`version`	`integer`	Current published version.
`keys`	`array<CardKey>`	All device and recovery keys, including revoked keys.
`links`	`array<CardLink>`	Linked accounts and pending takeovers.
`fingerprint`	`Fingerprint`	Twelve words in each language and twelve five-digit groups.
`type`	`string`	person or organization.
`nameHidden`	`boolean`	Whether staff hide the name.
`logo`	`object, optional`	Image type and URL; omitted without a visible image.
`alias`	`string \| null`	Current alias; it can change.
`aliasUrl`	`string \| null`	Current alias address. Use n as the permanent identifier.

Device key CardKey

Field	Type	Meaning
`id`	`string`	Device label shown on the card.
`alg`	`string`	Readable algorithm name.
`fp`	`string`	Full public key as stored in the signed record.
`ed25519`	`string`	Ed25519 key or composite-key half, in hex.
`since`	`string`	Date the key was added.
`state`	`string`	active, offline or revoked. Offline denotes a recovery key.
`revoked`	`string \| null`	Revocation date, when revoked.
`role`	`string`	Signing role assigned to the key.
`addedIn`	`integer`	Version that added the key.
`revokedIn`	`integer \| null`	Version that revoked the key.

Linked account CardLink

Field	Type	Meaning
`service`	`string`	Platform identifier.
`handle`	`string`	Display handle or normalised account.
`id`	`string \| null`	Stable provider ID, when separate from the handle.
`how`	`string`	Proof method, such as oauth, dns_txt, well_known, emailCode or backlink.
`at`	`string`	Time the link was established.
`state`	`string`	active or pending.
`until`	`string \| null`	Pending takeover deadline.
`takeover`	`integer \| null`	Pending takeover ID.
`unicode`	`string, optional`	Unicode spelling of an international domain. Keep the ASCII handle as the identifier.
`addedIn`	`integer \| null`	Version that added the link.
`logIndex`	`integer \| null`	Zero-based log index of that version.
`check`	`CardLinkCheck, optional`	The server’s periodic re-check of the proof (since 30 October 2026), for an active domain, Fediverse or GitHub link it has checked at least once. Its word, not part of the signed card.

Re-check of a proof CardLinkCheck

Field	Type	Meaning
`state`	`string`	ok, failing (the place answered and the proof is not there) or unreachable (no answer).
`at`	`string`	Time of the last check that got an answer.
`since`	`string, optional`	Since when the proof has not confirmed. Absent while ok.
`reported`	`boolean`	True once 30 days passed without a confirmation and the owner was told. The link stays.

Card fingerprint Fingerprint

Field	Type	Meaning
`words`	`object`	en and it each contain the same twelve word-list positions in their language.
`digits`	`array<string>`	Twelve groups of five decimal digits.

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.
`Retry-After`	`integer seconds, on rate_limited or busy`	Wait at least this long before retrying. Other 429/503 codes do not necessarily include it.

What to verify#

Resolve the number, then verify the full card and the matched account in its signed record.

Usage notes#

Supply exactly one query parameter. Display names are not unique.

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

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.
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.

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.

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.

When using an optional API key

HTTP	Code	Meaning and next step
401	`invalid_api_key`	The bearer credential is malformed, unknown, expired or revoked. Use an active key. To use anonymous public access, remove `Authorization` entirely. Invalid credentials never fall back automatically.
403	`api_key_scope`	The API key lacks read or verify scope, or the endpoint does not accept bearer keys. Use the correct scope. Identity writes and key management still require a device signature.
403	`api_key_suspended`	This API key is suspended. Ask staff to restore it; another key cannot lift an account suspension.
403	`developer_suspended`	The owner’s API account is suspended or the owner card is unavailable. Check the owner account and any staff restriction. Creating another key does not bypass suspension.

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