API reference

Inspect a UUID

Read a UUID’s version, variant and embedded timestamp, clock sequence and node.

GET POST /api/uuid/inspect MCP tool uuid_inspect

Parses a UUID written as 8-4-4-4-12 hex, 32 hex digits, {…} or urn:uuid:… (any case) and reports its RFC 9562 variant and version, whether it is the Nil or Max UUID, and the fields its version defines: the timestamp of v1, v6 and v7 as ISO 8601 (v1/v6 to 100 ns), and the clock sequence and node of v1 and v6. It also returns the UUID in every common format.

Browser version (runs locally): UUID Generator & Inspector.

Try it
Credentials
Remember these credentials

Not saved: you will paste them again next time.

No credentials yet? Get a client ID and secret. They are sent only to this site, in an Authorization: Basic header.

POST /api/uuid/inspect with a JSON body

Parameters

Parameter Type Default Description
input required string (≤ 64 chars) — One UUID in any accepted form, e.g. 017f22e2-79b0-7cc3-98c4-dc0c0c07398f.

Also accepted on every endpoint: format (json | text). Parameters may come from the query string, a JSON object body, an urlencoded or multipart form, or (for input) a text/plain body.

Global parameters
Parameter Type Default Description
format json | text json json returns the documented object. text returns only the primary value as text/plain (see "Text output").

Response 200 application/json

Field Type Description
input object
input.format "canonical" | "uppercase" | "no-hyphens" | "braces" | "urn" | "mixed-case" Form the input was written in.
input.normalized boolean True when the input differs from the canonical form.
canonical string Lowercase 8-4-4-4-12 form (RFC 9562 §4).
hex string 32 lowercase hex digits.
formats object
formats.canonical string 8-4-4-4-12 lowercase.
formats.uppercase string 8-4-4-4-12 uppercase.
formats.noHyphens string 32 hex digits.
formats.braces string {8-4-4-4-12} (Microsoft GUID style).
formats.urn string urn:uuid:8-4-4-4-12 (RFC 9562 §4).
special one of (by kind) nil (all zeros), max (all ones), or null.
special (kind = "undefined") variant
special (kind = "undefined") variant
variant "NCS" | "RFC 9562" | "Microsoft" | "Reserved (future)" Variant from the top bits of octet 8 (RFC 9562 §4.1).
variantBits string The variant bits: 0, 10, 110 or 111.
version integer | null Version (top 4 bits of octet 6), only for the RFC 9562 variant and not nil/max.
versionName string | null e.g. Unix Epoch time-based for 7.
timestamp object | null
timestamp.iso string ISO 8601 UTC, millisecond precision.
timestamp.isoExact string ISO 8601 UTC at the native precision (7 fractional digits for v1/v6).
timestamp.unixMs integer Milliseconds since 1970-01-01T00:00:00Z (floored for v1/v6).
timestamp.precision "100ns" | "1ms" Native precision.
timestamp.gregorian100ns string | null v1/v6: 100 ns intervals since 1582-10-15T00:00:00Z, as a decimal string.
clockSequence integer | null v1/v6: 14-bit clock sequence.
node string | null v1/v6: 48-bit node as colon-separated uppercase hex.
nodeIsRandom boolean | null v1/v6: the multicast bit is set, marking a random node rather than a MAC address.
notes array of string What the version encodes and any anomalies.

Errors

Errors are JSON: {"error": "<message>", "code": "<code>", "param": "<name>"?}.

Status Code When
422 unprocessable_input The input is not a UUID. The message gives the bad character or the digit count found.
400 missing_parameter A required parameter is absent.
400 unknown_parameter A parameter name is not in the table above (typos are rejected, not ignored).
400 invalid_parameter A value has the wrong type, is out of range, or is not an allowed value.
413 payload_too_large The request body exceeds 1 MiB.
405 method_not_allowed A method other than GET, POST or OPTIONS.

Behaviour

  • Idempotent: the same arguments always return the same result.
  • Requires a client ID and secret (authentication). Each call is recorded as one metadata row against your client ID; inputs and outputs are never stored or logged. Responses carry cache-control: no-store.
  • CORS: any origin may call this endpoint from a browser, using your credentials.

Examples

Responses below were produced by running each request through this code at build time. Long strings are shortened.

UUIDv7 (RFC 9562 test vector)

curl 'https://util.caruana.me/api/uuid/inspect?input=017F22E2-79B0-7CC3-98C4-DC0C0C07398F'

Response 200

{
  "input": {
    "format": "uppercase",
    "normalized": true
  },
  "canonical": "017f22e2-79b0-7cc3-98c4-dc0c0c07398f",
  "hex": "017f22e279b07cc398c4dc0c0c07398f",
  "formats": {
    "canonical": "017f22e2-79b0-7cc3-98c4-dc0c0c07398f",
    "uppercase": "017F22E2-79B0-7CC3-98C4-DC0C0C07398F",
    "noHyphens": "017f22e279b07cc398c4dc0c0c07398f",
    "braces": "{017f22e2-79b0-7cc3-98c4-dc0c0c07398f}",
    "urn": "urn:uuid:017f22e2-79b0-7cc3-98c4-dc0c0c07398f"
  },
  "special": null,
  "variant": "RFC 9562",
  "variantBits": "10",
  "version": 7,
  "versionName": "Unix Epoch time-based",
  "timestamp": {
    "iso": "2022-02-22T19:22:22.000Z",
    "isoExact": "2022-02-22T19:22:22.000Z",
    "unixMs": 1645557742000,
    "precision": "1ms",
    "gregorian100ns": null
  },
  "clockSequence": null,
  "node": null,
  "nodeIsRandom": null,
  "notes": []
}
Same call as an MCP tools/call
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "uuid_inspect",
    "arguments": {
      "input": "017F22E2-79B0-7CC3-98C4-DC0C0C07398F"
    }
  }
}

UUIDv1 (RFC 9562 test vector)

curl 'https://util.caruana.me/api/uuid/inspect?input=C232AB00-9414-11EC-B3C8-9F6BDECED846'

Response 200

{
  "input": {
    "format": "uppercase",
    "normalized": true
  },
  "canonical": "c232ab00-9414-11ec-b3c8-9f6bdeced846",
  "hex": "c232ab00941411ecb3c89f6bdeced846",
  "formats": {
    "canonical": "c232ab00-9414-11ec-b3c8-9f6bdeced846",
    "uppercase": "C232AB00-9414-11EC-B3C8-9F6BDECED846",
    "noHyphens": "c232ab00941411ecb3c89f6bdeced846",
    "braces": "{c232ab00-9414-11ec-b3c8-9f6bdeced846}",
    "urn": "urn:uuid:c232ab00-9414-11ec-b3c8-9f6bdeced846"
  },
  "special": null,
  "variant": "RFC 9562",
  "variantBits": "10",
  "version": 1,
  "versionName": "Gregorian time-based",
  "timestamp": {
    "iso": "2022-02-22T19:22:22.000Z",
    "isoExact": "2022-02-22T19:22:22.0000000Z",
    "unixMs": 1645557742000,
    "precision": "100ns",
    "gregorian100ns": "138648505420000000"
  },
  "clockSequence": 13256,
  "node": "9F:6B:DE:CE:D8:46",
  "nodeIsRandom": true,
  "notes": [
    "The node has the multicast bit set, which marks a random node ID (RFC 9562 §6.10), not a MAC address."
  ]
}
Same call as an MCP tools/call
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "uuid_inspect",
    "arguments": {
      "input": "C232AB00-9414-11EC-B3C8-9F6BDECED846"
    }
  }
}