Cuid Generator API

About the Cuid Generator API

Cuid Generator creates CUIDs, collision-resistant unique identifiers designed for distributed applications where several servers create IDs at the same time. Ask for one ID or a batch of up to 100 and get them back as an array of strings, each starting with the letter c and safe to use in URLs, file names and database keys.

A CUID starts with a timestamp for sorting, so IDs generated later generally sort after earlier ones, which keeps database indexes and logs in rough creation order. Teams use them as primary keys, client-side record IDs before a sync, and request or job identifiers, and as a shorter alternative to a UUID when they want a sortable id.

The Free plan returns the IDs and the count. Paid plans add a description of the CUID component layout and flags stating that the IDs are collision resistant and sortable, which helps when the response is logged or shown to someone checking which unique identifier format a system uses.

How it works

Each ID follows the original CUID layout, built from five parts concatenated in order: the letter c; the current time in milliseconds written in base 36; a four-character base-36 counter; a four-character fingerprint; and two four-character random blocks.

The counter increments for every ID the serving instance creates and wraps back to zero after 36^4 values, so IDs made in the same millisecond on the same instance still differ. The fingerprint is derived from the server process ID and the length of its hostname, which separates IDs made by different instances at the same moment. The random blocks come from the JavaScript runtime's standard random number generator, which is not a cryptographic source: treat CUIDs as unique identifiers, not as secrets or unguessable tokens. Use a password or token generator for those.

Because the timestamp comes first and is the same length for any current date, IDs sort roughly by creation time. Ordering within the same millisecond is reliable only for IDs from the same instance, since separate instances keep separate counters.

count sets how many IDs are returned, from 1 to 100, defaulting to 1, and cuids holds them in generation order. format, collision_resistant and sortable are fixed descriptive values that are the same on every response; they are null on the Free plan.

What people use it for

Distributed Databases

Generate safe unique keys across distributed database systems and shards

Horizontal Scaling

Create identifiers that work reliably across horizontally scaled applications

Event Sourcing

Generate sortable event identifiers for event sourcing and CQRS patterns

Multi-tenant Systems

Create unique identifiers across multiple tenants and isolated environments

Ways to call it

One endpoint, many ways in — REST with JSON, XML, YAML and CSV, plus GraphQL and an MCP interface for AI agents.

JSON

Default REST response

XML

Markup format

YAML

Human-readable

CSV

Tabular export

Beta

GraphQL

Query language

New

MCP

For AI agents

Request parameters — GET /v1/cuidgenerator

Sent in the query string. Premium parameters are accepted on every plan but only take effect on plans that include them. Anything not listed here is dropped rather than passed through.

Optional

1
2

curl "https://api.apiverve.com/v1/cuidgenerator?count=10" \
  -H "x-api-key: YOUR_API_KEY"

Authentication

Send your key in the x-api-key header. That is the only auth step — no token exchange, and no per-endpoint scope to configure.

Response — GET /v1/cuidgenerator

Every APIVerve endpoint returns the same three top-level keys, so one response handler covers your whole integration: status, error and data. Only data changes shape.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

{
  "status": "ok",
  "error": null,
  "data": {
    "cuids": [
      "cmj95ed27000000145v116use",
      "cmj95ed2700010014uuounuyc",
      "cmj95ed27000200147pwbz35y",
      "cmj95ed27000300142h9ivqrz",
      "cmj95ed27000400149ingh73n",
      "cmj95ed2700050014mg9alsah",
      "cmj95ed27000600149utx0fy3",
      "cmj95ed270007001467kspfhp",
      "cmj95ed2700080014n7ykgwxf",
      "cmj95ed2700090014rrnfehcn"
    ],
    "count": 10,
    "format": "c + timestamp + counter + fingerprint + random",
    "collision_resistant": true,
    "sortable": true
  }
}

Response fields

Paths are relative to data. Premium fields are absent rather than zeroed on plans that do not include them, so check for presence instead of comparing to 0.

Response headers

Every response carries your balance, so your own code always knows where it stands without polling anything. All four are exposed to browsers through CORS.

Errors

Read the HTTP status first, then error for the specific reason. The body names the parameter that has to change.

What a call costs — 1 credits per call

Credits are shared across every APIVerve API — one balance, one key, one bill. Failed requests never count against it, so a rejected input costs nothing.

Calls are what the credits buy at this API's rate — spend them here, on any of the other APIs, or across both. Nothing is reserved per endpoint.

Zero-code embed — one snippet, no backend

Drop an interactive Cuid Generator form onto any page. The widget calls the API for you, so no key ever appears in your markup and there is nothing to deploy.

Changelog — Cuid Generator API

Every change to this endpoint, newest first. Breaking changes ship as a new version and the previous one keeps serving — response fields are added, never removed or retyped in place, so an integration written against v1 keeps working.

Currently v1