---
title: "Use this when you need a modern unique identifier (UUID v7, UUID v5, ULID, or nanoid) or want to read the timestamp embedded in an existing ULID or UUIDv7."
method: POST
path: "/v1/generate_id"
tags: ["random"]
---

# Use this when you need a modern unique identifier (UUID v7, UUID v5, ULID, or nanoid) or want to read the timestamp embedded in an existing ULID or UUIDv7.

`POST /v1/generate_id`

## Request

- Base URL: `https://api.clean.tools`
- URL: `https://api.clean.tools/v1/generate_id`
- Auth: none declared

Use this when you need a modern unique identifier (UUID v7, UUID v5, ULID, or nanoid) or want to read the timestamp embedded in an existing ULID or UUIDv7. uuid_v5 (SHA-1 of a namespace UUID + a name, RFC 4122) and decode are deterministic (same input, same output) — e.g. generate_id(type "uuid_v5", namespace "6ba7b810-9dad-11d1-80b4-00c04fd430c8", name "www.example.com") -> {ids:["2ed6657d-e927-568b-95e1-2665a8aea6a2"]}. uuid_v7, ulid, and nanoid are cryptographically random via Web Crypto (NOT deterministic). Prefer this over assembling ids by hand: it sets the correct RFC version/variant bits, uses Crockford base32 for ULIDs, and draws nanoid characters with unbiased rejection sampling. When decode is present, type is ignored and the result is the embedded {unix_ms, timestamp_iso}.

## Request body

- object
  - `type` 'uuid_v7' | 'uuid_v5' | 'ulid' | 'nanoid': Which id to generate. Required unless decode is given.
  - `count` integer: How many ids to generate (default 1). For uuid_v5 all copies are identical (deterministic).
  - `namespace` string: uuid_v5 only: the namespace UUID, e.g. 6ba7b810-9dad-11d1-80b4-00c04fd430c8 (DNS).
  - `name` string: uuid_v5 only: the name hashed within the namespace.
  - `alphabet` string: nanoid only: characters to draw from (2-256 chars; default is the 64-char URL-safe set).
  - `size` integer: nanoid only: id length (default 21).
  - `decode` string: A ULID or UUIDv7 to decode; returns its embedded timestamp. type is ignored when set.

## Response `200`

Structured tool result.

- object
  - `tool` string
  - `result` object: Generate mode returns `ids`; decode mode returns `decoded`. Exactly one of the two is present.
    - `ids` string[]: [generate mode] The generated identifiers, length = count. For uuid_v5 every copy is identical (deterministic).
    - `decoded` object: [decode mode] The timestamp embedded in the supplied ULID or UUIDv7.
      - `kind` 'ulid' | 'uuid_v7', required: Which id family was decoded.
      - `unix_ms` integer, required: Embedded timestamp as Unix epoch milliseconds.
      - `timestamp_iso` string, required: Embedded timestamp as an ISO-8601 UTC string.

## Other responses

- `400`: Invalid input or the tool reported an error.
- `413`: Request body exceeds the 128 KB limit.
- `429`: Rate limit exceeded; the response carries Retry-After and RateLimit-* headers — honor them and add jitter.

---

[API](https://skmtc.dev/clean/apis/clean-tools-api.md) · [All operations](https://skmtc.dev/clean/apis/clean-tools-api/llms.txt) · [OpenAPI document](https://skmtc.dev/clean/apis/clean-tools-api/revisions/a24a01d2833c?raw)