Generate an ID

The single POST endpoint, the request body shape, request encodings, and the response and error formats shared by every ID type.

Generate an ID#

Everything the ID Generator does runs through one endpoint. The type field selects the flavour; the per-type options that go alongside it are documented on ID types.

Request#

The endpoint accepts a JSON body (Content-Type: application/json) or a form-urlencoded body (Content-Type: application/x-www-form-urlencoded). Bodies up to 32 MB are accepted, though a real request is tiny. Credentials must be in the body; query parameters are not read.

Each type takes its own additional fields, for example length for nanoid or style for words. See ID types for the full list per type.

Response#

A successful call returns 200 with JSON.

{ "id": "V1StGXR8_Z5jdHi6B-myT" }

The keypair type is the only one that returns a second field, privateID. See keypair.

{
  "id": "<public key, hex>",
  "privateID": "<secret key, hex>"
}

Errors#

Errors are returned as JSON in the shape { "error": "..." }.

An unknown type returns 400 with { "error": "ID Type <type> not supported." }.

Example#

curl -X POST https://id.hep.gg/ \
  -H "Content-Type: application/json" \
  -d '{
    "username": "my-bot",
    "token": "<your-token>",
    "type": "nanoid",
    "length": 12
  }'

const res = await fetch("https://id.hep.gg/", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    username: "my-bot",
    token: "<your-token>",
    type: "nanoid",
    length: 12,
  }),
});
const data = await res.json();
console.log(data.id);