VeriPix Badge Verification API

01 / request

Start with a VPX Badge ID

The path parameter must use this exact grammar:

VPX-YYYY-XXXXXXXX

YYYY is a four-digit year.
XXXXXXXX is eight characters from A-H J-N P-Z 2-9.
The identifier is uppercase; the alphabet omits I, O, 0, and 1.

A malformed ID returns HTTP 400 with code invalid_badge_id. A well-formed ID with no public issued record follows the privacy-safe 404 behavior below.

02 / integrate

Make the request

Send a GET request to the relative route from your application’s public origin. The endpoint does not require an API key or a session.

curl

curl --request GET \
  --url https://veripix.polsia.app/api/badges/VPX-2026-ABCD2345

03 / response

Read the public projection

An issued badge record returns HTTP 200 with ten top-level fields. Dotted paths below describe each nested registration and history field. The normalized status distinguishes active, revoked, and corrected records. Private account, payment, storage, and upload fields are never included.

Every sample below is illustrative, including its VPX ID and image URL. The base64 signature and public-key strings satisfy the response format but are synthetic, are not a production key pair, and cannot verify a real badge.

Successful lookups return HTTP 200. The embedded history and /api/badges/{badgeId}/history contain at most 100 events: the registration followed by the 99 newest verifications in chronological order. Older events are omitted from this response. The public JSON response is capped at 32 KiB.

Field	Type	Meaning
vpxBadgeId	string	The issued VPX identifier that was requested.
imageUrl	string (URL)	The registered image associated with the badge.
photoSha256	string	The lowercase or uppercase hexadecimal SHA-256 image fingerprint.
registeredAt	string (ISO 8601)	The UTC timestamp when the registration was recorded.
issuanceStatus	string	The stored public badge state: ISSUED, REVOKED, or CORRECTED.
status	string	The normalized public state: active, revoked, or corrected.
statusExplanation	string	A concise explanation of the normalized public state.
registrationEvent	object	The signed registration payload and public key used to verify it.
registrationEvent.eventType	string	Always INITIAL_REGISTRATION.
registrationEvent.vpxBadgeId	string	The badge ID covered by the registration signature.
registrationEvent.photoSha256	string	The 64-character hexadecimal SHA-256 fingerprint covered by the signature.
registrationEvent.registeredAt	string (ISO 8601)	The registration timestamp covered by the signature.
registrationEvent.signature	string (base64)	The Ed25519 signature over the registration fields, encoded as base64.
registrationEvent.algorithm	string	The signature algorithm; currently Ed25519.
registrationEvent.keyId	string	Identifier for the public key used to verify the event.
registrationEvent.publicKey	string (base64)	The DER SubjectPublicKeyInfo public key, encoded as base64.
registrationEvent.verificationStatus	string	Always valid when this event is returned.
verificationHistory	object	The badge ID and up to 100 chronological registration/verification events.
verificationHistory.vpxBadgeId	string	The badge ID associated with the history.
verificationHistory.events	array (up to 100)	The registration followed by the 99 newest public verification events.
verificationHistory.events[].eventType	string	INITIAL_REGISTRATION or PUBLIC_VERIFICATION.
verificationHistory.events[].timestamp	string (ISO 8601)	When the registration or public verification event was recorded.
verificationHistory.events[].signatureStatus	string	Always valid for events included in the verified public history.
squad	object \| null	Shared squad family and claimant display names only; private account details are omitted.
squad.familyId	string	The VPX family identifier shared by the original badge and linked copies.
squad.memberNames	array of strings	Display names of people who claimed a linked squad copy.
badgePresentation	object	Optional playful badge copy, kept separate from the signed registration record.
badgePresentation.badge	object or null	Style, title, one-line report, and rarity; these fields are not signed evidence.
badgePresentation.disclaimer	string	States that the badge title, report, and rarity are entertainment only.
disclaimer	string	The fixed limitation on what a registration record establishes.

200 / illustrative active response

{
  "vpxBadgeId": "VPX-2026-ABCD2345",
  "imageUrl": "https://assets.example.test/photo.jpg",
  "photoSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "registeredAt": "2026-09-13T00:00:00.000Z",
  "issuanceStatus": "ISSUED",
  "status": "active",
  "statusExplanation": "This badge is active and currently valid.",
  "registrationEvent": {
    "eventType": "INITIAL_REGISTRATION",
    "vpxBadgeId": "VPX-2026-ABCD2345",
    "photoSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "registeredAt": "2026-09-13T00:00:00.000Z",
    "signature": "c2lnbmF0dXJl",
    "algorithm": "Ed25519",
    "keyId": "illustrative-key-id",
    "publicKey": "cHVibGljLWtleQ==",
    "verificationStatus": "valid"
  },
  "verificationHistory": {
    "vpxBadgeId": "VPX-2026-ABCD2345",
    "events": [
      {
        "eventType": "INITIAL_REGISTRATION",
        "timestamp": "2026-09-13T00:00:00.000Z",
        "signatureStatus": "valid"
      },
      {
        "eventType": "PUBLIC_VERIFICATION",
        "timestamp": "2026-09-13T00:01:00.000Z",
        "signatureStatus": "valid"
      }
    ]
  },
  "squad": null,
  "badgePresentation": {
    "badge": {
      "style": "Futuristic",
      "title": "Future Verified",
      "report": "Main character energy: confirmed.",
      "rarity": "Epic"
    },
    "disclaimer": "Badge titles, reports, and rarity are entertainment only. They are not forensic or legal proof."
  },
  "disclaimer": "Registration records evidence; it does not prove ownership or authorship."
}

200 / illustrative revoked status excerpt

{
  "issuanceStatus": "REVOKED",
  "status": "revoked",
  "statusExplanation": "This badge is revoked and is no longer valid."
}

200 / illustrative corrected status excerpt

{
  "issuanceStatus": "CORRECTED",
  "status": "corrected",
  "statusExplanation": "This record was corrected; the displayed evidence is the current public evidence."
}

04 / responses

Validation and not-found responses

Malformed identifiers return HTTP 400. Well-formed unknown and not-yet-issued IDs return the same generic HTTP 404, so consumers cannot distinguish those two private states.

400 / malformed ID

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": "Invalid VPX Badge ID.",
  "code": "invalid_badge_id"
}

404 / unknown or unissued ID

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": "Badge not found."
}

05 / scope

Registration is evidence, not ownership

Registration records evidence; it does not prove ownership or authorship.

The API verifies what VeriPix recorded about an image and when it was registered. It does not independently establish who created, owns, or is authorized to use the image.