Versioning
The API has one version, v1, at https://farbeamlabs.com/api/v1. It is the first release, dated 2026-11-04 UTC in the changelog. The version lives in the path. There is no version header.
| Item | Value |
|---|---|
| Current version | v1 |
| Base path | /api/v1 |
| OpenAPI file | /api/v1/openapi.json, OpenAPI 3.1.0 with info.version 1.0.0 |
| Paths outside the version | /api/live (the stream) |
| Deprecation schedule | None published |
| SLA | None. An SLA is Planned. |
#What this version promises
Farbeam is early, and it does not publish a formal stability contract. These statements describe how the service is built and how changes are recorded, and they are not a contractual guarantee.
- Changes that affect API clients go in the API changelog, with a UTC date.
- Error
codevalues are the stable part of an error. Message text is not. meta.as_ofandmeta.request_idappear on every successful response.
#What can change without a new version
Write your client so these changes do not break it.
| Change | What to do in your client |
|---|---|
| A new field in an object | Ignore unknown fields. Do not use strict schema validation that rejects extras. |
A new item in checks[] | Key by id, and do not rely on array position. Treat an unrecognized id as information. |
| A new chain | Do not hard-code seven. Read /chains. |
| A new curated token | Read tokens[] from /chains. Rows can appear with a new token value. |
| New labels, or corrected ones | Do not cache labels forever. Read them again from /labels. |
| A changed cache time | Read meta.as_of as the response time, and do not build logic on an exact TTL. |
A new kind value | Handle an unknown kind by skipping or logging it. |
#Timestamps differ by surface
This is the most common client bug, so it is worth stating here.
| Surface | Type of ts | Example |
|---|---|---|
GET /transfers, POST /rules/validate samples, GET /chains/{chain}/blocks | ISO 8601 string in UTC | 2026-11-04T19:20:59.000Z |
SSE transfer and block events, webhook data.ts, indexed_transfers[].ts, wallet signature ts, GET /tx ts | Integer milliseconds since the Unix epoch | 1793819663000 |
Normalize at the edge of your client. In JavaScript, new Date(value) accepts both. In Python, check the type first.
#Client checklist
- Send requests to the
/api/v1path, and keep the base URL in one constant. - Ignore unknown JSON fields.
- Branch on
error.code, never onerror.message. - Log
x-request-idon failures. - Handle
nullon all optional fields. Many numeric fields arenullon the chain families where they do not apply. See the data model. - Read the OpenAPI file if you generate code. It lists paths, parameters and error statuses. It does not hold response schemas, so generated types for response bodies need hand work. Use the API reference for fields.
#Pre-release channels
There is no beta channel, sandbox or testnet API. Testnets are Planned. To test code that handles webhooks, use a test delivery. To test rules, use Validate a rule, which runs against real stored rows and sends nothing.