# Changelog

import { ChangeTag } from "../../../components/change-tag";
import { Release, Change } from "../../../components/release";

All notable changes to the Kordiam API are documented on this page, newest first. Entries affect API
**v2** unless tagged otherwise. For how versioning works, see the
[Versioning](/docs/guides/api-conventions/versioning) guide.

Entries are grouped as:

- <ChangeTag>Added</ChangeTag> - new endpoints, fields, or capabilities
- <ChangeTag>Changed</ChangeTag> - modifications to existing behavior
- <ChangeTag>Fixed</ChangeTag> - bug fixes to existing behavior
- <ChangeTag>Deprecated</ChangeTag> - features marked for future removal
- <ChangeTag>Removed</ChangeTag> - features that are no longer available
- <ChangeTag>Security</ChangeTag> - security-relevant fixes or changes

---

{/* HOW TO ADD CHANGES — full guidance: CONTRIBUTING.md → "Changelog / Release Notes".

    This page is customer-facing. Write entries for external integrators: describe the
    observable change, never internal details (no Jira IDs, internal names, ticket links).

    Do NOT hand-stamp a version or date. Add your <Change> blocks under the
    "Unreleased" entry below as you merge work. At release time, a script stamps
    the version (from the Maven <revision>) and date, and opens a fresh
    Unreleased entry:

      npm run changelog:release -- --label "Optional title" --commit

    The Unreleased entry is shown only in local/dev builds — never on the published
    site until it is cut.

    Authoring rules:
    - One <Change> block per type; type is one of Added, Changed, Fixed, Deprecated, Removed, Security.
    - Keep entries short; link out for depth.
    - Use note="..." on <Change> for a qualifier (e.g. note="compared with v1").
    - api (optional, on <Release>): set ONLY when an entry affects a different API version
      (e.g. a future "v3"). Omit it while everything is v2 — the page intro states the default.
    - Keep blank lines around the bullet list inside <Change> so it parses as Markdown. */}

<Release unreleased>

{/* Add <Change> blocks here as you merge work. Example:

<Change type="Added">

- **Item** - one line; link out for depth.

</Change> */}

</Release>

<Release version="1.26.26" date="2026-06-24" label="Initial Release">

The first public release of the Kordiam v2 REST API. v2 keeps Kordiam's editorial concepts and
rules, but makes the public contract explicit and consistent across resources.

:::info{title="Where to start"}

- New to the API? Begin with [Getting Started](/docs/getting-started/index).
- Moving from v1? See [Migrating from v1](/docs/migration-from-v1/index) and
  [Breaking Changes](/docs/migration-from-v1/breaking-changes).

:::

<Change type="Added">

- **Elements** - create, read, and update editorial stories and events
  ([Resource Model](/docs/getting-started/data-model))
- **Element Tasks** - manage work assignments within an element
- **Element Publications** - manage publications, including
  [scheduling](/docs/guides/editorial-workflows/publication-scheduling) and
  [publishing](/docs/guides/editorial-workflows/publishing-publications)
- **Task-publication linking** - explicit links between tasks and publications
  ([guide](/docs/guides/editorial-workflows/task-publication-linking))
- **Custom Fields** - extensible fields on elements, tasks, and publications
  ([guide](/docs/guides/resource-guides/custom-fields))
- **Configuration resources** - Groups, Platforms, Categories, and Types, plus read-only Statuses
  and Task Formats ([guide](/docs/guides/resource-guides/configuration-resources))
- **People and scheduling** - Users, Absences, and Shifts
  ([guide](/docs/guides/resource-guides/people-and-scheduling))
- **OAuth2 authentication** - client-credentials token issuance with bearer tokens
  ([guide](/docs/getting-started/authentication))
- **Pagination** - shared list response with offset and cursor modes where the endpoint exposes both; the element list is cursor-only
  ([Querying Lists](/docs/guides/api-conventions/querying-lists))
- **OpenAPI 3.1 specification** and this documentation site

</Change>

<Change type="Changed" note="compared with v1">

The public contract is reshaped in v2. The differences that most often affect integrators:

- endpoints are versioned under `/api/v2`
- errors use [RFC 9457 Problem Details](/docs/guides/api-conventions/error-handling)
- `POST`, `PUT`, `PATCH`, and `DELETE` follow documented
  [write semantics](/docs/guides/api-conventions/write-semantics)
- list endpoints share a [pagination shape](/docs/guides/api-conventions/querying-lists) with offset
  and cursor modes where exposed; the element list is cursor-only
- scalar references use explicit field names such as `platformId`, `categoryId`, and `statusId`
- task-publication links use explicit `assignedTaskRefs` or `assignedTaskIds` instead of v1
  [positional assignment arrays](/docs/migration-from-v1/task-publication-linking)

For the complete, resource-by-resource list, see
[Breaking Changes](/docs/migration-from-v1/breaking-changes).

</Change>

</Release>