API Endpoints

Complete reference of all Metricis API endpoints.

Health

Check API Health

GET /api/health

Response:

{
  "status": "healthy",
  "version": "0.1.0",
  "timestamp": "2026-01-24T12:34:56Z"
}

Authentication

See Authentication for detailed authentication documentation.

Login

POST /api/auth/login

Request Magic Link

POST /api/auth/magic-link

Get Current User

GET /api/auth/me
Authorization: Bearer <token>

Studies

List Studies

GET /api/studies
Authorization: Bearer <token>

Query Parameters: - status - Filter by status (active, paused, completed) - page - Page number (default: 1) - per_page - Results per page (default: 20)

Get Study

GET /api/studies/{study_id}
Authorization: Bearer <token>

Create Study

POST /api/studies
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Neurocognitive Study",
  "code": "NEUROCOG-01",
  "description": "Study description",
  "pi_name": "Dr. Smith",
  "pi_email": "smith@hospital.org",
  "start_date": "2026-01-01",
  "end_date": "2026-12-31"
}

Update Study

PATCH /api/studies/{study_id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "status": "paused"
}

Delete Study

DELETE /api/studies/{study_id}
Authorization: Bearer <token>

Participants

List Participants

GET /api/studies/{study_id}/participants
Authorization: Bearer <token>

Query Parameters: - status - Filter by status (enrolled, withdrawn, completed) - search - Search by participant ID or email - page - Page number - per_page - Results per page

Get Participant

GET /api/participants/{participant_id}
Authorization: Bearer <token>

Create Participant

POST /api/studies/{study_id}/participants
Authorization: Bearer <token>
Content-Type: application/json

{
  "participant_id": "P001",
  "email": "participant@example.com",
  "phone": "+1234567890",
  "enrollment_date": "2026-01-24",
  "actor": "patient",
  "language": "en"
}

Import Participants (CSV)

POST /api/studies/{study_id}/participants/import/csv
Authorization: Bearer <token>
Content-Type: multipart/form-data

file=participants.csv

Import Participants (Excel)

POST /api/studies/{study_id}/participants/import/excel
Authorization: Bearer <token>
Content-Type: multipart/form-data

file=participants.xlsx

Download Import Template

GET /api/studies/{study_id}/participants/import/template
Authorization: Bearer <token>

Batteries

List Batteries

GET /api/batteries
Authorization: Bearer <token>

Get Battery

GET /api/batteries/{battery_id}
Authorization: Bearer <token>

Create Battery

POST /api/batteries
Authorization: Bearer <token>
Content-Type: application/json

{
  "study_id": 1,
  "name": "Baseline Battery",
  "description": "Initial cognitive assessment",
  "estimated_minutes": 30,
  "tasks": [
    {
      "task_name": "simple_rt",
      "config": { "trials": 20 }
    },
    {
      "task_name": "cpt",
      "config": { "trials": 100 }
    }
  ]
}

Sessions

Start Session

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

{
  "participant_id": "P001",
  "battery_id": "battery_1"
}

Response:

{
  "session_id": "sess_abc123",
  "participant_id": "P001",
  "battery_id": "battery_1",
  "start_time": "2026-01-24T12:34:56Z"
}

End Session

POST /api/session/end
X-Session-ID: sess_abc123
Content-Type: application/json

{
  "session_id": "sess_abc123"
}

Submit Session Data

POST /api/submit
X-Session-ID: sess_abc123
Content-Type: application/json

{
  "session_id": "sess_abc123",
  "task_summaries": {
    "simple_rt": {
      "mean_rt": 342.5,
      "sd_rt": 45.2,
      "accuracy": 0.95
    }
  },
  "trials": [
    {
      "task": "simple_rt",
      "rt": 350,
      "correct": true,
      "timestamp": "2026-01-24T12:35:00Z"
    }
  ]
}

Schedules

List Visits

GET /api/studies/{study_id}/visits
Authorization: Bearer <token>

Create Visit

POST /api/schedules/windows
Authorization: Bearer <token>
Content-Type: application/json

{
  "study_id": 1,
  "visit_name": "Baseline",
  "visit_number": 1,
  "window_start_days": 0,
  "window_end_days": 7,
  "battery_id": "battery_1"
}

REDCap

Get REDCap Config

GET /api/redcap/config/{study_id}
Authorization: Bearer <token>

Update REDCap Config

PATCH /api/redcap/config/{study_id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "site_id": "hospital_a",
  "event_name": "baseline_arm_1",
  "field_mappings": {
    "simple_rt_mean": "cognitive_rt_mean"
  },
  "sync_enabled": true
}

Import Participants from REDCap

POST /api/redcap/import-participants/{study_id}
Authorization: Bearer <token>

Export Sessions to REDCap

POST /api/redcap/export-sessions
Authorization: Bearer <token>
Content-Type: application/json

{
  "session_ids": ["sess_123", "sess_456"]
}

Reports

Generate Study Summary PDF

GET /api/reports/studies/{study_id}/pdf/summary
Authorization: Bearer <token>

Returns PDF file.

Generate Participant Report PDF

GET /api/reports/studies/{study_id}/participants/{participant_id}/pdf
Authorization: Bearer <token>

Returns PDF file.

Generate Session Scores PDF

GET /api/reports/studies/{study_id}/sessions/{session_id}/pdf
Authorization: Bearer <token>

Returns PDF file.

Export

Export Study Data

POST /api/exports
Authorization: Bearer <token>
Content-Type: application/json

{
  "study_id": 1,
  "format": "csv",
  "include_trials": false,
  "date_range": {
    "start": "2026-01-01",
    "end": "2026-01-31"
  }
}

Supported formats: - csv - Comma-separated values - excel - Excel workbook - json - JSON export - spss - SPSS format - sas - SAS format

Templates

List Templates

GET /api/templates
Authorization: Bearer <token>

Get Template

GET /api/templates/{template_id}
Authorization: Bearer <token>

Preview Template

GET /api/templates/{template_id}/preview
Authorization: Bearer <token>

Apply Template

POST /api/templates/{template_id}/apply
Authorization: Bearer <token>
Content-Type: application/json

{
  "study_id": 1
}

Consent

List Consent Forms

GET /api/consent/forms
Authorization: Bearer <token>

Create Consent Form

POST /api/consent/forms
Authorization: Bearer <token>
Content-Type: application/json

{
  "study_id": 1,
  "version": "1.0",
  "title": "Study Consent Form",
  "content": "<html>...</html>",
  "effective_date": "2026-01-01"
}

Sign Consent

POST /api/consent/sign
Authorization: Bearer <token>
Content-Type: application/json

{
  "consent_form_id": 1,
  "participant_id": "P001",
  "signature": "data:image/png;base64,..."
}

Notifications

Send Notification

POST /api/notifications/send
Authorization: Bearer <token>
Content-Type: application/json

{
  "participant_id": "P001",
  "channel": "email",
  "template_id": 1,
  "variables": {
    "visit_name": "Baseline",
    "visit_date": "2026-01-30"
  }
}

Next Steps

• REST API Overview - API basics
• Authentication - Authentication methods
• Server Architecture - Technical details