Skip to main content
The Fabro API is under active development and may be subject to change. Endpoints, request/response formats, and authentication mechanisms may evolve as the project matures.
The Fabro API is a REST API for managing workflow runs, interactive sessions, and related resources. All requests and responses use JSON.

​
Base URL

By default, fabro server start listens on the Unix socket ~/.fabro/fabro.sock. If you bind Fabro to TCP instead, the versioned API is served at a URL like:
The advertised public API URL is configurable via settings.toml:
settings.toml

​
Authentication

Fabro configures server auth with bootstrap methods:
settings.toml
Protected /api/v1/* routes always accept:
  • Authorization: Bearer <token>
  • the browser session cookie when the web UI is enabled
If both are present, the Authorization header wins.

​
Dev Token

When "dev-token" is enabled, the API accepts the raw dev token directly as a bearer credential:
This is the simplest way to make ad hoc local requests with curl or a script. The dev token is also available as a web login method when the web UI is enabled.

​
GitHub OAuth

When "github" is enabled, browser users can sign in through GitHub OAuth. Successful logins mint a server-issued session cookie that the browser automatically sends on subsequent API requests. [server.auth.github].allowed_usernames restricts which GitHub usernames may complete login.

​
Browser Sessions

When [server.web].enabled = true, the server requires SESSION_SECRET and issues a private __fabro_session cookie after successful login. The cookie is session transport only; the underlying bootstrap method remains dev-token or github, and that provenance is preserved in run metadata.

​
HTTPS and Reverse Proxies

Fabro’s listener is plain HTTP (or a Unix socket) only. If you want a public HTTPS endpoint, terminate TLS at a reverse proxy, load balancer, or platform ingress and point it at Fabro’s internal listener.

​
Errors

​
Error Shape

All error responses share a consistent JSON structure:
Each entry in the errors array contains:

​
HTTP Status Codes

​
Pagination

List endpoints that return large collections use offset-based pagination. Pass pagination parameters as query strings: Paginated responses include a meta object alongside the data array:
When has_more is true, increment the offset by the limit to fetch the next page.

​
Versioning

The Fabro API is versioned under /api/v1. All versioned endpoints, including the OpenAPI document, live under that prefix. Future breaking changes can be introduced under a new versioned prefix while preserving existing clients.

​
Discovery

The root endpoint (GET /) returns discovery URLs. The health endpoint (GET /health) can be used for liveness checks. The OpenAPI spec is available at GET /api/v1/openapi.json.