API reference

Bairav exposes three HTTP APIs. They are described by OpenAPI 3.1 documents you can download and load into your own tools.

API	Base path	Credential	Download	Use it to
Gateway API	/gw/{token}/...	Gateway key in the path, your provider key in Authorization	gateway.yaml	Govern model calls and report reasoning trails
Ingest API	/api/ingest/...	X-Sensor-Token or X-Ingest-Token	ingest.yaml	Send sensor events, security events, traces and SBOMs
Portal API	/api/...	Authorization: Bearer <access token>	portal.yaml	Manage agents, policies, keys, the Audit ledger and security data

Replace {host} in every example with the hostname of your Bairav deployment.

Conventions

• Not versioned. Paths start with /api/ or /gw/. Check the changelog before upgrading.
• Tenant from the token. Never send a tenant ID in a request body or query.
• Errors are {"detail": ...} for the Portal and Ingest APIs, and an OpenAI-style {"error": {...}} for the gateway. See Errors and limits.
• Lists return {"items": [...]} and page with limit and an opaque cursor; the response carries next_cursor until the last page.
• Times are ISO-8601 in UTC.
• Request IDs. Every Portal API response carries X-Request-ID. Send your own to correlate, and quote it when you contact support.
• Unknown is not zero. Where a value was not recorded (for example cost), the API returns null and an explicit flag, never 0.

How complete is this reference

API	Operations	Request bodies	Response bodies
Gateway	7, written by hand	Described	Described
Ingest	6, written by hand	Described	Described
Portal	Generated from the source for the operations on the public allowlist	Described	Described for sign-in, gateway keys and the Audit ledger; open for the rest

Operations whose response schema is open are marked in the changelog as they are completed.