Skip to content

API Overview

Beyond Retrieval v2 exposes a REST API built on FastAPI. All endpoints live under the /api prefix and follow consistent conventions for authentication, response shape, and error handling.

Base URL: http://localhost:8000/api

Response Envelope

Every endpoint (except GET /api/health) wraps its payload in a standard JSON envelope:

{
  "success": true,
  "data": { ... },
  "error": null
}

On error the shape becomes:

{
  "success": false,
  "data": null,
  "error": "Human-readable error message"
}

Frontend Consumption

The frontend apiFetch helper calls response.json().data to unwrap the envelope. If a backend endpoint returns a raw Pydantic model instead of APIResponse(data=...), the frontend will receive undefined.

Authentication

Beyond Retrieval v2 uses Clerk for production authentication and supports a bypass mode for local development.

Mode Condition Behavior
Bypass BYPASS_AUTH=true or no CLERK_SECRET_KEY All requests succeed as dev-user
Production BYPASS_AUTH=false with Clerk keys configured RS256 JWT verified against Clerk JWKS

Header format:

Authorization: Bearer <clerk_jwt_token>

See the Authentication page for full details.

Authorization Levels

Endpoints enforce one of three access levels:

Level Description
None Public -- no token required (GET /api/health, GET /api/auth/config)
User Any authenticated user (or dev-user in bypass mode)
Admin User with role: "admin" in Clerk public_metadata (or dev-user in bypass mode)

Notebook-scoped endpoints additionally check that the user has access to the specific notebook (via ownership or a redeemed invite).

Common Query Parameters

Parameter Type Used In Description
notebook_id string (UUID) Path Identifies the target notebook
file_id string (UUID) Path / Query Identifies a specific document file
conversation_id string (UUID) Path Identifies a chat conversation

Error Codes

Code Meaning Common Causes
200 OK Successful read or update
201 Created Successful resource creation (notebooks, conversations, invites)
400 Bad Request Missing required field, invalid enum value, missing API key
401 Unauthorized Missing or invalid JWT token
403 Forbidden Non-admin user attempting admin-only action
404 Not Found Resource does not exist
409 Conflict Re-ingestion of currently-processing file, or storage disabled
410 Gone Expired invite link
429 Too Many Requests LLM provider rate limit (enhancement pipeline)
500 Internal Server Error Unhandled exception in the backend
502 Bad Gateway Storage upload failure, Clerk API unreachable

Content Types

Endpoint Type Content-Type
JSON endpoints application/json
File upload multipart/form-data
Responses application/json (always)

Pagination

Most list endpoints return all records. The enhancement chunk listing supports server-side pagination:

Parameter Default Max Endpoint
limit 200 1000 GET /enhance/files/{file_id}/chunks
offset 0 -- GET /enhance/files/{file_id}/chunks

API Sections

Section Base Path Endpoints Description
Authentication /api/auth 1 Auth configuration
Notebooks /api/notebooks 7 Notebook CRUD
Settings /api/notebooks/{id}/settings 3 Per-notebook settings
Documents /api/notebooks/{id}/documents 13 Upload, ingest, manage
Chat /api/notebooks/{id} 11 Conversations and RAG
Retrieval /api/notebooks/{id}/retrieval 9 Search strategies
Enhancement /api/notebooks/{id}/enhance 11 AI chunk enhancement
Health Monitor /api/notebooks/{id}/health 2 Data quality checks
Models /api/models 3 LLM and embedding catalogs
Admin / Global Settings /api/settings 11 API keys, storage, DB type
OneDrive /api/onedrive 5 SharePoint integration
Users /api/admin 3 User management
Sharing /api/notebooks/{id}, /api/invite 7 Notebook sharing
Viewer /api/notebooks/{id} 2 Document content viewer
Developer API /api/v1/external 3 External RAG query & chat via API keys