Birdor API Overview

Birdor exposes the same capabilities used by the tools — hashing, encoding, JSON diffing, cron parsing, identifiers and more — as simple, predictable HTTP APIs. This page gives you a high-level introduction to the API surface: authentication, versioning, common patterns, and resource families.

For the bigger picture of how APIs fit into the platform, see the platform overview and the Developer Console docs.

Base URL & Transport

Birdor APIs are plain HTTPS JSON APIs. There are no SDK requirements, and you can call them from any HTTP client.

Base URL (example)

https://api.birdor.com/v1/...

Exact hostnames and regions will be documented here as they are rolled out. All public APIs are served over HTTPS only.

Content types

Requests: JSON bodies with Content-Type: application/json.
Responses: JSON payloads with consistent error shapes.
Some tools may also support binary inputs/outputs — those will be clearly marked in their individual docs.

Authentication

Birdor APIs use API keys for authentication. Keys are created and managed in the Developer Console, and can be scoped per project and per environment.

HTTP header

Authorization: Bearer birdor_live_xxx...

API keys are secret credentials. Never embed them in mobile apps, frontend bundles, or other client-side code.

Basic example (curl)

curl https://api.birdor.com/v1/hash/sha256 \
  -H "Authorization: Bearer $BIRDOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":"hello"}'

Key formats, prefixes (e.g. birdor_live_*) and rotation guidelines will be fully documented here before public launch.

Versioning & Stability

Birdor aims to keep APIs boring and backwards-compatible. The version is encoded in the URL path (e.g. /v1/).

Minor additions (new optional fields, new endpoints) do not change the version.
Breaking changes will result in a new version (e.g. /v2/) and a clear migration guide.
Old versions will be given a reasonable deprecation window, clearly communicated in docs and changelog.

A detailed versioning & deprecation policy will be added here as the surface area grows.

Request & Response Patterns

Most Birdor API endpoints follow a simple JSON pattern:

Success

HTTP 200 OK
{
  "ok": true,
  "data": {
    // endpoint-specific payload
  }
}

Error

HTTP 4xx / 5xx
{
  "error": {
    "type": "invalid_request",
    "message": "Something went wrong",
    "code": "ERR_SOME_REASON",     // optional, machine-readable
    "details": { ... }             // optional, endpoint-specific
  }
}

Each endpoint will document its specific data and error.details shape, but the outer wrapper stays consistent.

API Resource Families

APIs are grouped by capability. The initial surface focuses on everyday building blocks you're likely to need across projects:

Hash & Security

/v1/hash/* — compute hashes for payloads.
/v1/hmac/* — generate HMACs with shared secrets.
/v1/jwt/* — decode, inspect, and (optionally) validate JWTs.

Encoding & URLs

/v1/base64/* — encode/decode Base64 and Base64URL.
/v1/text/* — text encode/decode, escaping helpers.
/v1/url/* — parse and manipulate URLs and query strings.

JSON & Data

/v1/json/diff — compute structural diffs between two JSON documents.
/v1/json/format — pretty-print or minify JSON.

Time, Cron & IDs

/v1/time/timestamp — convert timestamps to/from human-readable dates.
/v1/cron/parse — parse cron expressions and list next run times.
/v1/id/uuid & /v1/id/nanoid — generate identifiers.

Exact endpoints and payloads will be documented under per-resource reference pages (e.g. /docs/platform/api/hash) as they stabilize.

Rate Limits & Quotas

Birdor applies fair, predictable rate limits and quotas based on your plan. Limits are tracked per workspace and per API key.

Free plans have generous but bounded monthly request quotas and sensible per-second caps.
Paid plans raise those limits and may unlock higher concurrency or dedicated pools.
When you approach limits, Birdor prefers gentle warnings over surprise failures.

Exact numbers, headers (e.g. X-RateLimit-*) and upgrade paths will be documented here as pricing and plans roll out.

Language Examples

Because the APIs are plain HTTPS, you can use them from any language. Official examples will focus on:

JavaScript / TypeScript (Node, edge runtimes)
Go
Python
Java / Kotlin

As the platform matures, language-specific helpers or lightweight SDKs may be added — but the core HTTP API will remain the source of truth.

Detailed code samples will live alongside each specific API reference page once the endpoints are stable.

Next Steps

This page is the top-level map of Birdor's API surface. As individual endpoints stabilize, they will gain their own dedicated reference pages under /docs/platform/api/*.

In the meantime, you can follow the overall direction and philosophy in the Birdor Platform Vision and keep an eye on the changelog for new API capabilities as they land.