API-Referenz
Alles, was ein API-Schlüssel aufrufen kann – erzeugt aus dem laufenden Dienst, nicht von Hand geschrieben.
Vertragsversion 1.0.0
Every endpoint an API key can call, and nothing else.
Authenticating
Send the key as a bearer token: Authorization: Bearer fk_live_<prefix>_<secret> X-Org-ID: <the organization's id> X-Org-ID is required: a key belongs to one organization, and naming the wrong one is a 403 rather than an empty result, so a misconfigured integration fails loudly.
Scopes
A key carries an explicit list of scopes and can reach only the endpoints whose x-forge-scope it holds. The vocabulary is closed: orgs:read, members:read, members:write, files:read. Asking for a scope outside it is a 422 naming the offending value.
Rate limits
Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and a 429 additionally carries Retry-After. The limit is per key, so one integration cannot spend another's budget.
Errors
Every response, success or failure, is the same envelope: {"data": ..., "error": ..., "meta": {"request_id": ...}}. Quote meta.request_id in a support request -- it is what identifies the exact call in the logs.
Versioning
A breaking change gets a new path prefix; this one is never redefined underneath you. Breaking means: removing an endpoint or a response field, making an optional request field required, narrowing an accepted value set, or changing a field's type. Adding an endpoint, adding a response field and adding an optional request field are not breaking, so build clients that ignore unknown fields. Any breaking change is announced at least 90 days ahead, and the superseded version keeps working for those 90 days.
Endpunkte
GET /api/v1/orgs/{org_id}
Erfordert die Berechtigung orgs:read
The organization record. Callable with an API key holding the orgs:read scope, or with a session belonging to the organization.
GET /api/v1/orgs/{org_id}/members
Erfordert die Berechtigung members:read
The organization's members, cursor-paginated. Callable with an API key holding the members:read scope, or with a session belonging to the organization.