Skip to API content
Birdor API v1

API reference · v1

Batch lookup tools

Authenticated lookup of tool IDs. Third-party servers send a tools.read API key in Authorization: Bearer; the main site uses its HttpOnly session plus X-Birdor-Workspace-ID and same-origin POST. Accepted requests share workspace minute/month limits and consume one monthly unit, including business 4xx/5xx. Unknown IDs are omitted; no matches returns 404. Results follow catalog order. Requires a live tools.read credential; there is no anonymous access and every admitted call consumes one monthly unit. API key headers are alternatives; a site session needs workspace selection instead. Pending/unknown outcomes retain reserved units. Catalog HEAD and unsupported methods return405 with Allow/no-store before admission. New client retries are new admissions; trace/Idempotency-Key do not deduplicate them. Rate headers reflect the stricter workspace/actor bound; ingress limits are separate.

POST/v1/tools/query

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

FieldDescription
AuthorizationstringOptionalThird-party server: Bearer API key with tools.read scope. Use BIRDOR_API_KEY from the server environment; never put keys in URLs or main-site browser JavaScript.
X-Birdor-Workspace-IDstringOptionalRequired for main-site session calls; for API keys, omitted or equal to the key workspace.
X-Birdor-Project-IDstringOptionalOptional owned project; a project-bound key cannot select another project.
X-API-KeystringOptionalAlternative to Authorization; never send both API key headers or combine key and site session.

Request body

Send JSON with Content-Type: application/json.

FieldDescription
idsstring[]Required1–100 IDs, each 1–128 Unicode code points. Unknown IDs are omitted. Slugs are not matched separately.

Request example

1. Set the base URL

Request example
curl --request POST "$BIRDOR_API_BASE_URL/v1/tools/query" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer $BIRDOR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "ids": [
    "base64"
  ]
}'

Examples are copied only; this page does not send API requests.

Responses

Illustrative response. Values vary by environment and time.

200Success
HTTP 200
{
  "ok": true,
  "data": [
    {
      "id": "base64",
      "slug": "base64",
      "name": "Base64 Encoder / Decoder",
      "shortDescription": "Encode and decode Base64 strings in your browser.",
      "category": "encoding",
      "path": "/tools/base64",
      "tags": [
        "base64",
        "encoding",
        "decoder"
      ]
    }
  ],
  "request_id": "req_example",
  "timestamp": "2026-09-26T00:00:00.000Z",
  "meta": {
    "count": 1
  }
}
400Invalid JSON, ids array, workspace selection or ambiguous credentials; INVALID_REQUEST_BODY is a pre-admission stream read failure
401Missing, expired, rotated or revoked credential
HTTP 401
{
  "ok": false,
  "code": "UNAUTHENTICATED",
  "message": "API access denied",
  "request_id": "req_example",
  "timestamp": "2026-09-26T00:00:00.000Z"
}
403Insufficient scope, workspace/project access or invalid site Origin
HTTP 403
{
  "ok": false,
  "code": "FORBIDDEN",
  "message": "API access denied",
  "request_id": "req_example",
  "timestamp": "2026-09-26T00:00:00.000Z"
}
429Workspace/actor minute rate or shared monthly quota exceeded; inspect Retry-After
HTTP 429
{
  "ok": false,
  "code": "QUOTA_EXCEEDED",
  "message": "API request limit exceeded",
  "request_id": "req_example",
  "timestamp": "2026-09-26T00:00:00.000Z"
}
503Authentication or metering dependency unavailable; a transport timeout can leave admission pending, inspect request trace
HTTP 503
{
  "ok": false,
  "code": "API_GATEWAY_UNAVAILABLE",
  "message": "API access denied",
  "request_id": "req_example",
  "timestamp": "2026-09-26T00:00:00.000Z"
}
404No tools found
HTTP 404
{
  "ok": false,
  "code": "NOT_FOUND",
  "message": "No tools found",
  "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"
}
413Streamed or declared body exceeds 32768 bytes
HTTP 413
{
  "ok": false,
  "code": "PAYLOAD_TOO_LARGE",
  "message": "Request body too large",
  "request_id": "req_example",
  "timestamp": "2026-09-26T00:00:00.000Z"
}
408Request body 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"
}
415JSON content type required
HTTP 415
{
  "ok": false,
  "code": "UNSUPPORTED_MEDIA_TYPE",
  "message": "JSON content type required",
  "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.
dataarray
Endpoint-specific result.
data[].idstring
Resource identifier.
data[].slugstring
Tool URL identifier.
data[].namestring
Name or token identifier.
data[].shortDescriptionstring
Short tool description.
data[].categorystring
Tool category.
data[].pathstring
Browser tool path.
data[].tagsarray
Tool tags.
request_idstring
Origin-response identifier matching X-Request-ID; a shared HTTP cache may replay the original trace.
timestampstring
Response creation timestamp.
metaobject
Optional response metadata.
meta.countnumber
Matching item count.