API Overview & Authentication

Base URL

All API requests are made against the following base URL. Append the endpoint path to the base URL for each request.

https://api.usbios.ai

The BiOS console is available at https://bios.us.com. The API gateway is a separate service that handles all programmatic access.

Authentication

The recommended authentication method is an API key passed via the X-API-Key header. Each API key is scoped to one workspace. The API resolves the organization and workspace automatically, so no extra headers are needed.

X-API-Key: sk_live_your_key_here
Content-Type: application/json

Alternatively, JWT Bearer tokens are supported (used by the web console). JWT auth requires additional X-Org-ID and X-Workspace-ID headers.

Error Response Format

All error responses follow a consistent JSON structure:

{
  "status": 400,
  "error": "Bad Request",
  "detail": "A human-readable description of what went wrong",
  "code": "VALIDATION_ERROR"
}

Rate Limits

The API enforces rate limits on a per-user basis. When you exceed the limit, you will receive a 429 Too Many Requests response with a Retry-After header indicating when you can retry.

Common Status Codes