API reference · v1
List tools
Browse tool metadata with optional filters and pagination. This endpoint does not execute tools. meta.count is the total matching count before pagination. 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.
/v1/toolsAccess 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 |
|---|---|
categorystringOptional | Exact category filter; maximum 64 Unicode code points. |
tagstringOptional | Exact tag filter; maximum 64 Unicode code points. |
pageintegerOptional | Between 1 and 1000000; default 1. |
limitintegerOptional | Between 1 and 50; default 20. |
AuthorizationstringOptional | Bearer tools.read API key for third-party servers; alternatively X-API-Key or the site session. One credential is required. |
X-API-KeystringOptional | Alternative to Authorization; never send both API key headers or combine key and site session. |
X-Birdor-Workspace-IDstringOptional | Required with the HttpOnly site session; optional and matching with API key. |
Request example
curl --request GET "$BIRDOR_API_BASE_URL/v1/tools" \
--header "Accept: application/json" \
--header "Authorization: Bearer $BIRDOR_API_KEY"Examples are copied only; this page does not send API requests.
Responses
Illustrative response. Values vary by environment and time.
200Success
{
"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,
"cached": false
}
}400Invalid parameters/JSON body, or INVALID_REQUEST_BODY on stream read failure before admission; shared trace envelope
{
"ok": false,
"code": "VALIDATION_ERROR",
"message": "Invalid request parameters",
"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"
}429Ingress limit exceeded before admission
{
"ok": false,
"code": "INGRESS_RATE_LIMITED",
"message": "Ingress request limit exceeded",
"request_id": "req_example",
"timestamp": "2026-09-26T00:00:00.000Z"
}503Ingress protection or route dependency unavailable
{
"ok": false,
"code": "INGRESS_UNAVAILABLE",
"message": "Ingress protection unavailable",
"request_id": "req_example",
"timestamp": "2026-09-26T00:00:00.000Z"
}401Missing, expired, revoked, rotated or invalid credential; there is no anonymous access
{
"ok": false,
"code": "UNAUTHENTICATED",
"message": "API access denied",
"request_id": "req_example",
"timestamp": "2026-09-26T00:00:00.000Z"
}403Scope, workspace/project/member policy or site Origin denied
{
"ok": false,
"code": "FORBIDDEN",
"message": "API access denied",
"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.
- 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.
- meta.cachedboolean
- Cache indicator when supplied.