# Migrating from v1

import { Card, CardHeader, CardTitle, CardDescription } from "zudoku/ui/Card.js";

This section helps v1 integrations move to v2 of the Kordiam API.

The v2 API keeps Kordiam's business concepts and rules, but the public contract is more explicit:
resources are addressed through `/api/v2`, write methods have clearer semantics, list endpoints use
a common pagination shape, and errors use a consistent Problem Details response.

Use this section together with the [API reference](/api). Migration pages explain the
client-impacting patterns. The API reference remains the source of truth for exact paths, request
fields, response fields, examples, and status codes.

## Recommended Migration Path

1. Start with [Breaking Changes](/docs/migration-from-v1/breaking-changes) to identify areas that
   can require client code changes.
2. Review [Contract Changes](/docs/migration-from-v1/contract-changes) for method, endpoint,
   pagination, filtering, and authentication patterns.
3. Review [JSON Model Changes](/docs/migration-from-v1/request-response-models) before
   mapping JSON payloads.
4. Review [Error Contract Changes](/docs/migration-from-v1/errors-status-codes) before updating
   retry, validation, and support workflows.
5. Use the [Migration Checklist](/docs/migration-from-v1/checklist) to track implementation work.
6. For each resource, validate against the [API reference](/api), the relevant guide page, and
   published resource-specific notes such as [Elements](/docs/migration-from-v1/elements).

## What Changes In v2

The most important v2 integration themes are:

- public endpoints are versioned under `/api/v2`
- authentication uses OAuth2 client credentials and bearer tokens
- errors use RFC 9457 Problem Details with `application/problem+json`
- `POST`, `PUT`, `PATCH`, and `DELETE` have documented method semantics
- most list responses use a shared pagination shape with offset and cursor modes; `GET
  /api/v2/elements` is cursor-only
- scalar reference fields use explicit names such as `platformId`, `categoryId`, and `statusId`
- richer response objects can include embedded references instead of only scalar values
- task-publication linking and publication scheduling have explicit workflow contracts

## Resource-Specific Notes

Resource-specific migration pages:

<div className="grid gap-4 sm:grid-cols-2 mt-6 not-prose">
  <a href="/docs/migration-from-v1/elements" className="no-underline">
    <Card className="h-full transition-colors hover:border-primary">
      <CardHeader>
        <CardTitle>Elements</CardTitle>
        <CardDescription>Explicit root write fields, command-based external linking.</CardDescription>
      </CardHeader>
    </Card>
  </a>
  <a href="/docs/migration-from-v1/tasks" className="no-underline">
    <Card className="h-full transition-colors hover:border-primary">
      <CardHeader>
        <CardTitle>Element Tasks</CardTitle>
        <CardDescription>Required format and confirmation fields, done-state action endpoint, 204 deletes.</CardDescription>
      </CardHeader>
    </Card>
  </a>
  <a href="/docs/migration-from-v1/publications" className="no-underline">
    <Card className="h-full transition-colors hover:border-primary">
      <CardHeader>
        <CardTitle>Element Publications</CardTitle>
        <CardDescription>Dedicated schedule subresource, read-only published state, explicit task links.</CardDescription>
      </CardHeader>
    </Card>
  </a>
  <a href="/docs/migration-from-v1/task-publication-linking" className="no-underline">
    <Card className="h-full transition-colors hover:border-primary">
      <CardHeader>
        <CardTitle>Task-Publication Link Migration</CardTitle>
        <CardDescription>Explicit task refs and IDs replace positional assignments.</CardDescription>
      </CardHeader>
    </Card>
  </a>
  <a href="/docs/migration-from-v1/custom-fields" className="no-underline">
    <Card className="h-full transition-colors hover:border-primary">
      <CardHeader>
        <CardTitle>Custom-Field Migration</CardTitle>
        <CardDescription>Paginated definitions, plural option paths, selected-option IDs, named type values.</CardDescription>
      </CardHeader>
    </Card>
  </a>
  <a href="/docs/migration-from-v1/configuration-resources" className="no-underline">
    <Card className="h-full transition-colors hover:border-primary">
      <CardHeader>
        <CardTitle>Configuration Resource Migration</CardTitle>
        <CardDescription>Paginated lists, platform-scoped categories and types, deferred 202 deletes.</CardDescription>
      </CardHeader>
    </Card>
  </a>
  <a href="/docs/migration-from-v1/platform-schedule-configuration" className="no-underline">
    <Card className="h-full transition-colors hover:border-primary">
      <CardHeader>
        <CardTitle>Platform Schedule Configuration Migration</CardTitle>
        <CardDescription>Weekly-or-manual schedule modes, PATCH instruction lists, time slots.</CardDescription>
      </CardHeader>
    </Card>
  </a>
  <a href="/docs/migration-from-v1/people-and-scheduling" className="no-underline">
    <Card className="h-full transition-colors hover:border-primary">
      <CardHeader>
        <CardTitle>People And Scheduling Migration</CardTitle>
        <CardDescription>Paginated users, plural absence paths, restricted shift writes.</CardDescription>
      </CardHeader>
    </Card>
  </a>
</div>

For any area not covered by a dedicated migration page, use the [API reference](/api) and the existing
guide pages for that area.

Useful starting points:

<div className="columns-2 gap-x-8 [&_li]:break-inside-avoid">

- [Resource Model](/docs/getting-started/data-model)
- [Write Semantics](/docs/guides/api-conventions/write-semantics)
- [Publication Scheduling](/docs/guides/editorial-workflows/publication-scheduling)
- [Publishing Publications](/docs/guides/editorial-workflows/publishing-publications)
- [Task-Publication Linking](/docs/guides/editorial-workflows/task-publication-linking)
- [Custom Fields](/docs/guides/resource-guides/custom-fields)
- [Configuration Resources](/docs/guides/resource-guides/configuration-resources)
- [Platform Schedule Configuration](/docs/guides/resource-guides/platform-schedule-configuration)
- [People And Scheduling](/docs/guides/resource-guides/people-and-scheduling)
- [Error Handling](/docs/guides/api-conventions/error-handling)
- [Querying Lists](/docs/guides/api-conventions/querying-lists)

</div>