# API Changelog

This changelog tracks externally visible API documentation and contract updates.

Related guides:
[All Guides](./index.md) |
[Quickstart](./quickstart.md) |
[Recruitment Filter Expansion](./recruitment_filter_expansion.md) |
[Filters Reference](./filters.md)

## Label Definitions

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

## 2026-05-27

### Non-breaking

- Expanded recruitment/search filters across API and MCP surfaces with
  occupation/industry metadata, health-profile filters, GLP-1 alias
  normalization, `GET /v1/filters` field discovery, and synonym-backed
  `occupation` matching.
- Added a user-facing
  [recruitment filter expansion guide](./recruitment_filter_expansion.md)
  documenting the new parameters, response fields, examples, and best-practice
  workflows.

### Breaking

- None.

## 2026-05-22

### Non-breaking

- Added Scope B Thesis Lab read behavior: `GET /v1/thesis/{id}/state` is the lightweight polling surface with ETag/`304 Not Modified`; `GET /v1/thesis/{id}?include=full` and `GET /v1/thesis/{id}/detail` preserve the full thesis detail graph.
- Added `THESIS_DETAIL_LIGHTWEIGHT_DEFAULT` rollout flag. It defaults OFF, so `GET /v1/thesis/{id}` keeps the existing full-detail response until the flag is flipped after caller migration.
- Unknown Thesis detail `include` values now return `400 invalid_include`; Scope B supports only `include=full`.

### Breaking

- None. The lightweight default is behind a disabled rollout flag.

## 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.