Interface
Interfaces
Inbound and outbound contracts for Interface
Authentication
- All endpoints require
X-API-KeyexceptGET /api/v1/healthand docs assets. - Keys are loaded from Secret Manager (
INTERFACE_API_KEY) at startup. - Missing or invalid keys return
401 Unauthorized.
Base paths
- v1:
/api/v1 - v2:
/api/v2
Endpoint catalog
Most endpoints are POST /search with JSON filters and pagination (limit, offset).
Deprecated routes are marked in the table.
| Version | Resource | Operations | Notes |
|---|---|---|---|
| v1 | /health | GET | Health check (no auth) |
| v1 | /instances | POST /search | Read-only |
| v1 | /organizations | POST /search | Read-only |
| v1 | /clinics | POST /search | Read-only |
| v1 | /households | POST /search | Read-only |
| v1 | /contacts | POST /search | Read-only |
| v1 | /patients | POST /search, POST /sync | sync provides best-match lookup |
| v1 | /team-members | POST /search | Read-only |
| v1 | /appointments | POST /search | Deprecated (use v2) |
| v1 | /invoice-lines | POST /search, POST /count | Deprecated (use v2 invoices) |
| v1 | /invoices | POST /search, POST /count | Deprecated (use v2) |
| v1 | /migration-member | POST /search | Read-only |
| v1 | /reports | POST /fiscal | Read-only |
| v1 | /products | POST /search | Read-only |
| v1 | /appointment-types | POST /search, POST /update | update writes is_wellness |
| v1 | /appointment-statuses | POST /search, POST /update | update writes status |
| v2 | /appointments | POST /search, POST /count | Preferred for appointments |
| v2 | /invoices | POST /search | Preferred for invoices |
Response envelopes
- v1 endpoints generally return lists of models.
- v2 endpoints return a
Responseenvelope with metadata and data payloads.
Outbound dependencies
- Cloud Spanner for all reads and limited writes.
- Secret Manager for API keys and optional Sentry DSN.
Last updated on