API reference

UUID Foundry API documentation

A developer guide for generating UUIDs, inspecting values, and wiring up token-based integrations.

Get an API token

Base URL/api

Quick facts

History is saved automatically for generation endpoints.
Every API request reduces the API token balance.
UUID routes are rate-limited to help prevent abuse.

Authentication

Create a personal API token from your profile settings, then send it with every request in the Authorization header.

1. Create a token

Go to Profile Settings > API tokens and create a token for your integration.

2. Send the header

Authorization: Bearer YOUR_TOKEN

Request pattern

Every protected endpoint

All endpoints return JSON, token balance, and expect a valid API token.

Storage behavior

Generation endpoints save history automatically.

POST /api/uuids/generate

Generate a single UUID.

Parameters

type

stringRequired

UUID version to generate. Supported values: v1, v3, v4, v5, v6, v7, v8, nil, max.

Default: v7

namespace

string

Namespace UUID used for deterministic versions such as v3 and v5. Required for those versions.

Default: null

name

string

Name value used with deterministic UUID versions such as v3 and v5. Required for those versions.

Default: null

format

string

Format for the returned UUID. Supported values: canonical, uppercase, no-hyphens.

Default: canonical

Behavioral notes

History is always saved, and the source is automatically set to api .

Token usage: 1

Example request

curl -X POST "/api/uuids/generate" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "type": "v7",
        "format": "canonical"
    }'

Sample response

{
  "uuid": "018f4f2d-f92e-7fb0-a5e6-00f78c86375e",
  "formatted": "018f4f2d-f92e-7fb0-a5e6-00f78c86375e",
  "token_balance": 499
}

POST /api/uuids/batch

Generate multiple UUIDs in one call and choose how the response is formatted.

Parameters

type

stringRequired

UUID version to generate for each item in the batch.

Default: v7

quantity

integerRequired

Number of UUIDs to generate. Maximum allowed is 500.

Default: 1

namespace

string

Namespace UUID used for deterministic versions such as v3 and v5.

Default: null

name

string

Base name used for deterministic UUIDs in the batch.

Default: null

include_index_in_name

boolean

When true, appends an index to each generated name.

Default: false

format

string

Format for the returned UUIDs. Supported values: canonical, uppercase, no-hyphens.

Default: canonical

output_format

string

Response format for the batch output. Supported values: plain, json, csv, sql.

Default: plain

Behavioral notes

Token usage: 1 for each UUID generated.

Example request

curl -X POST "/api/uuids/batch" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "type": "v4",
        "quantity": 5,
        "format": "uppercase",
        "output_format": "json"
    }'

Sample response

{
  "uuids": [
    "018f4f2d-f92e-7fb0-a5e6-00f78c86375e",
    "018f4f2d-f92e-7fb0-a5e6-00f78c86375f"
  ],
  "output": [
    "018F4F2D-F92E-7FB0-A5E6-00F78C86375E",
    "018F4F2D-F92E-7FB0-A5E6-00F78C86375F"
  ],
  "token_balance": 498
}

POST /api/uuids/inspect

Inspect a UUID and return metadata about the version, structure, and validity.

Parameters

value

stringRequired

UUID value to inspect.

Behavioral notes

Token usage: 1

Example request

curl -X POST "/api/uuids/inspect" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "value": "018f4f2d-f92e-7fb0-a5e6-00f78c86375e"
    }'

Sample response

{
  "value": "018f4f2d-f92e-7fb0-a5e6-00f78c86375e",
  "version": 7,
  "valid": true,
  "variant": "rfc4122",
  "token_balance": 497
}

GET /api/user

Return the current authenticated user and token balance.

Notes

Use this route to confirm who is signed in and how many API tokens remain.

Behavioral notes

Token usage: 1

Example request

curl -X GET "/api/user" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"

Sample response

{
    "name": "Developer",
    "email": "[email protected]",
    "token_balance": 497
}

GET /api/history

List saved UUID history entries for the current user.

Notes

History is created automatically by generation endpoints. Manual POST creation is not part of the docs.

Behavioral notes

A maximum of 1000 history entries are returned per request.

Token usage: 1

Example request

curl -X GET "/api/history" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"

Sample response

{
    "data": [
        {
            "id": 5,
            "value": "019f479c-ef09-7177-9300-91b30dd361a8",
            "type": "v7",
            "created_at": "2026-07-09T16:01:34+00:00",
            "format": "canonical",
            "source": "api"
        }
    ],
    "token_balance": 497
}

HTTP status code summary

Common response codes you may see while using the API.

StatusMeaningDescription

200OKThe request succeeded and returned the expected response.

400Bad RequestThe request was invalid, often because a required parameter was missing or malformed.

401UnauthorizedNo valid API token was provided.

402Request FailedThe parameters were valid, but the request could not be completed.

403ForbiddenThe API token does not have permission to perform the request.

404Not FoundThe requested resource does not exist.

409ConflictThe request conflicts with another request, such as a duplicate or reused idempotent action.

424External Dependency FailedThe request could not be completed because an external dependency failed.

429Too Many RequestsThe API was hit too quickly. Retry with backoff and fewer requests.

500, 502, 503, 504Server ErrorsSomething went wrong on the server. These errors should be rare.