Cerca una scheda

Trova la scheda che ha un account, una chiave o un’impronta esatti.

GET/v1/lookup

Accesso: Pubblico; chiave API facoltativa
Client: Fetch dal browser supportato

Parametri#

Nome	Posizione	Significato
`discord`	Query	ID utente Discord numerico stabile, da 17 a 20 cifre.
`github`	Query	ID numerico dell’account GitHub, non il login.
`email`	Query	L’indirizzo email completo.
`domain`	Query	Dominio esatto, senza punto finale. I domini internazionali usano la forma ASCII A-label.
`fediverse`	Query	L’account completo @utente@server.
`key`	Query	Una chiave pubblica Ed25519 in hex o la chiave composita completa in base64. Anche una chiave pubblica di altri sistemi come la incolleresti: una riga OpenSSH con o senza commento, una chiave pubblica OpenPGP armata, una chiave pubblica minisign, una chiave ML-DSA in base64. Codifica il valore per l’URL.
`fingerprint`	Query	Le 12 parole in inglese o italiano, oppure le 60 cifre. Anche l’impronta di una chiave pubblica di altri sistemi: SHA256:… come la stampa ssh-keygen -l, l’ID di una chiave minisign in 16 cifre esadecimali, o le 40 cifre esadecimali dell’impronta di una chiave OpenPGP, maiuscole o minuscole, con o senza spazi o 0x. L’ID di una chiave OpenPGP non basta.

Esempi di richiesta#

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();

Prova la richiesta#

Risposta#

HTTP 200application/json

identity è la scheda breve. match riporta la ricerca normalizzata. takeover descrive un subentro in attesa, quando presente. La prova si legge nella scheda completa.

Campo	Tipo	Significato
`identity`	`CardLite`	Scheda breve trovata, priva della prova di inclusione.
`match`	`object`	by indica il parametro della ricerca; value è il suo valore normalizzato. Per una chiave pubblica di altri sistemi, value è la sua impronta ed external dà type, fp, label e addedIn.
`takeover`	`object \| null`	Trasferimento in attesa con toIdentity, openedAt e resolvesAt. Null se assente.
`alert`	`object \| optional`	Quando il proprietario della scheda ha dichiarato l’account cercato rubato, abbandonato o spostato e non l’ha dichiarato ripreso: platform, subject, display, state, since, to, logIndex, publishedAt. Mostralo prima di ogni altra cosa. La parola del server: la pagina della scheda lo controlla.

Apri un oggetto annidato per leggerne i campi. I tipi con null ammettono un valore null; i campi optional possono essere assenti. Gli altri campi sono presenti nell’oggetto.

Scheda breve CardLite

Campo	Tipo	Significato
`n`	`integer`	Numero permanente della scheda.
`url`	`string`	URL permanente con il numero della scheda.
`name`	`string`	Nome visualizzato corrente; un nome nascosto diventa Card seguito dal numero.
`initials`	`string`	Iniziali da mostrare in assenza di un’immagine.
`since`	`string`	Data della prima versione in YYYY-MM-DD UTC.
`id`	`string`	Impegno della prima versione in hex, da cui deriva l’impronta.
`version`	`integer`	Versione pubblicata corrente.
`keys`	`array<CardKey>`	Tutte le chiavi dei dispositivi e di recupero, incluse quelle revocate.
`links`	`array<CardLink>`	Account collegati e subentri in attesa.
`fingerprint`	`Fingerprint`	Dodici parole per lingua e dodici gruppi di cinque cifre.
`type`	`string`	person o organization.
`nameHidden`	`boolean`	Indica se lo staff nasconde il nome.
`logo`	`object, optional`	Tipo e URL dell’immagine; omesso in assenza di un’immagine visibile.
`alias`	`string \| null`	Alias corrente, che può cambiare.
`aliasUrl`	`string \| null`	Indirizzo dell’alias corrente. Usa n come identificatore permanente.

Chiave del dispositivo CardKey

Campo	Tipo	Significato
`id`	`string`	Etichetta del dispositivo mostrata sulla scheda.
`alg`	`string`	Nome leggibile dell’algoritmo.
`fp`	`string`	Chiave pubblica completa presente nel record firmato.
`ed25519`	`string`	Chiave Ed25519 o metà della chiave composita, in hex.
`since`	`string`	Data di aggiunta della chiave.
`state`	`string`	active, offline o revoked. Offline indica una chiave di recupero.
`revoked`	`string \| null`	Data di revoca, se revocata.
`role`	`string`	Ruolo di firma assegnato alla chiave.
`addedIn`	`integer`	Versione che ha aggiunto la chiave.
`revokedIn`	`integer \| null`	Versione che ha revocato la chiave.

Account collegato CardLink

Campo	Tipo	Significato
`service`	`string`	Identificatore della piattaforma.
`handle`	`string`	Nome visualizzato o account normalizzato.
`id`	`string \| null`	ID stabile del provider, quando distinto dal nome.
`how`	`string`	Metodo di prova, per esempio oauth, dns_txt, well_known, emailCode o backlink.
`at`	`string`	Data e ora del collegamento.
`state`	`string`	active o pending.
`until`	`string \| null`	Scadenza del subentro in attesa.
`takeover`	`integer \| null`	ID del subentro in attesa.
`unicode`	`string, optional`	Forma Unicode di un dominio internazionale. Usa il nome ASCII come identificatore.
`addedIn`	`integer \| null`	Versione che ha aggiunto il collegamento.
`logIndex`	`integer \| null`	Indice della versione nel registro, a partire da zero.
`check`	`CardLinkCheck, optional`	Il ricontrollo periodico della prova fatto dal server (dal 30 ottobre 2026), per un collegamento attivo a un dominio, al Fediverso o a GitHub che ha controllato almeno una volta. È la sua parola, non fa parte della scheda firmata.

Ricontrollo di una prova CardLinkCheck

Campo	Tipo	Significato
`state`	`string`	ok, failing (il posto ha risposto e la prova non c’è) o unreachable (nessuna risposta).
`at`	`string`	Data e ora dell’ultimo controllo che ha avuto una risposta.
`since`	`string, optional`	Da quando la prova non si conferma. Manca finché è ok.
`reported`	`boolean`	Vero quando sono passati 30 giorni senza conferma e il proprietario è stato avvisato. Il collegamento resta.

Impronta della scheda Fingerprint

Campo	Tipo	Significato
`words`	`object`	en e it contengono le stesse dodici posizioni nelle rispettive liste di parole.
`digits`	`array<string>`	Dodici gruppi di cinque cifre decimali.

Intestazioni della risposta#

Intestazione	Valore	Significato
`Content-Type`	`application/json`	Usa il tipo dichiarato per scegliere come leggere il corpo.
`Date`	`HTTP date`	Ora del server. Confrontala con il tuo orologio per firmare le richieste.
`Retry-After`	`integer seconds, on rate_limited or busy`	Attendi almeno questo intervallo prima di riprovare. Altri codici 429/503 non lo includono necessariamente.

Cosa verificare#

Risolvi il numero, poi verifica la scheda completa e l’account trovato nel suo record firmato.

Note d’uso#

Passa esattamente un parametro di ricerca. I nomi visualizzati non sono unici.

Errori#

Gli errori API restituiscono un oggetto error. Usa error.code nella logica del programma; error.message è un testo inglese per le persone e può cambiare. Guida a risposte ed errori

HTTP Codice Significato e cosa fare

400

HTTP	Codice	Significato e cosa fare
400	`invalid_parameter`	Un campo del percorso, della query o del corpo manca, è malformato o fuori intervallo. Correggi il campo indicato in `error.message` prima di inviare di nuovo.
404	`not_found`	La scheda, la chiave, l’alias, il codice o la risorsa richiesti non sono stati trovati. Controlla l’identificatore. Codici e anteprime temporanei potrebbero essere scaduti o già usati.

invalid_parameter

Un campo del percorso, della query o del corpo manca, è malformato o fuori intervallo.

Correggi il campo indicato in error.message prima di inviare di nuovo.

404

not_found

La scheda, la chiave, l’alias, il codice o la risorsa richiesti non sono stati trovati.

Controlla l’identificatore. Codici e anteprime temporanei potrebbero essere scaduti o già usati.

Quando usi una chiave API facoltativa

HTTP	Codice	Significato e cosa fare
401	`invalid_api_key`	La credenziale Bearer è malformata, sconosciuta, scaduta o revocata. Usa una chiave attiva. Per l’accesso pubblico anonimo, rimuovi del tutto `Authorization`. Credenziali non valide non attivano automaticamente l’accesso anonimo.
403	`api_key_scope`	La chiave API non ha il permesso read o verify, oppure l’endpoint non accetta chiavi Bearer. Usa il permesso corretto. Le modifiche alle schede e la gestione delle chiavi richiedono una firma del dispositivo.
403	`api_key_suspended`	Questa chiave API è sospesa. Chiedi allo staff di ripristinarla; un’altra chiave non rimuove la sospensione dell’account.
403	`developer_suspended`	L’account API del titolare è sospeso oppure la scheda titolare non è disponibile. Controlla l’account titolare e le restrizioni dello staff. Creare un’altra chiave non aggira la sospensione.

Errori comuni delle richieste

HTTP Codice Significato e cosa fare

429

HTTP	Codice	Significato e cosa fare
429	`rate_limited`	È stato superato un limite anonimo, delle richieste firmate o della chiave API. Attendi almeno i secondi indicati da `Retry-After`. Condividi coda e budget dei tentativi tra i tuoi processi.
500	`internal_error`	Si è verificato un errore imprevisto del server. I dettagli interni non vengono restituiti. Riprova le letture con attese crescenti e un limite. Controlla l’esito delle scritture prima di inviare una nuova operazione firmata.
503	`busy`	L’applicazione ha raggiunto un limite temporaneo di concorrenza o del database. Attendi i secondi indicati da `Retry-After` e riprova con attese crescenti e un limite.

rate_limited

È stato superato un limite anonimo, delle richieste firmate o della chiave API.

Attendi almeno i secondi indicati da Retry-After. Condividi coda e budget dei tentativi tra i tuoi processi.

500

internal_error

Si è verificato un errore imprevisto del server. I dettagli interni non vengono restituiti.

Riprova le letture con attese crescenti e un limite. Controlla l’esito delle scritture prima di inviare una nuova operazione firmata.

503

busy

L’applicazione ha raggiunto un limite temporaneo di concorrenza o del database.

Attendi i secondi indicati da Retry-After e riprova con attese crescenti e un limite.

Leggi questa voce in JSON