API reference

Generate UUIDs

Generate random (v4) or time-ordered (v7) UUIDs, up to 1000 at a time.

GET POST /api/uuid/generate MCP tool uuid_generate

Generates RFC 9562 UUIDs. Version 4: 122 random bits from crypto.randomUUID(). Version 7: a 48-bit Unix millisecond timestamp, then a 42-bit counter (randomly seeded each millisecond, incremented within it) and 32 fresh random bits, so every batch is strictly increasing in both byte and string order. UUIDs are identifiers, not secrets: do not use them as passwords, API keys, session tokens or capability URLs, even though v4 uses a CSPRNG.

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/generate with a JSON body

Parameters

Parameter Type Default Description
version 4 | 7 4 4 (random) or 7 (time-ordered; sorts by creation time, good for database keys).
count integer (1–1000) 1 How many UUIDs to return, 1 to 1000.
format canonical | uppercase | no-hyphens | braces | urn canonical canonical (lowercase 8-4-4-4-12), uppercase, no-hyphens (32 hex), braces ({…}), or urn (urn:uuid:…).

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
version integer UUID version generated.
format "canonical" | "uppercase" | "no-hyphens" | "braces" | "urn" Output format.
count integer Number of UUIDs.
uuids array of string The UUIDs, in generation order (for v7, also ascending order).

Text output (format=text, text/plain): One UUID per line.

Errors

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

Status Code When
400 invalid_parameter version is not 4 or 7, count is outside 1–1000, or format is unknown.
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).
413 payload_too_large The request body exceeds 1 MiB.
405 method_not_allowed A method other than GET, POST or OPTIONS.

Behaviour

  • Not idempotent: the result can differ between calls (time, randomness, or a live network check).
  • 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.

One random UUID

curl 'https://util.caruana.me/api/uuid/generate?version=4'

Response 200

{
  "version": 4,
  "format": "canonical",
  "count": 1,
  "uuids": [
    "761e9672-3ec7-453e-9f32-15eea29cde5f"
  ]
}
Same call as an MCP tools/call
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "uuid_generate",
    "arguments": {
      "version": "4"
    }
  }
}

Five time-ordered UUIDs

curl 'https://util.caruana.me/api/uuid/generate?version=7&count=5'

Response 200

{
  "version": 7,
  "format": "canonical",
  "count": 5,
  "uuids": [
    "01a13cf5-15ae-74e5-aee5-1283487f3dde",
    "01a13cf5-15ae-74e5-aee5-12843ef42045",
    "01a13cf5-15ae-74e5-aee5-12853c2cf0db",
    "01a13cf5-15ae-74e5-aee5-12863c3d7888",
    "01a13cf5-15ae-74e5-aee5-12879e7a1dbe"
  ]
}
Same call as an MCP tools/call
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "uuid_generate",
    "arguments": {
      "version": "7",
      "count": 5
    }
  }
}