API Overview — bRRAIn Docs

REST API overview including base URL, authentication, versioning, rate limits, and common patterns.

API Overview

The bRRAIn REST API provides programmatic access to all platform capabilities. This document covers the conventions, authentication, versioning, and rate limiting that apply to every endpoint.

Base URL

All API requests are made to:

https://api.brrain.io/v1

Self-hosted deployments use your configured domain:

https://your-domain.com/v1

All endpoints require HTTPS. Plain HTTP requests are rejected with a 301 redirect.

Authentication

Every request must include a valid authentication credential. bRRAIn supports three authentication methods:

API Keys

The simplest method. Include your API key in the Authorization header:

Authorization: Bearer brr_live_k1a2b3c4d5e6f7g8h9i0

API keys are scoped to a specific vault and workspace with defined permissions (read-only, read-write, or admin). See API Authentication for details on key management.

OAuth 2.0 Tokens

For user-facing applications, use the OAuth 2.0 authorization code flow to obtain short-lived access tokens. These tokens carry the user's identity and workspace permissions.

Session Tokens

The bRRAIn dashboard uses session tokens for browser-based access. These are not recommended for programmatic use.

Request Format

All request bodies must be JSON with the Content-Type: application/json header. Query parameters use standard URL encoding.

curl -X POST https://api.brrain.io/v1/memory/store \
  -H "Authorization: Bearer brr_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "example"}'

Response Format

All responses return JSON with a consistent structure:

Success Response

{
  "id": "mem_abc123",
  "status": "stored",
  "created_at": "2026-04-15T10:00:00Z"
}

Error Response

{
  "error": {
    "code": "validation_error",
    "message": "The 'content' field is required.",
    "request_id": "req_xyz789",
    "status": 400
  }
}

Every response includes a X-Request-Id header for tracing and support purposes.

Versioning

The API is versioned in the URL path (/v1/). When breaking changes are introduced, a new version is released (e.g., /v2/). Previous versions remain available for at least 12 months after a new version launches.

Non-breaking changes (new optional fields, new endpoints) are added to the current version without a version bump. We publish these additions in the Changelog.

Rate Limits

Rate limits protect the platform and ensure fair usage across tenants.

| Plan | Requests/minute | Burst | |------|-----------------|-------| | Free | 60 | 10 | | Pro | 600 | 100 | | Enterprise | 6,000 | 1,000 | | Self-Hosted | Configurable | Configurable |

Rate limit headers are included in every response:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 587
X-RateLimit-Reset: 1713175260

When you exceed the limit, you receive a 429 Too Many Requests response. Implement exponential backoff with jitter for retries.

Pagination

List endpoints return paginated results using cursor-based pagination:

GET /v1/memory?limit=25&cursor=eyJpZCI6Im1lbV8xMjMifQ

The response includes a next_cursor field when more results are available:

{
  "results": [...],
  "next_cursor": "eyJpZCI6Im1lbV80NTYifQ",
  "has_more": true
}

The default page size is 25. Maximum page size is 100.

Idempotency

Write operations support idempotency keys to safely retry requests without creating duplicates:

Idempotency-Key: unique-request-id-12345

Idempotency keys are valid for 24 hours. Repeating a request with the same key returns the original response without performing the operation again.

Common HTTP Status Codes

| Code | Meaning | |------|---------| | 200 | Success | | 201 | Created (new resource) | | 400 | Bad request (validation error) | | 401 | Unauthorized (missing or invalid credentials) | | 403 | Forbidden (insufficient permissions) | | 404 | Resource not found | | 409 | Conflict (duplicate resource) | | 429 | Rate limit exceeded | | 500 | Internal server error | | 503 | Service unavailable (maintenance or overload) |

SDKs

Official SDKs wrap the REST API with language-idiomatic interfaces:

  • Go: go get github.com/Qosil/brrain-go
  • Python: pip install brrain
  • JavaScript: npm install @brrain/sdk

Each SDK handles authentication, retries, pagination, and error handling automatically.

Next Steps