Skip to API content
Birdor API v1

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.

POST/v1/waitlist/subscribe

Access 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.

FieldDescription
emailstringRequiredValid email; at most 320 characters after trimming and lowercasing. Longer values return 400 INVALID_EMAIL before waitlist counter/save.
sourcestringRequiredTrimmed string, 1–100 characters. U+0000 (NUL) is not allowed.
localestringOptionalAt most 16 characters. U+0000 (NUL) is not allowed.
workflowstring | nullOptionalTrimmed string, 3–240 characters. U+0000 (NUL) is not allowed.
candidatestring | nullOptionalhash, base64, jwt_debugger or other.
traffic_bandstring | nullOptionalunder_1k_day, 1k_to_10k_day, 10k_to_100k_day or 100k_plus_day.
utm_sourcestring | nullOptionalAt most 100 characters. U+0000 (NUL) is not allowed.
utm_mediumstring | nullOptionalAt most 100 characters. U+0000 (NUL) is not allowed.
utm_campaignstring | nullOptionalAt most 120 characters. U+0000 (NUL) is not allowed.
turnstile_tokenstring | nullOptionalAt most 2048 characters. Required by the service when Turnstile verification is enabled.

Request example

1. Set the base URL

This request creates or confirms a subscription. Replace the example email and token before running it intentionally.

Request example
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
HTTP 201
{
  "ok": true,
  "data": {
    "status": "subscribed"
  },
  "request_id": "req_example",
  "timestamp": "2026-09-26T00:00:00.000Z"
}
200Already subscribed
HTTP 200
{
  "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
HTTP 400
{
  "ok": false,
  "code": "INVALID_EMAIL",
  "message": "Invalid waitlist request",
  "request_id": "req_example",
  "timestamp": "2026-09-26T00:00:00.000Z"
}
429RATE_LIMITED
HTTP 429
{
  "ok": false,
  "code": "RATE_LIMITED",
  "message": "RATE_LIMITED",
  "request_id": "req_example",
  "timestamp": "2026-09-26T00:00:00.000Z"
}
500WAITLIST_DB_NOT_CONFIGURED
HTTP 500
{
  "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.
HTTP 503
{
  "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
HTTP 414
{
  "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
HTTP 413
{
  "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
HTTP 408
{
  "ok": false,
  "code": "REQUEST_TIMEOUT",
  "message": "Request body timeout or aborted",
  "request_id": "req_example",
  "timestamp": "2026-09-26T00:00:00.000Z"
}
Error handling

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.