Skip to API content
Birdor API v1

API reference · v1

Render a QR code

Render text as a QR code in SVG. Send an API key, or use the URL in an image tag, an email or Markdown by creating a signed URL with POST /v1/run/sign/url, which needs no header. Requires a credential with tools.run; every accepted call consumes one monthly unit, including business 4xx. Query strings can carry private content such as Wi-Fi passwords, so nothing derived from them is stored or logged. Output is deterministic; the response is cacheable by the browser only (private, max-age=600), so a repeated load may or may not reach the API and be metered again.

GET/v1/render/qr

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
datastringRequiredText to encode, 1 to 1024 UTF-8 bytes.
sizestringOptionalWidth and height in pixels, 64 to 1024; default 256.
marginstringOptionalQuiet zone in modules, 0 to 8; default 4 (the QR specification minimum).
ecL | M | Q | HOptionalError correction level: L (7%), M (15%), Q (25%) or H (30%); default M.
fgstringOptionalForeground colour as six hex digits without #; default 000000.
bgstringOptionalBackground colour as six hex digits without #; default ffffff. Must differ from fg.
formatsvgOptionalOutput format; only svg for now.
AuthorizationstringOptionalBearer API key with tools.run; alternatively X-API-Key. Omit when using a signed URL.
X-API-KeystringOptionalAlternative to Authorization; never send both.
X-Birdor-Workspace-IDstringOptionalRequired with the site session; optional and matching with an API key.
X-Birdor-Project-IDstringOptionalOptional owned project; a project-bound key cannot select another project.

Request example

1. Set the base URL

Request example
curl --request GET "$BIRDOR_API_BASE_URL/v1/render/qr?data=https%3A%2F%2Fbirdor.com&size=256" \
  --header "Accept: image/svg+xml" \
  --header "Authorization: Bearer $BIRDOR_API_KEY" \
  --output qr.svg

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

Responses

Illustrative response. Values vary by environment and time.

200SVG image
HTTP 200
"<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 33 33\" width=\"256\" height=\"256\" shape-rendering=\"crispEdges\" role=\"img\" aria-label=\"QR code\">…</svg>"
400Unknown, duplicate, missing or out-of-range query parameters (field paths and codes only, never values) or ambiguous credentials
HTTP 400
{
  "ok": false,
  "code": "VALIDATION_ERROR",
  "message": "Invalid request parameters",
  "request_id": "req_example",
  "timestamp": "2026-10-11T00:00:00.000Z"
}
401Missing, expired, rotated, revoked or invalid credential; for signed URLs also INVALID_SIGNATURE and SIGNED_URL_EXPIRED. There is no anonymous access
HTTP 401
{
  "ok": false,
  "code": "UNAUTHENTICATED",
  "message": "API access denied",
  "request_id": "req_example",
  "timestamp": "2026-10-11T00:00:00.000Z"
}
403Key lacks tools.run, or workspace/project/member policy or site Origin denied
HTTP 403
{
  "ok": false,
  "code": "FORBIDDEN",
  "message": "API access denied",
  "request_id": "req_example",
  "timestamp": "2026-10-11T00:00:00.000Z"
}
405Only GET is supported; HEAD is rejected so no request skips admission
HTTP 405
{
  "ok": false,
  "code": "METHOD_NOT_ALLOWED",
  "message": "Method not allowed",
  "request_id": "req_example",
  "timestamp": "2026-10-11T00:00:00.000Z"
}
429Ingress, workspace/actor minute or monthly quota exceeded; inspect code and Retry-After
HTTP 429
{
  "ok": false,
  "code": "QUOTA_EXCEEDED",
  "message": "API request limit exceeded",
  "request_id": "req_example",
  "timestamp": "2026-10-11T00:00:00.000Z"
}
503Authentication/metering dependency unavailable, or SIGNING_NOT_CONFIGURED for a signed URL
HTTP 503
{
  "ok": false,
  "code": "API_GATEWAY_UNAVAILABLE",
  "message": "API access denied",
  "request_id": "req_example",
  "timestamp": "2026-10-11T00: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.