API Reference

The EpsimoAI backend exposes a RESTful API for managing assistants, threads, messages, and runs. All authenticated endpoints require a JWT token obtained via authentication.

Interactive Documentation

The API is fully documented with OpenAPI 3.x and available in multiple formats:

Format URL Best for
Swagger UI https://backend.epsimoagents.com/docs Interactive exploration, "Try it out"
ReDoc https://backend.epsimoagents.com/redoc Reading documentation, searching endpoints
OpenAPI JSON https://backend.epsimoagents.com/openapi.json Code generation, importing into Postman/Insomnia

Base URL

https://backend.epsimoagents.com

All endpoint paths in this documentation are relative to this base URL.

Authentication

Most endpoints require a Bearer token in the Authorization header. See the full Authentication Guide for all supported mechanisms.

The simplest approach for CLI/script usage:

# Login and obtain a JWT
JWT=$(curl -s -X POST https://backend.epsimoagents.com/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"your-password"}' \
  | jq -r .jwt_token)

Then pass it on every request:

curl -s https://backend.epsimoagents.com/threads \
  -H "Authorization: Bearer $JWT"

Quick Example: Authenticate and List Threads

Full end-to-end example:

#!/bin/bash
# Authenticate and list all threads in the current project

# Step 1: Login
JWT=$(curl -s -X POST https://backend.epsimoagents.com/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"your-password"}' \
  | jq -r .jwt_token)

if [ "$JWT" = "null" ] || [ -z "$JWT" ]; then
  echo "Login failed"
  exit 1
fi

# Step 2: List threads
curl -s https://backend.epsimoagents.com/threads \
  -H "Authorization: Bearer $JWT" | jq '.[].thread_id'

Example response:

[
  {
    "thread_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "My conversation",
    "created_at": "2026-05-15T10:30:00Z",
    "updated_at": "2026-05-15T11:00:00Z"
  }
]

Key Endpoint Groups

Group Path Prefix Description
Auth /auth/* Login, signup, OAuth, token exchange
Projects /projects/* List/switch projects, get project-scoped JWTs
Assistants /assistants/* CRUD for AI assistants
Threads /threads/* CRUD for conversation threads
Runs /runs/* Execute assistant runs (streaming)
Public /public/* Public assistant endpoints (token or no-auth)
Admin /admin/* System administration (admin token required)

Response Format

{
  "detail": "Error description here"
}

Common HTTP status codes:

Code Meaning
200 Success
201 Created
401 Unauthorized — missing or invalid JWT
403 Forbidden — insufficient permissions
404 Not found
422 Validation error — malformed request body
500 Internal server error

Streaming Endpoints

Endpoints like /runs/stream and /public/runs/stream return Server-Sent Events (SSE). Each event has the format:

event: <event-type>
data: <json-payload>

Use curl -N (no buffering) or an SSE client library to consume these streams.