# Hashids API
> Turn sequential integer IDs into short, unique, non-sequential strings — and back again. Encode one or more non-negative integers (or a hex string such as a Mongo ObjectId) into a compact YouTube-style id like "vbYCZIYD", then decode it to recover the exact original values. Add a salt so your ids are unique to your application, set a minimum length, or supply a custom alphabet. It is reversible obfuscation (not encryption): perfect for hiding row ids in public URLs, building short links, and avoiding leaking how many records you have. Pure local computation — no key, no third-party service, nothing stored. Stateless: decode with the same salt/min-length/alphabet you encoded with. Live. 5 endpoints. Distinct from UUID generation, base conversion and snowflake decoding.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/hashids-api/..."
```

## Pricing
- **Free** (Free) — 1,540 calls/Mo, 2 req/s
- **Starter** ($7/Mo) — 30,000 calls/Mo, 8 req/s
- **Pro** ($27/Mo) — 186,000 calls/Mo, 20 req/s
- **Mega** ($63/Mo) — 950,000 calls/Mo, 50 req/s

## Endpoints

### Encode

#### `GET /v1/encode` — Encode integers to a hashid

**Parameters:**
- `numbers` (query, required, string) — Non-negative integers, comma-separated Example: `1,2,3`
- `salt` (query, optional, string) — Obfuscation salt (keep it constant per app) Example: `my-salt`
- `min_length` (query, optional, string) — Minimum hash length

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/hashids-api/v1/encode?numbers=1%2C2%2C3&salt=my-salt"
```

**Response:**
```json
{
    "data": {
        "hash": "7LC9u4",
        "salt": "my-salt",
        "numbers": [
            1,
            2,
            3
        ],
        "min_length": 0
    },
    "meta": {
        "timestamp": "2026-06-02T16:52:00.047Z",
        "request_id": "26e11334-d9ea-4078-8186-91d7c5cdddc0"
    },
    "status": "ok",
    "message": "Encode integers to a hashid",
    "success": true
}
```

#### `GET /v1/encode-hex` — Encode hex to a hashid

**Parameters:**
- `hex` (query, required, string) — Hex string (e.g. ObjectId) Example: `507f1f77bcf86cd799439011`
- `salt` (query, optional, string) — Obfuscation salt (keep it constant per app) Example: `my-salt`
- `min_length` (query, optional, string) — Minimum hash length

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/hashids-api/v1/encode-hex?hex=507f1f77bcf86cd799439011&salt=my-salt"
```

**Response:**
```json
{
    "data": {
        "hex": "507f1f77bcf86cd799439011",
        "hash": "gX9LYXekA7hygdy5dp36",
        "salt": "my-salt",
        "min_length": 0
    },
    "meta": {
        "timestamp": "2026-06-02T16:52:00.156Z",
        "request_id": "20fbe3ef-4a9a-4400-9dbf-48d9fc778ea3"
    },
    "status": "ok",
    "message": "Encode hex to a hashid",
    "success": true
}
```

### Decode

#### `GET /v1/decode` — Decode a hashid

**Parameters:**
- `hash` (query, required, string) — Hashid to decode Example: `vbYCZIYD`
- `salt` (query, optional, string) — Obfuscation salt (keep it constant per app) Example: `my-salt`
- `min_length` (query, optional, string) — Minimum hash length

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/hashids-api/v1/decode?hash=vbYCZIYD&salt=my-salt"
```

**Response:**
```json
{
    "data": {
        "hash": "vbYCZIYD",
        "salt": "my-salt",
        "valid": false,
        "numbers": [],
        "min_length": 0
    },
    "meta": {
        "timestamp": "2026-06-02T16:52:00.259Z",
        "request_id": "07f9bd5f-478d-408e-91e8-b89dc3ef79ac"
    },
    "status": "ok",
    "message": "Decode a hashid",
    "success": true
}
```

#### `GET /v1/decode-hex` — Decode a hashid to hex

**Parameters:**
- `hash` (query, required, string) — Hashid to decode to hex Example: `q7XKW7gyJRIdm1dK1r6g`
- `salt` (query, optional, string) — Obfuscation salt (keep it constant per app) Example: `my-salt`
- `min_length` (query, optional, string) — Minimum hash length

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/hashids-api/v1/decode-hex?hash=q7XKW7gyJRIdm1dK1r6g&salt=my-salt"
```

**Response:**
```json
{
    "data": {
        "hex": null,
        "hash": "q7XKW7gyJRIdm1dK1r6g",
        "salt": "my-salt",
        "valid": false,
        "min_length": 0
    },
    "meta": {
        "timestamp": "2026-06-02T16:52:00.370Z",
        "request_id": "9063c6f8-f254-4935-9774-c1beeb0cb3f8"
    },
    "status": "ok",
    "message": "Decode a hashid to hex",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Spec

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/hashids-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "auth": "none upstream; this gateway requires x-api-key",
        "name": "Hashids API",
        "note": "Encode non-negative integers into short reversible YouTube-style ids and decode them back. /v1/encode?numbers=1,2,3 ; /v1/decode?hash=... ; /v1/encode-hex?hex=507f... and /v1/decode-hex for hex/ObjectId values. Optional ?salt= (obfuscation key), ?min_length= and a custom ?alphabet= (>=16 unique chars). Stateless: decode with the SAME options used to encode. Not encryption — for obfuscating sequential ids in URLs.",
        "source": "Local hashids encoding — no key, no upstream",
        "endpoints": 5
    },
    "meta": {
        "timestamp": "2026-06-02T16:52:00.474Z",
        "request_id": "6d782130-b898-47f8-9f84-828e4798b2aa"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/hashids-api
OpenAPI spec: https://www.oanor.com/api/hashids-api/openapi.json