Merge dev into production release without education
Deploy / deploy-dev (push) Skipped
Deploy / deploy-prod (push) Successful in 3m58s

This commit is contained in:
Corey Blais committed 2026-10-05 18:18:10 -04:00
commit fc541f024d
50 files changed
+2986 -458

No files matched your search

+46 -1
View File
@@ -1,5 +1,30 @@
# FlockPal API Reference
## Customer integration reference
The interactive customer API reference is available at **`/api/docs/`** on your
FlockPal instance (locally, `http://localhost:5000/api/docs/`). Download the
OpenAPI 3.0 specification at **`/api/openapi.json`**. There is also a link in
Settings → Integration tokens.
Create an integration token in Settings, then paste it into Swagger's **Authorize**
dialog without the `Bearer` prefix. Use `read_only` for reading or `read_write`
for changes. Tokens apply to their originating workspace and the creator's
current membership permissions. Swagger's **Try it out** makes real API requests.
The customer reference covers integration-token endpoints only. The broader
application reference below also includes browser-session and administrative APIs.
### Maintaining the interactive reference
- Request validators live in `backend/src/schemas.ts` and are shared with route handlers.
- Customer operations are explicitly registered in `backend/src/docs/openapi.ts`.
- Response models live in `backend/src/docs/responses.ts`; update them when serialized responses change.
- `backend/src/docs/openapi.test.ts` validates OpenAPI, compares customer coverage against actual route middleware, and checks locally served Swagger assets and security headers.
- Run `npm run build` and `npm test` in `backend` after changes.
- The Zod-to-OpenAPI dependency is pinned to the Zod 3-compatible release; upgrade both together.
This document describes the HTTP API currently implemented in `backend/src/app.ts`.
## Base URLs
@@ -966,7 +991,7 @@ Possible errors:
#### `DELETE /api/birds/:birdId`
Requires auth with write access and role `owner`, `assistant`, or `caregiver`. Deletes a bird.
Requires auth with write access and role `owner`, `assistant`, or `caregiver`. Removes the bird from its current flock without deleting its profile, photo, or care history. Bird-specific notes stay with the bird. Public sharing is disabled and pending transfers are revoked. Workspace audit logs and flock-wide notes remain in the source flock.
Response `204` with no body.
@@ -974,6 +999,22 @@ Possible errors:
- `404` if the bird does not exist in the active workspace
#### `GET /api/birds/unassigned-match?tagId=…`
Requires auth and role `owner`, `assistant`, or `caregiver`. Returns `{ "available": true }` only for an unassigned, non-memorialized bird whose band ID matches exactly after trimming and ignoring letter case. No profile, history, or former-flock details are disclosed. Blank/unknown IDs return `400`; partial IDs do not match.
#### `POST /api/birds/claim`
Requires auth with write access and role `owner`, `assistant`, or `caregiver`.
```json
{ "tagId": "BAND-123", "confirmHistory": true }
```
Returns `200` with `{ "bird": { ... }, "historyImported": true }`. Adds the existing unassigned bird to the current flock using its saved profile and history. The bird's ID and photo are preserved; bird-specific notes follow it. Public sharing remains disabled until explicitly enabled. Competing requests are serialized so only one flock can claim a bird.
Returns `400` without explicit history confirmation, or `409` if no matching unassigned bird remains. Creating a new profile via `POST /api/birds` with an unassigned bird's band ID returns `409` with code `bird_history_available` instead of duplicating or overwriting its profile.
### Weights
#### `GET /api/birds/:birdId/weights`
@@ -1299,3 +1340,7 @@ curl -X POST http://localhost:5000/api/auth/magic-link/request \
curl http://localhost:5000/api/auth/session \
-H 'Authorization: Bearer YOUR_SESSION_TOKEN'
```
### Behavior Journal
Behavior types and occurrences are available under `/birds/{birdId}/behavior-types` and `/birds/{birdId}/behaviors`. The interactive reference documents request/response schemas and permissions. See [Behavior Journal](BEHAVIOR_JOURNAL.md) for timestamp semantics, flock scoping, and isolated workflow tests.