# FIT-Outcomes Public API

> Stable, read-only JSON export of a psychotherapy outcome-management agency's data (users, clients, episodes, sessions, and ORS/SRS scores). Built for nightly syncs to a warehouse, BI tool, or local archive. This file documents the public API only; the internal application API is not part of the public surface.

Base URL: `https://app.fit-outcomes.com`. All endpoints are GET-only, return JSON, and live under `/api/public/v1`.

Authentication: every request must carry a Personal Access Token (PAT) as an HTTP Bearer token: `Authorization: Bearer fit7_pat_...`. A PAT inherits its owner's access to agencies and clients. Cookie and mobile-JWT sessions are NOT accepted on this surface. Tokens are created from the account's API tokens page and shown exactly once; the server stores only a SHA-256 hash.

Rate limit: 60 requests per minute per token (sliding window). Over the limit returns HTTP 429 (`application/problem+json`); wait at least 10 seconds before retrying.

Errors: RFC 7807/9457 problem details (`application/problem+json`) carrying a `correlationId` to quote to support. `401` token missing/invalid/expired/revoked; `403` insufficient access to the agency or user; `404` agency does not exist or the caller is not a member (deliberately indistinguishable so agency IDs are not leaked); `429` rate limited; `5xx` server error (retry with exponential backoff).

CORS: endpoints under `/api/public/v1/*` allow any origin (`Access-Control-Allow-Origin: *`) and do not accept credentials; the token is attached explicitly by your code, never sent automatically by the browser.

Versioning: by path segment. Breaking changes ship as `/api/public/v2/*` with a parallel v2 schema. New optional fields may be added within v1 without a version bump, so parsers must ignore unknown properties.

## Machine-readable specs

- [OpenAPI 3.1 specification](https://app.fit-outcomes.com/schema/fit-outcomes-public-v1.openapi.json): full endpoint, auth, and error contract for this API.
- [Export payload JSON Schema (Draft 2020-12)](https://app.fit-outcomes.com/schema/fit-outcomes-export-v1.json): shape of the `export.json` response body, referenced from each response's root `$schema`.

## Endpoints

- `GET /api/public/v1/agencies/{agencyId}/ping`: verify a token and its agency access. Returns the JSON string `"pong"` on success; 404 if the token's owner is not a member of `{agencyId}`. `{agencyId}` is a numeric (int64) identifier.
- `GET /api/public/v1/agencies/{agencyId}/export.json`: full export of every client in the agency (users, clients, episodes, sessions, ORS/SRS scores). Requires the token's owner to be at least Coordinator in the agency.
- `GET /api/public/v1/agencies/{agencyId}/users/{userId}/export.json`: same payload shape, scoped to the clients of a single user. Requires the token's owner to be at least Coordinator in the agency, or to be that user. `{userId}` is a UUID.

## Example

```bash
curl -H "Authorization: Bearer fit7_pat_YOUR_TOKEN" \
  "https://app.fit-outcomes.com/api/public/v1/agencies/{agencyId}/export.json"
```

## Docs

- [Human-readable API documentation](https://app.fit-outcomes.com/help/api-doc): the same API with copy-paste curl/JavaScript/Python samples.