API Reference — Overview

Base URL, JWT authentication, rate limits per plan, error format, status codes, and versioning.

Base URL

All requests are directed to:

https://api.relaai.com/api/v1/

Internal requests between microservices use:

http://internal-api:8000/api/v1/

Authentication

The API uses JSON Web Tokens (JWT) issued upon login. Include the token in the Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

JWT Field	Description
`sub`	User ID
`tenant_id`	Tenant ID
`role`	User role
`permissions`	Permission list
`exp`	Expiration (15 minutes by default)

Tokens are refreshed via POST /api/v1/auth/refresh with the refresh token.

Rate Limits per Plan

Plan	Requests/min	Max burst
Free	30	10
Starter	120	30
Professional	600	100
Enterprise	3,000	500

Response headers included in every request:

X-RateLimit-Limit — Total window limit
X-RateLimit-Remaining — Remaining requests
X-RateLimit-Reset — Reset timestamp (Unix epoch)

Error Format

All errors follow a consistent format:

{
  "detail": "Resource not found",
  "error_code": "NOT_FOUND",
  "request_id": "req_abc123"
}

Status Codes

Code	Meaning
`200`	Successful operation
`201`	Resource created
`204`	Deleted, no content
`400`	Invalid request
`401`	Not authenticated
`403`	No permissions or plan limit reached
`404`	Resource not found
`409`	Conflict (duplicate)
`422`	Validation error
`429`	Rate limit exceeded
`500`	Internal server error

Pagination

List endpoints support pagination with skip and limit:

GET /api/v1/agents?skip=0&limit=20

The response includes pagination metadata in the body.

The live API exposes ~20 routers under /api/v1/. This section's pages cover the most-used groups (agents, assets, maintenance, data, admin). This table is the single source of truth for the complete list:

Prefix	Purpose	Docs
`/api/v1/whatsapp/agents`	WhatsApp agents	whatsapp-agents/create
`/api/v1/whatsapp/numbers`	Evolution API numbers	whatsapp-agents/numbers
`/api/v1/email`	Email agents	email-agents/create
`/api/v1/email/accounts`	Postmark email accounts	email-agents/accounts
`/api/v1/tools`	Agent tools	tools/overview
`/api/v1/prompts`	Gemini prompt optimizer	features/prompt-optimizer
`/api/v1/collections`	Data collections	data/collections
`/api/v1/extraction-templates`	Extraction templates	data/extractions
`/api/v1/extractions`	AI extraction + record CRUD	data/extractions
`/api/v1/files`	Multipart upload to GCS	features/file-uploads
`/api/v1/machine`	Industrial event gateway	machine-agents/create
`/api/v1/dashboard`	Operational dashboard KPIs	features/operational-dashboard
`/api/v1/assets`	Industrial assets	assets-api
`/api/v1/predictive-config`	Predictive engine config	maintenance/predictive-config
`/api/v1/reports`	On-demand PDF/Excel reports	data/reports
`/api/v1/scheduled-reports`	Scheduled reports	data/scheduled-reports
`/api/v1/brandings`	Branding presets	admin/brandings
`/api/v1/audit`	Immutable audit trail	admin/audit
`/api/v1/csat`	CSAT surveys	features/csat

All endpoints are REST JSON, JWT-authenticated and rate-limited per plan. The pipeline architecture lives at architecture.

Versioning

The current version is v1. When a new version becomes available, deprecation headers will indicate the migration path:

Deprecation: true
Sunset: Sat, 01 Jan 2027 00:00:00 GMT
Link: </api/v2/resource>; rel="successor-version"

Internal Endpoints

Some endpoints are reserved for inter-service communication:

Endpoint	Usage
`POST /internal/events`	Internal event ingestion
`POST /internal/notifications`	Notification queue
`GET /internal/health`	Service health check

These endpoints require an internal service token and are not exposed in the public API.