Skip to content

REST API Reference

imperfect-api exposes the user-facing API contract for authentication, onboarding, Home, notifications, public routes, channel webhooks, and health provider connection orchestration.

OpenAPI Specification

The generated OpenAPI specification is checked in at openapi.json. It is produced from app.main:app and updated automatically by GitHub Actions when API or schema code changes on main.

View the Redoc API reference for a browsable version of the same contract.

Regenerate the checked-in spec locally after API/schema changes:

set -a
source env.template
set +a
LOGFIRE_IGNORE_NO_CONFIG=1 uv run python scripts/generate_openapi.py

Using with API Tools

Import the OpenAPI spec into your API client:

  • Insomnia: File -> Import -> From URL -> https://raw.githubusercontent.com/imperfect-co/imperfect-api/main/docs/openapi.json
  • Postman: Import -> Link -> paste the raw GitHub URL above.
  • Swagger UI: Open https://editor.swagger.io/ and paste the spec contents.
  • Redoc: npx @redocly/cli preview-docs docs/openapi.json

Route Families

Family Representative paths Purpose
Root / Basic service metadata.
Users and auth /users/*, /users_profiles/{profile_id}, /notifications/*, /account User records, Firebase-owned identity, notification tokens, profiles, and account deletion.
Health providers /health-providers/*, /onboarding/{provider}/insights Provider connect/callback/disconnect orchestration. Alice owns OAuth credentials and token lifecycle.
Terra /session, /session/sdk-token Terra connection/session setup for wearable onboarding.
Home and boards /user_states/* Home state, streaming board generation, activity details, and feedback handling.
Events /events/*, /user_events/* Event discovery, active-event state, translations, and history.
Onboarding /onboarding/intake, /onboarding/race-recommendations* Intake, race recommendation, and discovery flows.
Cheshire bridge /cheshire/* Natural-language fitness questions and visualization streaming through Cheshire.
Public routes /routes/*, /route-send/garmin/* Browser route planning, route-send OAuth state, and Garmin course send flows.
Channels /whatsapp_webhooks, /heylo_webhooks, /channel_associations, /whatsapp_associations, /channels/message-references Chat bridge webhooks, link confirmation, and message reference confirmation.
Device attestation /attest/*, /auth/health-probe/* App/device attestation and health-probe auth flows.

Agent Reading Path

When changing API behavior, read in this order:

  1. AGENTS.md for the terse route map and repo conventions.
  2. The relevant module CLAUDE.md under app/resources/, app/lib/*/, or app/tasks/.
  3. The owning route module docstring and endpoint schema definitions.
  4. This page and openapi.json for the published contract.