> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tallychannel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Changelog

> What changed in each version of the Tally Platform API and schema.

This changelog records breaking changes, new endpoints, and schema promotions. Each entry references the relevant decision record and schema tag.

The **API version** (`openapi.yaml` → `info.version`) tracks the REST interface. The **schema version** (`schema_version` field in the snapshot envelope) tracks the canonical attribute vocabulary inside `attributes`. These advance independently.

For a machine-readable record of every field added, moved, or removed, see `tally_ops/registries/schema_tag_registry.json`.

***

## Schema v2.0 — Attribute Groups + Evidence Provenance

**Status: pending implementation**
Decision record: `knowledge/decisions/2026_06_schema_v2_attribute_groups.md`
Schema tag: `schema-v2.0`

### What changed

**Breaking — Individual and Organization attributes restructured into grant-eligible groups.**

The flat `attributes` object is replaced by a grouped structure. This enables per-group and eventually per-attribute grant scopes without a future refactor.

Individual groups: `biographic`, `contact`, `jurisdiction`, `identifiers`, with `professional` reserved.
Organization groups: `legal`, `contact`, `jurisdiction`, `identifiers`.

Individual grouped attributes:

| Group          | Fields                                                                           |
| -------------- | -------------------------------------------------------------------------------- |
| `biographic`   | `name`, `sex`, `date_of_birth`, `place_of_birth`                                 |
| `contact`      | `email`, `phone`, `addresses.residential`, `addresses.mailing`, `addresses.work` |
| `jurisdiction` | `nationalities`, `citizenships`, `tax_residencies`                               |
| `identifiers`  | Structured identifier array                                                      |

Organization grouped attributes:

| Group          | Fields                                                                                                        |
| -------------- | ------------------------------------------------------------------------------------------------------------- |
| `legal`        | `legal_name`, `alternative_names`, `legal_form`, `legal_form_code`, `status`, `date_of_incorporation`         |
| `contact`      | `email`, `phone`, `addresses.registered_office`, `addresses.principal_place_of_business`, `addresses.mailing` |
| `jurisdiction` | `country_of_incorporation`, `region_of_incorporation`, `tax_residencies`                                      |
| `identifiers`  | Structured identifier array                                                                                   |

**Breaking — `subject_id` is now server-generated.**

For all subject types on `snapshot_version: 1`, the server generates a UUID for `subject_id`. Any caller-provided `subject_id` is overridden. The server-assigned value is returned in the 201 response.

**Non-breaking — `schema_version` added to envelope.**

All snapshots now include a `schema_version` field alongside `envelope_version`. See [Envelope and Schema Versions](/concepts/evidence#envelope-and-schema-versions).

**Non-breaking — `verification_method` added to evidence items.**

Evidence items now include a standardized `verification_method` field. See [Evidence and Attestation](/concepts/evidence).

**Non-breaking — `/attest` endpoint added; `/operator-attest` eliminated.**

A single `POST .../subjects/:subject_type/:subject_id/attest` endpoint replaces both previous routes. The `verification_method` field in the request body carries the attestation tier. Callers of the former `/operator-attest` should migrate to `/attest` with `verification_method: "document_reviewed"`.

***

## Schema v1.0 — Initial Freeze

**Released: 2026-06-10**
Decision record: `knowledge/decisions/2026_06_schema_v1_freeze.md`
Schema tag: `schema-v1.0` (commit `cc88590`)

Initial freeze of canonical attribute vocabularies for `organization` and `individual`. `entityStateEnvelopeV1Z` container structure frozen.