API reference · v1
Identify and decode IDs
Identify up to 100 identifiers and decode what they embed: UUID version, variant and time (v1/v6 to 100 ns, v7 to 1 ms) plus v1/v6 clock sequence and node, ULID and KSUID time, MongoDB ObjectId time and counter, Snowflake time, worker and sequence (Twitter, Discord, Instagram, Sonyflake layouts) and CUID2 shape. Unrecognized entries return format null. confidence is low when the shape is ambiguous: CUID2 matches any short lowercase word, ObjectIds with an implausible time, and Snowflake ids that decode plausibly under several layouts (listed in alternatives). Requires a credential with tools.run; every accepted call consumes one monthly unit, including business 4xx/5xx.
/v1/run/id/inspectAccess requirements
Health, metadata, changelog and waitlist routes are public. Catalog reads (GET /v1/tools, /v1/tools/{id}, /v1/colors/*) and POST /v1/tools/query require a tools.read credential; POST /v1/run/* requires tools.run. There is no anonymous access to these routes: send an API key (Bearer OR X-API-Key) from your server, or use the HttpOnly main-site session plus workspace selection and same-origin Origin. Never combine credentials. Every admitted call is metered. Ingress and workspace/actor minute/month limits are separate; waitlist has its own policy.
Implemented interfaces and development screens do not imply public production availability, paid access or a completed payment integration. Confirm access with Birdor before connecting an application. No paid Pro service, activation or cross-device sync is currently delivered. We are validating one repeatable task before building a paid offer.
Parameters
| Field | Description |
|---|---|
AuthorizationstringOptional | Bearer API key with tools.run; alternatively X-API-Key. One of the credentials is required. |
X-API-KeystringOptional | Alternative to Authorization; never send both. |
X-Birdor-Workspace-IDstringOptional | Required with the site session; optional and matching with an API key. |
X-Birdor-Project-IDstringOptional | Optional owned project; a project-bound key cannot select another project. |
Request body
Send JSON with Content-Type: application/json.
| Field | Description |
|---|---|
idsarrayRequired | Identifiers to inspect, 1–100 entries of at most 64 characters: UUID (any version, with or without hyphens, braces or urn:uuid:), ULID, KSUID, MongoDB ObjectId, Snowflake or CUID2. |
snowflakePresetauto | twitter | discord | instagram | sonyflakeOptional | Snowflake layout: auto (ids of at least 15 digits; every preset whose time falls between 2010 and one year from now), twitter, discord, instagram or sonyflake (any integer); default auto. |
Request example
curl --request POST "$BIRDOR_API_BASE_URL/v1/run/id/inspect" \
--header "Accept: application/json" \
--header "Authorization: Bearer $BIRDOR_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"ids": [
"017F22E2-79B0-7CC3-98C4-DC0C0C07398F",
"01ARZ3NDEKTSV4RRFFQ69G5FAV",
"507f1f77bcf86cd799439011",
"175928847299117063",
"not-an-id"
],
"snowflakePreset": "discord"
}'Examples are copied only; this page does not send API requests.
Responses
Illustrative response. Values vary by environment and time.
200Success
{
"ok": true,
"data": {
"results": [
{
"input": "017F22E2-79B0-7CC3-98C4-DC0C0C07398F",
"format": "uuid",
"variant": "v7",
"confidence": "high",
"timeOrdered": true,
"timestamp": {
"unixMs": 1645557742000,
"iso": "2022-02-22T19:22:22.000Z",
"resolution": "1ms"
},
"fields": {
"canonical": "017f22e2-79b0-7cc3-98c4-dc0c0c07398f",
"version": 7,
"variant": "rfc9562"
},
"alternatives": []
},
{
"input": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
"format": "ulid",
"variant": null,
"confidence": "high",
"timeOrdered": true,
"timestamp": {
"unixMs": 1469922850259,
"iso": "2016-07-30T23:54:10.259Z",
"resolution": "1ms"
},
"fields": {
"canonical": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
"randomness": "TSV4RRFFQ69G5FAV"
},
"alternatives": []
},
{
"input": "507f1f77bcf86cd799439011",
"format": "objectid",
"variant": null,
"confidence": "high",
"timeOrdered": true,
"timestamp": {
"unixMs": 1350508407000,
"iso": "2012-10-17T21:13:27.000Z",
"resolution": "1s"
},
"fields": {
"random": "bcf86cd799",
"counter": 4427793
},
"alternatives": []
},
{
"input": "175928847299117063",
"format": "snowflake",
"variant": "discord",
"confidence": "high",
"timeOrdered": true,
"timestamp": {
"unixMs": 1462015105796,
"iso": "2016-04-30T11:18:25.796Z",
"resolution": "1ms"
},
"fields": {
"worker": 32,
"sequence": 7
},
"alternatives": []
},
{
"input": "not-an-id",
"format": null,
"variant": null,
"confidence": null,
"timeOrdered": null,
"timestamp": null,
"fields": {},
"alternatives": []
}
]
},
"request_id": "req_example",
"timestamp": "2026-10-11T00:00:00.000Z"
}400Invalid JSON, schema validation failure (field paths/codes only, never input values) or ambiguous credentials
{
"ok": false,
"code": "VALIDATION_ERROR",
"message": "Invalid request parameters",
"request_id": "req_example",
"timestamp": "2026-10-11T00:00:00.000Z"
}401Missing, expired, rotated, revoked or invalid credential; there is no anonymous access
{
"ok": false,
"code": "UNAUTHENTICATED",
"message": "API access denied",
"request_id": "req_example",
"timestamp": "2026-10-11T00:00:00.000Z"
}403Key lacks tools.run, or workspace/project/member policy or site Origin denied
{
"ok": false,
"code": "FORBIDDEN",
"message": "API access denied",
"request_id": "req_example",
"timestamp": "2026-10-11T00:00:00.000Z"
}405Only POST is supported; rejected before admission
{
"ok": false,
"code": "METHOD_NOT_ALLOWED",
"message": "Method not allowed",
"request_id": "req_example",
"timestamp": "2026-10-11T00:00:00.000Z"
}408Body read exceeds five seconds; before admission
{
"ok": false,
"code": "REQUEST_TIMEOUT",
"message": "Request body timeout or aborted",
"request_id": "req_example",
"timestamp": "2026-10-11T00:00:00.000Z"
}413Body exceeds 8192 bytes; before admission
{
"ok": false,
"code": "PAYLOAD_TOO_LARGE",
"message": "Request body too large",
"request_id": "req_example",
"timestamp": "2026-10-11T00:00:00.000Z"
}415Content-Type must be application/json; before admission
{
"ok": false,
"code": "UNSUPPORTED_MEDIA_TYPE",
"message": "JSON content type required",
"request_id": "req_example",
"timestamp": "2026-10-11T00:00:00.000Z"
}429Ingress, workspace/actor minute or monthly quota exceeded; inspect code and Retry-After
{
"ok": false,
"code": "QUOTA_EXCEEDED",
"message": "API request limit exceeded",
"request_id": "req_example",
"timestamp": "2026-10-11T00:00:00.000Z"
}500Unexpected operation failure; details are never echoed
{
"ok": false,
"code": "OPERATION_FAILED",
"message": "Operation failed",
"request_id": "req_example",
"timestamp": "2026-10-11T00:00:00.000Z"
}503Authentication/metering dependency unavailable
{
"ok": false,
"code": "API_GATEWAY_UNAVAILABLE",
"message": "API access denied",
"request_id": "req_example",
"timestamp": "2026-10-11T00:00:00.000Z"
}Example response fields
Fields shown in this example; optional fields can be omitted. Array rows describe the first example element.
- okboolean
- Application success flag.
- dataobject
- Endpoint-specific result.
- data.resultsarray
- Endpoint-specific example value.
- data.results[].inputstring
- Endpoint-specific example value.
- data.results[].formatstring
- Endpoint-specific example value.
- data.results[].variantstring
- Endpoint-specific example value.
- data.results[].confidencestring
- Endpoint-specific example value.
- data.results[].timeOrderedboolean
- Endpoint-specific example value.
- data.results[].timestampobject
- Response creation timestamp.
- data.results[].fieldsobject
- Endpoint-specific example value.
- data.results[].alternativesarray
- Endpoint-specific example value.
- request_idstring
- Origin-response identifier matching X-Request-ID; a shared HTTP cache may replay the original trace.
- timestampstring
- Response creation timestamp.