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.

Quick Start

Generate your first UUID in under 30 seconds. No API key required for the free tier.

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

const res = await fetch('<?php echo https://uuid.codexneo.com; ?>/api/v1/handler.php?slug=uuid&v=4&n=1');
const data = await res.json();
console.log(data.data.ids[0]);

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

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

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

{
  "status": "success",
  "data": {
    "ids": ["550e8400-e29b-41d4-a716-446655440000"],
    "version": 4,
    "format": "uuid",
    "count": 1,
    "timestamp": 1714483200
  }
}

Authentication

The public API tier requires no authentication for up to 1,000 requests per hour. For higher volume, include your Private Service Token (PST) in the Authorization header.

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

Rate Limits

Rate limits are applied per IP address on the free tier and per token on authenticated tiers.

Rate limit headers are returned with every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Base Endpoint

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

Generate UUID

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

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

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

import requests

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

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

package main

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

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

{
  "status": "success",
  "data": {
    "ids": [
      "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"
    ],
    "version": 7,
    "format": "uuid",
    "count": 5,
    "timestamp": 1714483200
  }
}

Generate ULID

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

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

{
  "status": "success",
  "data": {
    "ids": [
      "01ARZ3NDEKTSV4RRFFQ69G5FAV",
      "01ARZ3NDEKTSV4RRFFQ69G5FAW",
      "01ARZ3NDEKTSV4RRFFQ69G5FAX"
    ],
    "format": "ulid",
    "count": 3,
    "timestamp": 1714483200
  }
}

Generate NanoID

Generate compact, URL-safe NanoIDs. Supports custom size (default 21) and alphabet presets.

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

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

Generate GUID

Generate Microsoft-style GUIDs. Structurally identical to UUID v4, optionally formatted with curly braces and uppercase.

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

{
  "status": "success",
  "data": {
    "ids": [
      "550E8400-E29B-41D4-A716-446655440000",
      "6BA7B810-9DAD-11D1-80B4-00C04FD430C8"
    ],
    "format": "guid",
    "count": 2,
    "timestamp": 1714483200
  }
}

Bulk Generation

Generate up to 1,000 identifiers in a single request using the n parameter. Free tier is capped at 100 per request.

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

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

Output Formats

Use the format parameter to control the response envelope.

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

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

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

<ids><id>550e8400-...</id></ids>

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.

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.

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.

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.

Error Handling

The API uses standard HTTP status codes. All error responses include a message field explaining the issue.

{
  "status": "error",
  "code": "invalid_slug",
  "message": "The 'slug' parameter is required. Valid values: uuid, guid, ulid, nanoid, password.",
  "docs": "https://uuid.codexneo.com/docs#endpoint"
}

Best Practices

Recommendations for integrating the UUID Codexneo API into production systems.

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(
    `<?php echo https://uuid.codexneo.com; ?>/api/v1/handler.php?slug=uuid&v=${version}&n=${count}`
  );
  const { data } = await res.json();
  return count === 1 ? data.ids[0] : data.ids;
}

// Usage
const id = await generateUUID(7);
console.log(id);

import requests

def generate_uuid(version=7, count=1):
    res = requests.get(
        '<?php echo https://uuid.codexneo.com; ?>/api/v1/handler.php',
        params={'slug': 'uuid', 'v': version, 'n': count}
    )
    ids = res.json()['data']['ids']
    return ids[0] if count == 1 else ids

# Usage
id = generate_uuid(version=7)
print(id)

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

// Usage
$id = generateUUID(7);
echo $id;

func GenerateUUID(version, count int) ([]string, error) {
    url := fmt.Sprintf(
        "<?php echo https://uuid.codexneo.com; ?>/api/v1/handler.php?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 struct { IDs []string `json:"ids"` } `json:"data"`
    }
    json.NewDecoder(resp.Body).Decode(&result)
    return result.Data.IDs, nil
}