API reference · v1
Requests & responses
Base URLs, JSON payloads, pagination and request tracing.
Request format
All documented paths begin with /v1. Send Accept: application/json and Content-Type: application/json for JSON bodies.
Third-party batch lookup examples read BIRDOR_API_KEY on the server and send Authorization: Bearer. Main-site browser calls use the HttpOnly session, X-Birdor-Workspace-ID and same-origin POST; never embed an API key. Use HTTPS outside loopback development.
Obtain an authorized workspace from /v1/me/workspaces before a site catalog call. Current Web has account login/logout and public waitlist, but no authenticated catalog business page.
String lengths count Unicode code points after documented normalization, not UTF-16 units or visible graphemes; combining marks and ZWJ sequences count separately. ASCII bounds stay unchanged; emoji maximum boundaries expand and minimum boundaries tighten (workflow needs at least three code points). Waitlist email is limited to 320 characters after trim/lowercase; longer values return 400 INVALID_EMAIL before waitlist counting or writes. Body/query resource limits still apply.
Waitlist source, locale, workflow, utm_source, utm_medium and utm_campaign reject U+0000 (NUL): source returns 400 MISSING_SOURCE, the other five return 400 INVALID_PAYLOAD before waitlist business counting, Turnstile or writes. Coarse ingress may still count. Other characters and optional/nullable rules retain their behavior; formerly accepted MySQL/D1 NUL inputs now fail, without migrating stored data.
Response format
Successful responses contain ok, data, request_id and timestamp, with optional meta. Errors contain ok: false, code, message and request_id.
{
"ok": true,
"data": {
"service": "birdor-api",
"version": "v1",
"ok": true,
"timestamp": "2026-09-26T00:00:00.000Z",
"uptimeSeconds": 123.45,
"env": "development"
},
"request_id": "req_example",
"timestamp": "2026-09-26T00:00:00.000Z"
}Pagination
GET /v1/tools supports page (default 1, minimum 1) and limit (default 20, range 1–50). meta.count is the total number of matches, not the current page length. An empty page returns an empty data array. Other list endpoints have their own parameter rules.
Request tracing
Supply a non-empty X-Request-ID of at most 128 characters, or the server creates one. Header and body traces match at the origin; a shared HTTP cache can replay the original trace and timestamp. Authenticated responses are no-store.