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/

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.

Response headers included in every request:

All errors follow a consistent format:

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

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

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 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"

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.