Verified Handles

Verified Handles API

Verified Handles as data: every public entry, its handles and images, its history, and search. It answers with the same data as the pages, built by the same…

Data & analytics#open-data

Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.

Overview

Verified Handles as data: every public entry, its handles and images, its history, and search. It answers with the same data as the pages, built by the same code. Entry text is CC0, except a description taken from Wikipedia, which is CC BY-SA 4.0 (description_license): where you show it, show the article (description_source.url), the licence by name with a link (CC BY-SA 4.0), and “adapted from” when description_source.adapted is true, and share alike. Images are licensed by their owners, and each says how (image_rights). Email addresses are never published as data.

Keys. An entry answers to its VHID (11 digits, permanent), its short name, or an old name.

Paging. Lists page by limit and offset; follow next_offset until it is null. Offsets stop at 10,000: past that they are clamped, silently.

Caching. Responses say how long they may be kept (Cache-Control, and x-cache on each operation). An entry carries a strong ETag: send it back as If-None-Match and an unchanged entry answers 304.

Cross-origin. /api/v1 answers any origin (Access-Control-Allow-Origin: *, GET only, no credentials). The .json addresses beside the pages are same-origin.

Rate limit. 120 requests a minute per IP address across the JSON reads; past it, a 429 with Retry-After.

Errors are JSON: {"error": " "}, with a field or two more where they help.

Endpoints 107

Claiming an entry

  • POSTStart a claim/api/entity/:vhid/claimsStarts proving that you run the person or organisation an entry is about. It answers a token: publish it on a page the entry lists (url), in a DNS TXT record…
  • POSTCheck a claim’s proof/api/claims/:id/verifyChecks the claim’s proof by its method: the token on the page the entry lists (url, fetched once, through the same guard as every fetch the site makes), in a…

Drafts

  • GETRead your draft of an entry/api/entity/:vhid/draftYour unsaved edit to the entry, as you last kept it, in the editor’s own shape.
  • PUTKeep a draft of an entry/api/entity/:vhid/draftKeeps your unsaved edit to the entry, replacing any draft of it you had, and moves its expiry to 30 days from now. The description is cleaned with the same…
  • DELETEDiscard your draft of an entry/api/entity/:vhid/draftDeletes your draft of the entry, a deleted entry’s too. deleted is false when there was none to delete.
  • GETList your drafts/api/entity/draftsEvery draft you keep, the most recently changed first, without their contents.
  • POSTHold a signed-out draft through a sign-in/api/entity/:vhid/draft/handoffWhat the editor’s “Sign in to save” sends before it leaves for sign-in, so the edit still comes along when the sign-in finishes in another browser (a sign-in…
  • POSTClaim a draft held through a sign-in/api/entity/:vhid/draft/handoff/claimRedeems a token …/draft/handoff answered: answers the draft, keeps it as your draft of the entry (as PUT …/draft would, 30 days) and deletes the held copy, so…

Proposing changes

  • GETRead an entry for editing/api/editor/:vhidWhat the editor opens with: the fields a change may send, as they are now, the current revision to send as base_revision_id, each handle with who manages it,…
  • GETRead an entry as it was/api/entity/:vhid/revisions/:refThe whole entry as it was at one revision made on Verified Handles, for proposing to put it back. History kept from the old wiki is wikitext, not fields:…
  • GETFind an entry to link to/api/entity/search?q=jamesThe editor’s link search: up to 8 entries by name, words or QID, for a link in a description. Unlike the public search it is never cached, so an entry made a…
  • POSTPropose a change to an entry/api/entity/:vhid/proposalsQueues a change for a reviewer, who approves it into the entry or turns it down. Send only the fields that change, with the baseRevisionId you read as…
  • POSTPropose a new entry/api/entityQueues a new entry for a reviewer. Give it a title and, if it has one, its Wikidata item (qid); an entry already on that item is named instead (409), and an…
  • POSTPropose or make many changes at once/api/entity/batchUp to 25 edits in one request, each to a different entry: all proposals (mode: "propose", as POST /api/entity/{vhid}/proposals) or all live edits (mode:…
  • POSTSee a description as it would be stored/api/entity/description-previewThe HTML a save would store for this description, and nothing written: the same steps a live edit or an approved proposal runs ([[VHID]] and [[short]] links…
  • POSTSee an edit’s changes before sending it/api/editor/:vhid/changesAn edit not yet sent, against the entry as it is now, as the site’s diff viewer shows it: the editor’s Show changes. The review queue reads a proposal the…
  • GETFind an image the site already holds/api/media/library?q=jamesThe image picker’s “On Verified Handles” tab: images the site holds that may go on an entry (never a withdrawn one), found by the entries that show or showed…
  • GETSearch Wikimedia Commons for an image/api/media/commons/search?q=Ada LovelaceThe image picker’s Commons tab: up to 24 image files on Wikimedia Commons, each with a signed token that names it to the site. It asks Commons; when Commons…
  • POSTChoose a Commons file/api/media/commonsTurns a search hit’s token into an image the site holds, so a proposal can name it (image_id). The same file picked again answers the same image. It takes the…
  • GETRead a Wikidata item/api/wikidata/items/:qidWhat a Wikidata item says, the way the Wikidata sync would store it: label, description, image and handles, with the entries already on it. For proposing what…

Your account

  • GETWho you are/api/v1/meThe account the bearer belongs to: its role and capabilities, whether it is blocked, the Terms of Service it accepted, how much waits on it in each queue it…
  • PATCHChange your preferences/api/v1/me/prefsChanges the preferences sent; the others stay as they are. The website’s PATCH /api/user/prefs changes the same ones. The body may be at most 1 KiB. Send the…
  • POSTAccept the Terms of Service/api/v1/me/termsRecords that the account accepted the Terms of Service now in force (and the Privacy Policy published with them). Send the version the app showed: any other…
  • GETList where you are signed in to the app/api/v1/me/sessionsThe phones signed in to the Verified Handles app as this account, most recently used first; current marks the one asking (none, with a key). Website sign-ins…
  • DELETESign one device out of the app/api/v1/me/sessions/:idEnds that app session. It does not stop whoever holds the phone from signing in again, if its browser is still signed in to JEMEDIA: for a lost or stolen…
  • POSTSign out everywhere/api/v1/me/sessions/revoke-allEnds every app session of the account (the one asking too) and every website sign-in, at once. Keys and connected apps are left alone. JEMEDIA’s own sign-ins…
  • POSTDelete your account/api/v1/me/deleteDeletes the Verified Handles account at once and for good, exactly as My account → Settings does: every session and API key (this one too), the profile,…
  • POSTRegister this phone for push notifications/api/v1/me/devicesRegisters the phone the app session runs on, or refreshes its registration: send it at each start and whenever a token changes. It is matched by its Expo…
  • DELETEStop pushing to a phone/api/v1/me/devices/:idRemoves a phone’s registration: nothing more is pushed to it. A phone that is not the account’s is 404. Send the app’s own access token as Authorization:…
  • PATCHChange which pushes a phone gets/api/v1/me/devices/:idChanges a registered phone’s prefs (only those sent), its locale or its app version. A phone that is not the account’s is 404, as one that never existed. The…
  • POSTSend a test push to a phone/api/v1/me/devices/:id/testSends one fixed push (“Notifications are working”, data.type test) to one of the account’s phones at once, through the same push service as every other, and…
  • GETYour saved entries/api/v1/me/savedThe account’s saved entries are the Verified Handles app’s Saved list, kept so it follows the person between phones: the account’s own, never shown to anyone…
  • PUTSave an entry/api/v1/me/saved/:vhidThe account’s saved entries are the Verified Handles app’s Saved list, kept so it follows the person between phones: the account’s own, never shown to anyone…
  • DELETERemove a saved entry/api/v1/me/saved/:vhidThe account’s saved entries are the Verified Handles app’s Saved list, kept so it follows the person between phones: the account’s own, never shown to anyone…
  • POSTAdd many saved entries at once/api/v1/me/saved/mergeThe account’s saved entries are the Verified Handles app’s Saved list, kept so it follows the person between phones: the account’s own, never shown to anyone…
  • GETRead your preferences/api/user/prefsThe preferences of the account the key belongs to. Signed out, it still answers 200, with every value null, so a client need not check first.
  • PATCHChange your preferences/api/user/prefsChanges the preferences sent, each on its own; the others stay as they are. The body may be at most 1 KiB.
  • GETList your API keys/my/settings/api-keys.jsonEvery key your account has made, live or not, newest first; this_key marks the one making the request. Never a secret. Any account may list its own, even one…
  • POSTRevoke one of your API keys/my/settings/api-keys/:id/revokeRevokes the key at once, audited: anything using it stops working. Revoking the key that makes the request is allowed, and is its last request. Back to the…
  • GETWhat one of your API keys did/my/settings/api-keys/:id/activity.jsonEvery change made with one of your keys (the audit log’s rows that name it), newest first, 50 a page. Changes, not reads: reading writes no row. Page with…
  • GETList what you have sent for review/my/submissions.jsonYour proposals, new entries, claims, reports and applications, newest first, 25 to a page: every one, or with status=open only those still waiting on a…
  • GETRead one of your submissions, with its conversation/my/submissions/:fileOne submission, what it asked for (payload, as it was sent) and its comments, oldest first. Its submitter and reviewers may read it; to anyone else it is 404,…
  • POSTComment on one of your submissions/my/submissions/:id/commentsAdds a comment to the submission’s conversation, which its reviewers read. Answers as the page’s form does: back to the submission, done=commented, or…
  • POSTWithdraw one of your submissions/my/submissions/:id/retractWithdraws a submission of yours that is still waiting on a decision: it leaves the queue, marked retracted. Back to the submission, done=retracted, or…
  • POSTSet your account’s preferences/my/settings/prefsSets every preference on the Settings page at once, as its form does: a box left out is switched off. PATCH /api/user/prefs changes one at a time instead.
  • POSTHave the site email your address again/my/settings/email-resumeTakes your own address off the email suppression list, after Amazon SES reported it as a permanent bounce or a spam complaint. Nothing changes when it is not…
  • GETDownload everything the site holds about you/my/settings/data.jsonYour account, preferences, submissions, comments, notes, API keys (never a secret), your entries in the audit log, the edits you made, proposed or hid, what…
  • POSTSign one device out of the app/my/settings/devices/:id/revokeEnds one of your app sessions, as Account → Devices’ Remove does (DELETE /api/v1/me/sessions/{id} is the same for the app). Back to the Settings page,…
  • POSTSign out everywhere/my/settings/sign-out-everywhereEnds every app session and every website sign-in of the account, this one included, as Account → Devices’ button does (POST /api/v1/me/sessions/revoke-all is…
  • POSTDelete your account/my/settings/deleteDeletes the account at once and for good: every session and API key (this one too), the profile, preferences and unpublished submissions and unsaved drafts.…

Contributing

  • GETStart an edit/api/v1/entities/:vhid/edit-contextWhat a change to the entry starts from: the revision to send back, its fields and handles, what the person may do there, and their kept draft; and what the…
  • GETWhat you may do on an entry/api/v1/entities/:vhid/meWhether the person may edit the entry live, propose to it or claim it; their claim on it; their open submissions on it. Send the app’s access token or an API…
  • POSTSee what a change does/api/v1/entities/:vhid/proposals/previewThe change against the entry as it is now, as the review queue will read it: each field before and after, the handles added and removed. Writes nothing. An…
  • POSTSee a description as it would be stored/api/v1/entities/:vhid/description/previewA description, in HTML (description) or Markdown (description_markdown), exactly one, as a save would store it: the shared parser, its cross-links resolved,…
  • POSTChange an entry/api/v1/entities/:vhid/proposalsFor someone who may edit the entry live, the change is saved at once (a revision, audited edit), and the answer carries the entry’s rev, to re-read GET…
  • POSTUndo a live save/api/v1/entities/:vhid/revisions/:revision_id/undoThe "Saved" toast’s Undo: puts the entry back as it stood before one of your own live saves (revision_id, from the save’s answer), as a new revision with the…
  • GETYour unsent edit/api/v1/entities/:vhid/draftThe person’s kept draft of the entry, from the app or the website. Send the app’s access token or an API key as Authorization: Bearer; a browser session is…
  • PUTKeep an unsent edit/api/v1/entities/:vhid/draftKeeps the person’s draft of the entry for 30 days, replacing any before, the website editor’s too: the same one draft per account and entry. Its fields…
  • DELETEDiscard an unsent edit/api/v1/entities/:vhid/draftDiscards the person’s draft of the entry; deleted says whether there was one. Send the app’s access token or an API key as Authorization: Bearer; a browser…
  • POSTPropose a new entry/api/v1/entitiesQueues a new entry for review (audited propose), with no rev: nothing is created until it is approved. Needs propose. Takes Idempotency-Key. It runs the…
  • POSTStart a claim/api/v1/entities/:vhid/claimsStarts claiming the entry (doc 02 §6): a single-use token to place on a profile listed on it (url), in a TXT record of its domain (dns), or none for email…
  • POSTFinish a claim/api/v1/claims/:id/verifyChecks the proof now, from the server. Proved: the entry is the account’s, and the answer carries its rev. A proof an administrator decides first (a transfer,…
  • GETIs it on Verified Handles already?/api/v1/applications/checkBefore applying: the entry already on the Wikidata item, and up to five whose names match the title. Local reads only. It runs the website’s own steps (GET…
  • POSTApply for a new entry/api/v1/applicationsFiles an application (doc 02 §4.5) from the form’s fields as JSON: each a string, a repeated one (handle_platform, handle_value, risk_link, press_url, …) a…
  • GETYour submissions/api/v1/me/submissionsThe person’s own proposals, new entries, claims, reports and applications, newest first. Send the app’s access token or an API key as Authorization: Bearer; a…
  • GETOne of your submissions/api/v1/me/submissions/:idWith what it proposed (payload) and its thread, each author named as the person may see them (doc 02 §3.4). Another account’s is 404. Send the app’s access…
  • POSTReply in a thread/api/v1/me/submissions/:id/commentsUp to 2,000 characters (longer is cut), blocked-words-guarded, audited comment. A reply to an application waiting on its applicant returns it to the reviewers…
  • POSTWithdraw a submission/api/v1/me/submissions/:id/retractWhile it is open; a decision made first stands (409, with its current.status). Audited retract. It runs the website’s own steps (POST…
  • POSTReport an entry, a comment or a contributor/api/v1/reportsLands in Console → Reports, as a report from the entry’s page does (doc 02 §4.6). target.id is an entry’s VHID; a comment’s id, from a thread the person may…
  • GETWhat the account may upload/api/v1/media/upload-rulesWhether the account may upload an image (POST /api/v1/media), the licences it may choose from, and the limits on the file, the credit and the source. Any…
  • POSTUpload an image/api/v1/mediaStores an image file with its rights, through the website upload’s own steps: the same rights rules, the bytes sniffed and re-encoded as a lossless WebP with…

Entries

  • GETGet many entries at once/api/v1/entities?ids=james,53500361835,Verified_HandlesUp to 50 entries in one request: the batch form of GET /api/v1/entities/{vhid}. Each key is answered exactly as that route answers it, in the order asked: the…
  • GETGet an entry/api/v1/entities/:vhidEverything the entry’s page shows, as data: its title, description, images with their rights, and handles. It is built by the same code as the page, so the…
  • GETGet an entry’s handles/api/v1/entities/:vhid/handlesJust the entry’s handles, in the order its page shows them: the same list as handles in the entry. An email address is listed with its value, label and URL…
  • GETCheck whether copies of entries are current/api/v1/stamps?ids=53500361835,10000000002For up to 200 VHIDs, each entry’s rev (as its body carries it), without reading the entries: a copy whose rev differs is out of date. A VHID that now leads to…
  • GETFind the entries that list a handle/api/v1/handlesWhich public entries list this handle: “is x.com/someone an official account, and whose?”. Ask by platform and value, or by url, a profile’s address, which is…
  • GETIs this account on Verified Handles?/api/v1/lookup?q=https://x.com/james/status/1For whatever text a share sheet or a paste hands over: the site reads it, so a caller never has to. The first address in the text that names a profile is read…
  • GETWhen an entry last changed/:key/freshnessWhen the entry last changed, never cached: a cheap way to tell whether a copy you hold is stale. An old name answers for the entry it leads to. Each call…
  • GETGet an entry, at its page’s address/:key.jsonThe entry as data, at its page’s address plus .json: the same body as GET /api/v1/entities/{vhid}. An old name or a merged entry’s key answers with the entry…

History

  • GETGet an entry’s revision history/api/v1/entities/:vhid/historyThe entry’s public revision history, newest first, a page at a time: the history kept from the old wiki and every edit made since. Hidden and deleted…
  • GETGet one revision, with what it changed/api/v1/entities/:vhid/history/:ref_idOne revision of the entry’s public history: its row in the history, and changes, each field, handle and image it changed, in the shape of a review item’s…
  • GETGet an entry’s history, at its history page’s address/:key/history.jsonThe entry’s public revision history as its history page shows it: newest first, 50 to a page, by page number. GET /api/v1/entities/{vhid}/history gives the…

Search

  • GETSearch the entries/api/v1/search?q=jamesFull-text search over every public entry’s title, short name, subtitle and description, best match first. The first page leads with the entries whose title or…
  • GETSuggest entries as a name is typed/api/v1/suggestThe site’s own typeahead, for a search box: entries whose title or short name starts with, contains or nearly matches what has been typed so far (tesl finds…
  • GETGet the homepage’s Trending entries/api/v1/trendingThe entries the site’s homepage shows under Trending, in its order, from the same code: the ones the site has picked first, then, when the site has it turned…
  • GETSuggest entries as a name is typed/get_dataWhat the search box suggests: up to 10 entries whose name starts with, contains or nearly matches the text, best first. With no text, the trending entries. A…

About the API

  • GETGet this document/api/v1/openapi.jsonThis description of the public API, as OpenAPI 3.1. It is generated from the same registry the routes are tested against, so it changes when the API does. Any…
  • GETGet the app contract/api/v1/app/contract.jsonThe operations of this API the Verified Handles app calls, as OpenAPI 3.1 with the same schemas as this document. Each is held to the shape the app was built…
  • GETGet the Verified Handles app’s config/api/v1/app/configWhat the Verified Handles app reads when it starts: the oldest release each store may run, a notice to show, how the iOS sign-in comes back, the contribution…
  • GETGet the platform catalog/api/v1/platformsEvery platform an entry’s handles may be on, in the order a page lists them, with what a page draws for each: its name, how a value becomes a link, its colour…

The app

  • POSTSend the app’s crash reports/api/v1/app/errorsWhere the Verified Handles app sends its crash reports: a Sentry envelope tunnel to the site’s own GlitchTip. An envelope is taken only when its header’s dsn…
  • POSTSend the app’s crash reports (native SDKs)/api/v1/app/errors/api/:project_id/envelope/Where the app’s native Sentry SDKs post every crash report: the envelope endpoint of the DSN https://<public…

Applying for an entry

  • GETCheck for an entry before applying/applications/check.jsonWhether the site already has the entry you would apply for: the entry on a Wikidata item, and up to 5 entries whose names match a title. It reads only this…
  • GETFind the Wikidata item to apply with/applications/wikidata.json?q=Ada LovelaceUp to 6 Wikidata items whose names match, each with the entry already on it. It asks Wikidata, within a lookup budget per account and for the site; past the…
  • POSTApply for an entry/applicationsFiles an application, which a reviewer decides; you are told by email, and can follow it at /applications/{id}. Check first with GET /applications/check.json:…
  • POSTReply on your application/applications/:id/commentsAdds to the application’s conversation with its reviewers; a reply to a question (needs_info) puts it back in their queue. Back to the application, or…
  • POSTWithdraw your application/applications/:id/retractWithdraws it while it is still open. Back to the application, or ?error=cannot_retract once it is decided.
  • POSTHold a signed-out application through a sign-in/applications/handoffWhat the application form sends before it leaves for sign-in, so what was typed still comes along when the sign-in finishes in another browser (a sign-in link…
  • POSTClaim an application held through a sign-in/applications/handoff/claimRedeems a token POST /applications/handoff answered: answers the form’s values and deletes the held copy, so a token works once. Nothing is kept with your…

Entry manager

  • GETFind an entry by name, for a console form or the console search/console/findUp to 10 entries matching find: blocked ones too for an account with manage_entries or suppress_history, else what the public search finds. Each says whether…

Connecting an app

  • GETWhere to sign in for /mcp/account/.well-known/oauth-protected-resource/mcp/accountRFC 9728 protected resource metadata for the MCP address /mcp/account, the one that signs a person in: with no token it answers 401. A 401 from that address…
  • GETWhere to sign in for /mcp/.well-known/oauth-protected-resource/mcpRFC 9728 protected resource metadata for the MCP address /mcp, which also answers with no token at all, with the public reads. A 401 from that address names…
  • GETThe authorization server/.well-known/oauth-authorization-serverRFC 8414 authorization server metadata: where to send the person (authorization_endpoint), where to get and refresh tokens, and what the server supports. The…
  • POSTExchange a code, or refresh a connection/oauth/tokenThe OAuth 2.1 token endpoint, for MCP clients a person has connected to their account. grant_type=authorization_code redeems the one-time code the person’s…
  • POSTDisconnect/oauth/revokeToken revocation (RFC 7009). Either of a connection’s current tokens ends the whole connection: the person consented once, so there is one thing to end. A…
  • POSTRegister a client/oauth/registerDynamic Client Registration (RFC 7591), for an MCP client without a Client ID Metadata Document (Cursor is one). It sends its client_name and redirect_uris…

Reporting an entry

  • POSTReport an entry/:key/reportReports a problem with an entry to the site’s reviewers. It is the report page’s own form, so it answers as the form does: a 303 back to the page, ?sent=1…

API details

Base URL
https://verifiedhandles.org
Authentication
A bearer token in the Authorization header
Operations
107 operations on 99 pathsGET 49POST 47DELETE 5PUT 3PATCH 3
Main resources
Your account 30Contributing 21Proposing changes 12Entries 8Applying for an entry 7Connecting an app 6Drafts 6About the API 4Search 4History 3
Response formats
application/json text/html text/plain
Description format
OpenAPI 3.1.0, API version 1.6.0

How to test the Verified Handles API in Swastik Codes

  1. Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
  2. Fork it into your workspaceChoose a workspace. You get your own copy of the Verified Handles API collection, without the publisher's secrets.
  3. Add your credentialsThis API uses A bearer token in the Authorization header. Add yours in the collection's variables or an environment; the requests already reference it.
  4. Send a requestPick an endpoint, for example “Start a claim” (POST /api/entity/:vhid/claims), and press Send. Check the response, add tests and run the whole collection with the runner.

Frequently asked questions

What is the Verified Handles API?

Verified Handles as data: every public entry, its handles and images, its history, and search. It answers with the same data as the pages, built by the same… It is listed under Data & analytics and has 107 endpoints.

Who publishes the Verified Handles API?

It is listed from Verified Handles's public API description (an OpenAPI document), not published by Verified Handles on Swastik Codes. Anyone who controls verifiedhandles.org can claim the profile by adding a DNS TXT record.

What is the base URL of the Verified Handles API?

Requests go to https://verifiedhandles.org. Endpoint paths are added to this base URL.

How do I authenticate with the Verified Handles API?

With A bearer token in the Authorization header.

How many endpoints does the Verified Handles API have?

107 operations on 99 paths (49 GET, 47 POST, 5 DELETE, 3 PUT, 3 PATCH). The largest groups are Your account, Contributing, Proposing changes, Entries.

Is forking the Verified Handles API free?

Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.

Suggest an API

Tell us which public API is missing. We check it, then add it here with its endpoints when it has an OpenAPI (Swagger) description.