API Reference

Base URL: http://localhost:3001/api (or your deployed instance).

All authenticated endpoints require Authorization: Bearer <token>. Tokens are either:

User JWT — returned by POST /auth/login
API token — created in project settings, with specific permissions (logs:write, heartbeat:write, etc.)

Authentication

`POST /auth/register`

Create a new account.

// Request
{
  "firstName": "Jane",
  "lastName": "Doe",
  "pseudo": "janedoe",
  "email": "jane@example.com",
  "password": "mypassword123"
}

// Response 201
{ "ok": true }

`POST /auth/login`

// Request
{ "email": "jane@example.com", "password": "mypassword123" }

// Response 200
{ "token": "eyJ..." }

// Response 200 (2FA required)
{ "requires2FA": true, "sessionToken": "tmp_..." }

`POST /auth/2fa/verify`

Complete 2FA login with a temporary session token:

// Request
{ "sessionToken": "tmp_...", "code": "123456" }

// Response 200
{ "token": "eyJ..." }

`GET /auth/me`

Returns the authenticated user profile. Requires user JWT (not API token).

Projects

All project routes require Authorization: Bearer <user-jwt>.

`GET /projects`

List all projects for the authenticated user.

`POST /projects`

// Request
{ "name": "my-project", "label": "My Project" }

// Response 201
{ "id": 1, "name": "my-project", "label": "My Project" }

name must be lowercase, digits and hyphens only.

`DELETE /projects/:projectName`

Permanently delete a project and all its data.

`PATCH /projects/:projectName/archive`

Archive a project (hides from dashboard, preserves data).

`PATCH /projects/:projectName/restore`

Restore an archived project.

Sources

`GET /projects/:projectName/sources`

List sources for a project.

`POST /projects/:projectName/sources`

// Request
{ "name": "api-backend", "description": "Main API server" }

// Response 201
{ "id": 1, "name": "api-backend", "token": "sk_..." }

The returned token is used to authenticate log writes from the SDK or agent.

Logs

`GET /projects/:projectName/logs`

Search logs with filters:

Query param	Type	Description
`level`	string	Filter by log level
`search`	string	Full-text search in message
`source`	string	Filter by source name
`tags`	string	Comma-separated tag filter
`from`	ISO date	Start of time range
`to`	ISO date	End of time range
`limit`	number	Max results (default 100)
`offset`	number	Pagination offset

`GET /projects/:projectName/logs/export`

Same filters as above, returns a downloadable file.

`GET /projects/:projectName/sources/:sourceName/logs`

Logs for a specific source. Supports the same query params.

Agent (SDK / system agent writes)

These endpoints are used by orion-monitoring SDK and the system agent. Auth via API token with the required permission.

`POST /agent/log`

Send one log entry or a batch. Requires logs:write permission.

// Single log
{
  "timestamp": "2024-01-15T10:30:00.000Z",
  "level": "info",
  "message": "User signed in",
  "metadata": { "userId": "u_123" },
  "tags": ["auth"]
}

// Batch (array)
[
  { "timestamp": "...", "level": "info", "message": "..." },
  { "timestamp": "...", "level": "error", "message": "..." }
]

`POST /agent/register`

// Request
{
  "serverId": "my-server",
  "displayName": "Production Server",
  "hostname": "prod-1.example.com",
  "platform": "linux",
  "arch": "x64",
  "projectName": "my-project"
}

// Response 201
{ "token": "sk_agent_..." }

`POST /agent/heartbeat`

Send a heartbeat. Requires heartbeat:write permission.

{
  "timestamp": "2024-01-15T10:30:00.000Z",
  "uptime": 86400,
  "cpu": { "percent": 12.5 },
  "ram": { "usedMb": 1024, "totalMb": 4096, "percent": 25 },
  "disk": { "usedGb": 20, "totalGb": 100, "percent": 20 },
  "network": { "rxBytesPerSec": 1024, "txBytesPerSec": 512 },
  "scripts": [{ "name": "api", "status": "running" }]
}

`POST /agent/alert`

Send a crash or critical alert. Requires logs:write permission.

{
  "event": "script_crash",
  "message": "Process exited with code 1",
  "scriptName": "api-backend",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

`POST /agent/source`

// Request
{ "name": "api-backend", "cwd": "/opt/myapp" }

// Response 201
{ "token": "sk_source_..." }

`GET /agent/commands`

Poll for pending commands (e.g. restart). Requires commands:read permission.

`POST /agent/commands/:id/ack`

Acknowledge a command as executed. Requires commands:write permission.

Alert Rules

`GET /projects/:projectName/alerts/rules`

List alert rules for a project.

`POST /projects/:projectName/alerts/rules`

{
  "name": "High error rate",
  "condition": "error_rate > 10",
  "windowMinutes": 5,
  "channels": ["email"]
}

`PUT /projects/:projectName/alerts/rules/:id`

Update an existing rule.

`DELETE /projects/:projectName/alerts/rules/:id`

Delete a rule.

`POST /projects/:projectName/alerts/rules/:id/test`

Trigger a test notification for a rule.

API Tokens

`GET /projects/:projectName/tokens`

List API tokens for a project.

`POST /projects/:projectName/tokens`

Create a new token with specific permissions.

`DELETE /projects/:projectName/tokens/:tokenId`

Revoke a token.

`POST /projects/:projectName/tokens/:tokenId/rotate`

Issue a new token value (old value immediately invalid).

WebSocket — Real-time logs

Connect to ws://localhost:3001/ws with Authorization: Bearer <token> to receive live log events as they arrive.