Skip to content

REST API

Metricis frontends and integrations use the FastAPI service under /api. The API is broad and evolves with the platform; the OpenAPI document generated by the running server is the authoritative endpoint and schema reference for that deployed version.

Discover the deployed contract

When API documentation is enabled for the environment:

GET /openapi.json   # machine-readable OpenAPI
GET /docs           # Swagger UI
GET /redoc          # ReDoc

Production deployments can disable these routes with ENABLE_API_DOCS=false. In that case, generate or inspect the contract in an approved non-production environment built from the same release.

Route families

Most application routes begin with /api, including researcher authentication and operations, participant-portal routes, forms, assessments, consent, schedules, quality workflows, and integrations. Some registry routers declare their complete /api/registries prefix directly but are exposed under the same public API root.

The /api/v1 surface contains scoped read, snapshot, export, token-management, and authoring routes. These capabilities have deployment gates and scope requirements; do not assume that a route appearing in source is enabled in a particular environment.

Authentication and authority

Metricis uses different credentials for different actors and purposes:

  • interactive researcher sessions use access/refresh tokens, with MFA requirements determined by account role and deployment policy;
  • participant and caregiver sessions begin with magic-link verification and use portal-specific tokens/cookies;
  • assessment submissions use their issued session or delivery credentials; and
  • programmatic /api/v1 access uses expiring, scoped tokens minted from an interactive session.

Authentication proves the caller; authorization still evaluates role, study or registry context, site, consent purpose, workflow state, and token scope. See Authentication.

Contract conventions

  • Request and response models are defined in the OpenAPI schema.
  • FastAPI validation failures generally use HTTP 422; domain conflicts and authorization failures use route-specific status codes documented in OpenAPI.
  • List pagination is endpoint-specific. Do not assume one universal page envelope.
  • Correlation and audit context may be added by middleware; preserve returned request identifiers in integration logs.
  • Writes that can be retried should use the idempotency mechanism defined by that endpoint or workflow.
  • A 2xx response from an enqueue operation may mean accepted for processing, not reconciled with an external system.

Versioning

The main /api routes evolve with the deployed Metricis release. The /api/v1 namespace provides a more deliberate contract for governed programmatic access, but callers should still pin a platform release, capture the OpenAPI document used for integration testing, and review release notes before upgrading.

Minimal inspection workflow

# Start the configured API locally, then save the exact contract you tested.
curl -fsS http://localhost:8030/openapi.json -o metricis-openapi.json

Do not copy example production base URLs or credentials from prose. Use the deployment's approved base URL and secret-management process.

Next: Authentication, API surface, and Integration overview.