Metricis API Reference¶

This document provides an overview of the Metricis REST API. For interactive documentation with request/response examples, visit /docs (Swagger UI) or /redoc (ReDoc) when the server is running.

Base URL¶

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

Authentication¶

Most endpoints require JWT authentication. Include the access token in the Authorization header:

Authorization: Bearer <access_token>

Obtaining Tokens¶

POST /api/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "your-password"
}

Response:

{
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "name": "User Name",
    "role": "researcher",
    "status": "active"
  },
  "tokens": {
    "access_token": "eyJ...",
    "refresh_token": "eyJ...",
    "token_type": "bearer",
    "expires_in": 1800
  }
}

Refreshing Tokens¶

POST /api/auth/refresh
Content-Type: application/json

{
  "refresh_token": "eyJ..."
}

Rate Limiting¶

Endpoint Category	Limit
General endpoints	60/minute
Authentication	10/minute

Rate limit headers are included in responses: - X-RateLimit-Limit: Maximum requests per window - X-RateLimit-Remaining: Remaining requests - X-RateLimit-Reset: Window reset time

Error Responses¶

All errors follow a consistent format:

{
  "detail": "Error message describing what went wrong"
}

HTTP Status Codes¶

Code	Description
200	Success
201	Created
204	No Content (successful deletion)
400	Bad Request - validation error
401	Unauthorized - invalid/missing token
403	Forbidden - insufficient permissions
404	Not Found
413	Request Entity Too Large
429	Too Many Requests - rate limited
500	Internal Server Error

API Endpoints¶

Health¶

Method	Endpoint	Description
GET	`/api/health`	Basic health check
GET	`/api/health/detailed`	Detailed health with dependencies

Authentication¶

Method	Endpoint	Description
POST	`/api/auth/login`	Authenticate and get tokens
POST	`/api/auth/register`	Register new user (admin only)
POST	`/api/auth/refresh`	Refresh access token
GET	`/api/auth/me`	Get current user profile
POST	`/api/auth/logout`	Invalidate refresh token

Studies¶

Method	Endpoint	Description
GET	`/api/studies`	List all studies
POST	`/api/studies`	Create new study
GET	`/api/studies/{id}`	Get study details
PATCH	`/api/studies/{id}`	Update study
DELETE	`/api/studies/{id}`	Delete study (admin only)

Participants¶

Method	Endpoint	Description
GET	`/api/studies/{study_id}/participants`	List participants
POST	`/api/studies/{study_id}/participants`	Enroll participant
GET	`/api/participants/{id}`	Get participant details
PATCH	`/api/participants/{id}`	Update participant
DELETE	`/api/participants/{id}`	Remove participant
POST	`/api/studies/{study_id}/participants/import/csv`	Bulk import from CSV
POST	`/api/studies/{study_id}/participants/import/excel`	Bulk import from Excel
GET	`/api/studies/{study_id}/participants/import/template`	Download CSV template

Sessions¶

Method	Endpoint	Description
POST	`/api/session/start`	Start assessment session
POST	`/api/session/end`	End session
GET	`/api/sessions`	List sessions (admin)
GET	`/api/sessions/{id}`	Get session details

Data Submission¶

Method	Endpoint	Description
POST	`/api/submit`	Submit assessment data

Batteries¶

Method	Endpoint	Description
GET	`/api/batteries`	List batteries
POST	`/api/batteries`	Create battery
GET	`/api/batteries/{id}`	Get battery details
PATCH	`/api/batteries/{id}`	Update battery
DELETE	`/api/batteries/{id}`	Delete battery
GET	`/api/batteries/{id}/compile`	Get compiled battery for client
POST	`/api/batteries/{id}/modules`	Add module to battery
PUT	`/api/batteries/{id}/modules`	Reorder modules

Offline Sync¶

Method	Endpoint	Description
GET	`/api/sync/status`	Check sync connectivity
POST	`/api/sync/sessions`	Sync offline session
POST	`/api/sync/responses`	Sync offline response
POST	`/api/sync/bulk`	Bulk sync multiple items
POST	`/api/sync/check-conflicts`	Check for sync conflicts

Schedules¶

Method	Endpoint	Description
GET	`/api/schedules/windows`	List visit windows
POST	`/api/schedules/windows`	Create visit window
GET	`/api/schedules/visits`	List scheduled visits
POST	`/api/schedules/visits`	Schedule a visit

Reports & Exports¶

Method	Endpoint	Description
GET	`/api/reports/summary`	Get summary statistics
GET	`/api/reports/studies/{study_id}/summary`	Get study summary
GET	`/api/reports/studies/{study_id}/enrollment`	Get enrollment report
GET	`/api/reports/studies/{study_id}/completion`	Get completion report
GET	`/api/reports/studies/{study_id}/modules`	Get module performance
GET	`/api/reports/studies/{study_id}/sites`	Get site comparison
GET	`/api/reports/studies/{study_id}/visits`	Get visit compliance
GET	`/api/reports/participants/{participant_id}`	Get participant summary
POST	`/api/exports/csv`	Export data to CSV
POST	`/api/exports/json`	Export data to JSON

PDF Reports¶

Method	Endpoint	Description
GET	`/api/reports/studies/{study_id}/pdf/summary`	Download study summary PDF
GET	`/api/reports/studies/{study_id}/participants/{id}/pdf`	Download participant PDF
GET	`/api/reports/studies/{study_id}/sessions/{id}/pdf`	Download session scores PDF

Study Templates¶

Method	Endpoint	Description
GET	`/api/templates`	List all templates
GET	`/api/templates/categories`	List template categories
GET	`/api/templates/{template_id}`	Get template details
GET	`/api/templates/{template_id}/preview`	Preview template entities
POST	`/api/templates/{template_id}/apply`	Create study from template

REDCap Integration¶

Method	Endpoint	Description
GET	`/api/redcap/config/{study_id}`	Get REDCap config
PATCH	`/api/redcap/config/{study_id}`	Update REDCap config
POST	`/api/redcap/sync/{study_id}`	Trigger REDCap sync
GET	`/api/redcap/status/{study_id}`	Get sync status

Request/Response Examples¶

Starting an Assessment Session¶

POST /api/session/start
Content-Type: application/json

{
  "site_id": "demo",
  "participant_id": "P001",
  "language": "en"
}

Response:

{
  "sessionId": "abc123-def456-...",
  "expiresAt": "2024-01-15T12:00:00Z"
}

Submitting Assessment Data¶

POST /api/submit
Content-Type: application/json
X-Session-ID: abc123-def456-...

{
  "session_id": "abc123-def456-...",
  "task_summaries": {
    "simple_rt": {
      "mean_rt": 325.5,
      "median_rt": 310.0,
      "accuracy": 0.95,
      "total_trials": 20
    }
  },
  "raw_trials": [
    {
      "task": "simple_rt",
      "trial_index": 0,
      "rt": 342,
      "correct": true,
      "timestamp": "2024-01-15T10:30:00Z"
    }
  ]
}

Syncing Offline Data with Conflict Resolution¶

POST /api/sync/check-conflicts
Content-Type: application/json
Authorization: Bearer eyJ...

{
  "sessions": [
    {
      "id": "local-uuid-123",
      "participantId": "P001",
      "studyId": "study-uuid",
      "status": "completed",
      "startedAt": "2024-01-15T10:00:00Z",
      "completedAt": "2024-01-15T10:30:00Z",
      "syncStatus": "pending",
      "syncAttempts": 0
    }
  ],
  "responses": []
}

Response (with conflict):

{
  "has_conflicts": true,
  "session_conflicts": [
    {
      "conflict_type": "duplicate_session",
      "local_id": "local-uuid-123",
      "server_id": "server-uuid-456",
      "resolution": "server_wins",
      "message": "Duplicate session already synced."
    }
  ],
  "response_conflicts": []
}

Importing Participants from CSV¶

POST /api/studies/{study_id}/participants/import/csv?skip_duplicates=true&create_missing_sites=false
Content-Type: multipart/form-data
Authorization: Bearer eyJ...

file: <participant_data.csv>

CSV Format:

participant_code,external_id,site_code,preferred_language
P001,EXT-001,SITE_A,en
P002,EXT-002,SITE_B,fr

Response:

{
  "success": true,
  "total_rows": 2,
  "imported_count": 2,
  "skipped_count": 0,
  "error_count": 0,
  "errors": [],
  "imported_participants": [
    {"row": 2, "participant_code": "P001", "external_id": "EXT-001", "site_code": "SITE_A"},
    {"row": 3, "participant_code": "P002", "external_id": "EXT-002", "site_code": "SITE_B"}
  ],
  "skipped_participants": []
}

Creating a Study from Template¶

POST /api/templates/ms_assessment/apply?study_code=MS2024&study_name=MS%20Cognition%20Study
Authorization: Bearer eyJ...

Response:

{
  "study_id": "550e8400-e29b-41d4-a716-446655440000",
  "study_code": "MS2024",
  "study_name": "MS Cognition Study",
  "message": "Study created from template 'MS Assessment Battery'",
  "batteries_created": 2,
  "visit_windows_created": 3
}

Downloading PDF Reports¶

GET /api/reports/studies/{study_id}/pdf/summary?page_size=letter
Authorization: Bearer eyJ...

Response: Binary PDF file with Content-Disposition: attachment; filename="STUDY001_summary_report.pdf"

Pagination¶

List endpoints support pagination with skip and limit parameters:

GET /api/studies?skip=0&limit=10

Responses include total count:

{
  "items": [...],
  "total": 42
}

Filtering¶

Many list endpoints support filtering:

GET /api/studies?status=active
GET /api/participants?status=enrolled&search=john
GET /api/batteries?study_id=uuid

Correlation IDs¶

All requests are assigned correlation IDs for tracing:

Response headers: - X-Correlation-ID: Unique request chain identifier - X-Request-ID: Unique request identifier

Include X-Correlation-ID in requests to chain related calls.

Multi-Tenancy¶

Metricis supports multi-tenant data isolation at the study level. Each study's data (participants, sessions, batteries, etc.) is isolated from other studies.

Study Context¶

Most endpoints operate within a study context. Provide the study context using:

Path parameter (preferred):

GET /api/studies/{study_id}/participants

X-Study-ID header:

GET /api/participants
X-Study-ID: 550e8400-e29b-41d4-a716-446655440000

Query parameter:

GET /api/participants?study_id=550e8400-e29b-41d4-a716-446655440000

Site-Level Access¶

Within a study, data can be further scoped to sites for multi-center studies:

GET /api/participants
X-Study-ID: {study_id}
X-Site-ID: {site_id}

Data Isolation¶

Participants are scoped to studies
Sessions are scoped through their participant
Batteries and consent forms are scoped to studies
Cross-study data access is prevented at the API level

Admin Access¶

Users with admin role can access data across all studies. Regular researcher users only see data from studies they are assigned to.

Performance Metrics¶

Performance metrics are available for monitoring API health:

Method	Endpoint	Auth	Description
GET	`/api/metrics/health`	None	Basic health metrics
GET	`/api/metrics/summary`	Researcher+	Summary statistics
GET	`/api/metrics/endpoints`	Researcher+	Per-endpoint metrics
GET	`/api/metrics`	Admin	Full metrics data
POST	`/api/metrics/reset`	Admin	Reset all metrics

Example response from /api/metrics/summary:

{
  "uptime_seconds": 3600,
  "start_time": "2024-01-15T10:00:00Z",
  "total_requests": 1500,
  "total_errors": 12,
  "error_rate": 0.008,
  "endpoints_count": 45
}