Skip to content

REST API

The Metricis REST API provides endpoints for all portal and client functionality.

Base URL

Development: http://localhost:8000/api
Production:  https://api.metricis.app/api

Authentication

Most endpoints require authentication. See Authentication for details.

Response Format

Success Response

{
  "data": {
    // Response data
  }
}

Error Response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": {
      "field": "email",
      "reason": "Invalid email format"
    }
  }
}

Status Codes

Code Meaning
200 Success
201 Created
204 No Content
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
409 Conflict
422 Validation Error
429 Rate Limit Exceeded
500 Internal Server Error

Rate Limiting

Global rate limit: 60 requests/minute

Auth endpoints: 10 requests/minute

Rate limit headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1706112000

Pagination

List endpoints support pagination:

Request:

GET /api/participants?page=2&per_page=20

Response:

{
  "data": [...],
  "pagination": {
    "page": 2,
    "per_page": 20,
    "total": 150,
    "total_pages": 8,
    "has_next": true,
    "has_prev": true
  }
}

Filtering

Filter list endpoints with query parameters:

GET /api/participants?study_id=1&status=enrolled
GET /api/sessions?start_date=2026-01-01&end_date=2026-01-31

Sorting

Sort results with sort and order parameters:

GET /api/participants?sort=created_at&order=desc
GET /api/sessions?sort=participant_id&order=asc

Field Selection

Request specific fields with fields parameter:

GET /api/participants?fields=id,email,status

CORS

Allowed origins configured in server environment:

ALLOWED_ORIGINS=http://localhost:5173,http://localhost:3000,http://localhost:3001

Request IDs

All requests include correlation IDs for tracing:

X-Correlation-ID: abc123def456
X-Request-ID: req_xyz789

Webhooks

Configure webhooks for events:

{
  "url": "https://your-server.com/webhook",
  "events": ["session.completed", "participant.enrolled"],
  "secret": "webhook-secret-key"
}

Webhook payload:

{
  "event": "session.completed",
  "timestamp": "2026-01-24T12:34:56Z",
  "data": {
    "session_id": "sess_123",
    "participant_id": "P001"
  },
  "signature": "sha256=..."
}

API Versioning

Current version: v1

Version specified in URL:

/api/v1/participants

(Currently v1 is implied - explicit versioning will be added in future)

SDK Libraries

Python

from metricis import MetricisClient

client = MetricisClient(
    base_url="https://api.metricis.app/api",
    api_token="your-token"
)

# Get participants
participants = client.participants.list(study_id=1)

# Create session
session = client.sessions.create(
    participant_id="P001",
    battery_id="battery_1"
)

TypeScript/JavaScript

import { MetricisClient } from '@metricis/sdk';

const client = new MetricisClient({
  baseUrl: 'https://api.metricis.app/api',
  apiToken: 'your-token',
});

// Get participants
const participants = await client.participants.list({ studyId: 1 });

// Create session
const session = await client.sessions.create({
  participantId: 'P001',
  batteryId: 'battery_1',
});

OpenAPI Specification

Interactive API documentation available at:

GET /docs         # Swagger UI
GET /redoc        # ReDoc
GET /openapi.json # OpenAPI spec

Next Steps