API reference · v1
Join the waitlist
Creates or confirms a subscription. Requires a configured database and, unless disabled by the operator, a valid Turnstile token. Rate limits depend on the deployment. This is a write operation. For compatibility the handler parses JSON even when Content-Type is absent or different; new clients should send application/json. This differs from strict tools/query415 behavior.
/v1/waitlist/subscribeAccess 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
No path or query parameters.
Request body
Send JSON with Content-Type: application/json.
| Field | Description |
|---|---|
emailstringRequired | Valid email; at most 320 characters after trimming and lowercasing. Longer values return 400 INVALID_EMAIL before waitlist counter/save. |
sourcestringRequired | Trimmed string, 1–100 characters. U+0000 (NUL) is not allowed. |
localestringOptional | At most 16 characters. U+0000 (NUL) is not allowed. |
workflowstring | nullOptional | Trimmed string, 3–240 characters. U+0000 (NUL) is not allowed. |
candidatestring | nullOptional | hash, base64, jwt_debugger or other. |
traffic_bandstring | nullOptional | under_1k_day, 1k_to_10k_day, 10k_to_100k_day or 100k_plus_day. |
utm_sourcestring | nullOptional | At most 100 characters. U+0000 (NUL) is not allowed. |
utm_mediumstring | nullOptional | At most 100 characters. U+0000 (NUL) is not allowed. |
utm_campaignstring | nullOptional | At most 120 characters. U+0000 (NUL) is not allowed. |
turnstile_tokenstring | nullOptional | At most 2048 characters. Required by the service when Turnstile verification is enabled. |
Request example
This request creates or confirms a subscription. Replace the example email and token before running it intentionally.
curl --request POST "$BIRDOR_API_BASE_URL/v1/waitlist/subscribe" \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data '{
"email": "developer@example.com",
"source": "api-docs",
"locale": "en",
"turnstile_token": "REPLACE_WITH_VALID_TOKEN"
}'Examples are copied only; this page does not send API requests.
Responses
Illustrative response. Values vary by environment and time.
201Subscription created
{
"ok": true,
"data": {
"status": "subscribed"
},
"request_id": "req_example",
"timestamp": "2026-09-26T00:00:00.000Z"
}200Already subscribed
{
"ok": true,
"data": {
"status": "already_subscribed"
},
"request_id": "req_example",
"timestamp": "2026-09-26T00:00:00.000Z"
}400INVALID_PAYLOAD, INVALID_EMAIL, MISSING_SOURCE, TURNSTILE_REQUIRED or TURNSTILE_FAILED; NUL in source returns MISSING_SOURCE and in the other five persisted text fields returns INVALID_PAYLOAD before waitlist business counting, Turnstile or writes (coarse ingress may still count). Stream read failure returns INVALID_REQUEST_BODY before parsing
{
"ok": false,
"code": "INVALID_EMAIL",
"message": "Invalid waitlist request",
"request_id": "req_example",
"timestamp": "2026-09-26T00:00:00.000Z"
}429RATE_LIMITED
{
"ok": false,
"code": "RATE_LIMITED",
"message": "RATE_LIMITED",
"request_id": "req_example",
"timestamp": "2026-09-26T00:00:00.000Z"
}500WAITLIST_DB_NOT_CONFIGURED
{
"ok": false,
"code": "WAITLIST_DB_NOT_CONFIGURED",
"message": "WAITLIST_DB_NOT_CONFIGURED",
"request_id": "req_example",
"timestamp": "2026-09-26T00:00:00.000Z"
}503WAITLIST_UNAVAILABLE: storage/capacity/deadline failure; completion may be partial or late. Retry uses email deduplication and qualification upsert, with new rate limits; no whole-request transaction or replay guarantee. INGRESS_UNAVAILABLE can also reject before the flow.
{
"ok": false,
"code": "WAITLIST_UNAVAILABLE",
"message": "WAITLIST_UNAVAILABLE",
"request_id": "req_example",
"timestamp": "2026-09-26T00:00:00.000Z"
}414Query string exceeds4096 characters before admission
{
"ok": false,
"code": "QUERY_TOO_LONG",
"message": "Query string too long",
"request_id": "req_example",
"timestamp": "2026-09-26T00:00:00.000Z"
}413Body exceeds32768 bytes before parsing
{
"ok": false,
"code": "PAYLOAD_TOO_LARGE",
"message": "Request body too large",
"request_id": "req_example",
"timestamp": "2026-09-26T00:00:00.000Z"
}408Body read exceeds five seconds or caller aborts; before admission, no quota headers
{
"ok": false,
"code": "REQUEST_TIMEOUT",
"message": "Request body timeout or aborted",
"request_id": "req_example",
"timestamp": "2026-09-26T00: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.statusstring
- Operation result.
- request_idstring
- Origin-response identifier matching X-Request-ID; a shared HTTP cache may replay the original trace.
- timestampstring
- Response creation timestamp.