Getting Started

API Documentation

The UUID Codexneo API is a RESTful HTTP service for generating universally unique identifiers. It supports UUID v1, v4, v6, v7, ULID, NanoID, and GUID - all returned as JSON, plain text, CSV, or XML.

REST

Architecture

HTTPS

Transport

JSON

Default Format

100

Max Per Request

Base URL

https://uuid.codexneo.com/api/v1/handler

Quick Start

Generate your first UUID in under 30 seconds. No API key required.

Quick Start

curl "https://uuid.codexneo.com/api/v1/handler?slug=uuid&v=4&n=1"

const res = await fetch('https://uuid.codexneo.com/api/v1/handler?slug=uuid&v=4&n=1');
const data = await res.json();
console.log(data.data);

import requests
res = requests.get('https://uuid.codexneo.com/api/v1/handler', params={'slug':'uuid','v':4,'n':1})
print(res.json()['data'])

<?php
$res = file_get_contents('https://uuid.codexneo.com/api/v1/handler?slug=uuid&v=4&n=1');
$data = json_decode($res, true);
echo $data['data'];

resp, _ := http.Get("https://uuid.codexneo.com/api/v1/handler?slug=uuid&v=4&n=1")
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))

200 OK - Response

{
  "status": "success",
  "type": "uuid",
  "version": 4,
  "count": 1,
  "data": "550e8400-e29b-41d4-a716-446655440000"
}

Authentication

The public API requires no authentication today. Token-based authentication for higher-volume tiers is on the roadmap. When available, you will include a Private Service Token (PST) in the Authorization header as shown below.

Authenticated Request

curl -H "Authorization: Bearer YOUR_PST_TOKEN" \
     "https://uuid.codexneo.com/api/v1/handler?slug=uuid&v=7&n=10"

Enterprise / High Volume For dedicated throughput, SLA guarantees, or private clusters, contact us for a Private Service Token.

Rate Limits

The public API currently caps each request at 100 identifiers and requires no authentication. Higher-volume tiers with token authentication are on the roadmap.

Tier	Max n per Request	Auth Required
Public	100	No
Developer (planned)	500	PST Token
Enterprise (planned)	1,000	PST Token

Each response includes the X-RateLimit-Limit header indicating the current per-request cap.

API Reference

Base Endpoint

All API requests are made to a single endpoint. The slug parameter determines which generator is invoked.

GET /api/v1/handler

Query Parameters

slug Required

string · uuid, guid, ulid, nanoid, password

The identifier type to generate.

v Optional

integer · 1, 4, 6, 7

UUID version. Only applies when slug=uuid. Defaults to 4.

n Optional

integer · 1-100

Number of identifiers to generate. Defaults to 1. Max 100 (max 20 when slug=password).

format Optional

string · json, text, csv, xml

Response format. Defaults to json.

size Optional

integer · 1-128

NanoID length. Only applies when slug=nanoid. Defaults to 21.

len Optional

integer · 4-128

Password length. Only applies when slug=password. Defaults to 24.

upper, lower, numbers, symbols Optional

boolean · true, false

Password character classes. Only apply when slug=password. Each defaults to true.

Generate UUID

Generate RFC 4122 / RFC 9562 compliant UUIDs. Supports versions 1, 4, 6, and 7.

GET ?slug=uuid&v=7&n=5

# UUID v7 (recommended for databases)
curl "https://uuid.codexneo.com/api/v1/handler?slug=uuid&v=7&n=5"

// UUID v7 - time-ordered, best for DB primary keys
const res = await fetch('https://uuid.codexneo.com/api/v1/handler?slug=uuid&v=7&n=5');
const { data } = await res.json();
console.log(data); // ['018e3a5f-...', ...]

import requests

# UUID v4 - cryptographically random
res = requests.get('https://uuid.codexneo.com/api/v1/handler', params={'slug': 'uuid', 'v': 4, 'n': 5})
ids = res.json()['data']
print(ids)

<?php
// UUID v4 batch
$url = 'https://uuid.codexneo.com/api/v1/handler?slug=uuid&v=4&n=5';
$data = json_decode(file_get_contents($url), true);
foreach ($data['data'] as $id) {
    echo $id . PHP_EOL;
}

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    resp, _ := http.Get("https://uuid.codexneo.com/api/v1/handler?slug=uuid&v=7&n=5")
    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    fmt.Println(result["data"])
}

200 OK

{
  "status": "success",
  "type": "uuid",
  "version": 7,
  "count": 5,
  "data": [
    "018e3a5f-2b4c-7d8e-9f0a-1b2c3d4e5f60",
    "018e3a5f-2b4d-7d8e-9f0a-1b2c3d4e5f61",
    "018e3a5f-2b4e-7d8e-9f0a-1b2c3d4e5f62",
    "018e3a5f-2b4f-7d8e-9f0a-1b2c3d4e5f63",
    "018e3a5f-2b50-7d8e-9f0a-1b2c3d4e5f64"
  ]
}

Generate ULID

Generate Universally Unique Lexicographically Sortable Identifiers. 26-character Crockford Base32 encoded, time-ordered.

GET ?slug=ulid&n=3

curl "https://uuid.codexneo.com/api/v1/handler?slug=ulid&n=3"

200 OK

{
  "status": "success",
  "type": "ulid",
  "count": 3,
  "data": [
    "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "01ARZ3NDEKTSV4RRFFQ69G5FAW",
    "01ARZ3NDEKTSV4RRFFQ69G5FAX"
  ]
}

Generate NanoID

Generate compact, URL-safe NanoIDs using the default 64-character alphabet. Use the size parameter to set the length (default 21).

GET ?slug=nanoid&n=3&size=16

curl "https://uuid.codexneo.com/api/v1/handler?slug=nanoid&n=3&size=16"

200 OK

{
  "status": "success",
  "type": "nanoid",
  "size": 16,
  "count": 3,
  "data": ["V1StGXR8_Z5jdHi6", "IRFa-VaY2b_9kM3n", "Xt7pQwRs_4nLmKj2"]
}

Generate GUID

Generate Microsoft-style GUIDs. Structurally identical to UUID v4, returned uppercase and wrapped in curly braces.

GET ?slug=guid&n=2

curl "https://uuid.codexneo.com/api/v1/handler?slug=guid&n=2"

200 OK

{
  "status": "success",
  "type": "guid",
  "count": 2,
  "data": [
    "{550E8400-E29B-41D4-A716-446655440000}",
    "{F47AC10B-58CC-4372-A567-0E02B2C3D479}"
  ]
}

Bulk Generation

Generate up to 100 identifiers in a single request using the n parameter. Values above 100 are clamped to 100.

GET ?slug=uuid&v=7&n=100&format=text

# Generate 100 UUID v7s as plain text (one per line)
curl "https://uuid.codexneo.com/api/v1/handler?slug=uuid&v=7&n=100&format=text"

# Pipe directly into a file
curl -s "https://uuid.codexneo.com/api/v1/handler?slug=uuid&v=7&n=100&format=text" > uuids.txt

Output Formats

Use the format parameter to control the response envelope.

format=json application/json

Default. Structured JSON with status, data, and metadata.

{"status":"success","data":[...]}

format=text text/plain

Raw identifiers, one per line. Ideal for piping to files.

550e8400-e29b-41d4-a716-446655440000
018e3a5f-2b4c-7d8e-9f0a-1b2c3d4e5f60

format=csv text/csv

CSV with header row. Ready for spreadsheet import.

id
550e8400-e29b-41d4-a716-446655440000

format=xml application/xml

XML envelope with a response wrapper and one item node per identifier.

<response><status>success</status><data><item>550e8400-...</item></data></response>

UUID Versions

UUID v4 - Random

The most widely used UUID version. 122 bits of cryptographic randomness. RFC 4122 compliant. Use for user IDs, session tokens, API keys, and general-purpose identifiers.

RFC 4122

Standard

128

Bits

122 bits

Random

Sortable

GET ?slug=uuid&v=4

550e8400-e29b-41d4-a716-446655440000

The 4 in position 13 identifies the version.

UUID v7 - Sortable

Unix millisecond timestamp prefix + 74 random bits. RFC 9562 standard. Lexicographically sortable. The recommended choice for database primary keys - eliminates B-tree index fragmentation.

RFC 9562

Standard

48-bit ms

Timestamp

74 bits

Random

Yes

Sortable

GET ?slug=uuid&v=7

018e3a5f-2b4c-7d8e-9f0a-1b2c3d4e5f60

First 12 hex chars = Unix timestamp in ms. 7 = version.

UUID v6 - Reordered Time

Reordered timestamp UUID. RFC 9562. Lexicographically sortable, fully backward-compatible with UUID v1. Best for migrating from v1 systems that need sortability.

GET ?slug=uuid&v=6

1ec9414c-232a-6b00-b3c8-9f6bdeced846

UUID v1 - Timestamp

Gregorian timestamp (100ns resolution) + node ID. RFC 4122. Partially sortable. Use for Cassandra timeuuid or legacy system compatibility. Our generator uses a random node ID for privacy.

GET ?slug=uuid&v=1

6ba7b810-9dad-11d1-80b4-9f3c2a7e5d18

Guides

Error Handling

The API uses standard HTTP status codes. All error responses include an error field explaining the issue, and a valid_slugs array when the slug is missing or unrecognized.

Status	Condition	Meaning
200	Success	Request succeeded.
400	Missing slug	The required slug parameter was not provided.
400	Invalid version	The v parameter is not a supported UUID version (1, 4, 6, 7).
404	Unknown slug	The slug value is not one of uuid, guid, ulid, nanoid, password.

400 Bad Request - Error Response

{
  "error": "Missing required parameter: slug",
  "valid_slugs": ["uuid", "guid", "ulid", "nanoid", "password"]
}

Best Practices

Recommendations for integrating the UUID Codexneo API into production systems.

Generate locally for high throughput

For services generating more than 10,000 IDs per second, use our Dev Lab snippets to generate identifiers locally. The API is ideal for low-to-medium volume and client-side use cases.

View Dev Lab →

Use UUID v7 for database primary keys

UUID v7's time-ordered prefix eliminates B-tree index fragmentation. At 100M+ rows, this translates to 2-5x better INSERT throughput compared to UUID v4.

UUID v7 Generator →

Store as binary, not VARCHAR

Use native UUID types (PostgreSQL UUID, MySQL BINARY(16), SQL Server UNIQUEIDENTIFIER) instead of VARCHAR(36). Binary storage is 56% smaller and indexes faster.

Compare Formats →

Cache bulk responses

If you need a pool of IDs, generate them in bulk (n=100) and cache them client-side. This reduces API calls and latency for high-frequency operations.

Implement exponential backoff

On transient 5xx responses, retry with exponential backoff: wait 1s, then 2s, then 4s. This keeps your integration resilient to temporary network or server hiccups.

SDKs & Libraries

Official SDKs are in development. In the meantime, the API is simple enough to integrate with any HTTP client. Below are minimal wrapper examples for the most common languages.

async function generateUUID(version = 7, count = 1) {
  const res = await fetch(
    `https://uuid.codexneo.com/api/v1/handler?slug=uuid&v=${version}&n=${count}`
  );
  const { data } = await res.json();
  return data;
}

// Usage
const ids = await generateUUID(7, 5);
console.log(ids);

import requests

def generate_uuid(version=7, count=1):
    res = requests.get(
        'https://uuid.codexneo.com/api/v1/handler',
        params={'slug': 'uuid', 'v': version, 'n': count}
    )
    return res.json()['data']

# Usage
ids = generate_uuid(version=7, count=5)
print(ids)

<?php
function generateUUID(int $version = 7, int $count = 1): string|array {
    $url = 'https://uuid.codexneo.com/api/v1/handler?'
         . http_build_query(['slug'=>'uuid','v'=>$version,'n'=>$count]);
    $data = json_decode(file_get_contents($url), true);
    return $data['data'];
}

// Usage
$ids = generateUUID(7, 5);
print_r($ids);

func GenerateUUID(version, count int) (interface{}, error) {
    url := fmt.Sprintf(
        "https://uuid.codexneo.com/api/v1/handler?slug=uuid&v=%d&n=%d",
        version, count,
    )
    resp, err := http.Get(url)
    if err != nil { return nil, err }
    defer resp.Body.Close()
    var result struct {
        Data interface{} `json:"data"`
    }
    json.NewDecoder(resp.Body).Decode(&result)
    return result.Data, nil
}

Need a local implementation?

Dev Lab has copy-ready UUID generation code for 25+ languages - no API calls needed.

Open Dev Lab