# API Changelog

This changelog tracks externally visible API documentation and contract updates.

## Label Definitions

- `Breaking`: a change that requires client code updates.
- `Non-breaking`: additive or clarifying change with no required client migration.

## 2026-03-03

### Non-breaking

- Added live-endpoint public spec pipeline (`api_docs/openapi_public.yaml`) and switched `/docs/api/openapi.yaml` to serve the public spec.
- Added canonical quickstart flow guidance with envelope extraction (`response.group.uuid`, `response.study.id`) and sequential polling requirements.
- Added async polling guide and common mistakes guide.
- Added operation-level request/response examples for core workflow endpoints, including study completion and sparse group-question job result notes.
- Added filter behavior hardening docs, including nested DSL format and canonical value sets.
- Added endpoint-specific error scenarios and recovery guidance for recruit/find/complete/share/jobs operations.
- Added `x-workflow-step` and `x-codeSamples` metadata for canonical flow operations.
- Added workflow diagram guide and runnable Postman collection for onboarding.
- Added optional strict invalid-filter handling (`API_V1_STRICT_INVALID_FILTERS`) with `422` responses and suggestion payloads for unsupported finite categorical values on recruit/interview/append/search/find endpoints.
- Added API docs -> Claude guide cross-linking: `/docs/api` now surfaces external Claude Code hubs/use-case guides, and key OpenAPI operations include "Guides using this endpoint" references.

### Breaking

- None.

## 2026-02-28

### Non-breaking

- Added direct group questioning endpoint documentation (`POST /v1/research-groups/{group_id}/questions`).
- Added upload-first attachment flow docs (`POST /v1/media-assets`) and reuse guidance for question endpoints.
- Expanded docs hub links for direct ask workflows and attachment usage.

### Breaking

- None.