# Contract Changes

v2 is designed as a resource-oriented REST API. This page summarizes the global contract patterns
that v1 clients should account for before mapping individual endpoints.

## Versioned Paths

All public REST endpoints use the `/api/v2` prefix.

```text
https://api.kordiam.app/api/v2/elements
```

:::caution{title="Do not infer paths from v1"}

Do not infer v2 endpoint names from v1 URLs. Use the [API reference](/api) for the exact path
set.

:::

## Authentication

v2 uses client credentials for token issuance and bearer tokens for protected endpoints.

```bash
curl -X POST https://api.kordiam.app/api/v2/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your-client-id",
    "client_secret": "your-client-secret",
    "grant_type": "client_credentials"
  }'
```

Then send the access token on API requests:

```text
Authorization: Bearer eyJhbGciOi...
```

See [Authentication](/docs/getting-started/authentication) for the token lifecycle.

## Method Semantics

v2 documents method behavior explicitly:

| Method | v2 use |
|--------|--------|
| `GET` | Read one resource, read a collection, or read a subresource. |
| `POST` | Create a resource or execute a command-style operation. |
| `PUT` | Replace the addressed writable resource or subresource. |
| `PATCH` | Partially update the addressed writable resource using presence-aware fields. |
| `DELETE` | Remove the addressed resource or subresource. |

:::caution{title="Omitted fields differ across methods"}

Do not assume that omitted fields behave the same across `PUT`, `PATCH`, and `POST`.
Field-level descriptions in `/api` win when a field has non-obvious omission or `null` behavior.

:::

See [Write Semantics](/docs/guides/api-conventions/write-semantics) for the method-level rules.

## List Endpoints

Most v2 list endpoints use a shared pagination model:

- no pagination parameters returns the first page and can include both offset metadata and a
  cursor token
- `page` and `size` use offset-based pagination
- `cursor` and `size` use forward-only cursor pagination
- `page` and `cursor` are mutually exclusive

`GET /api/v2/elements` is cursor-only; follow the API reference for endpoint-specific pagination
parameters.

See [Querying Lists](/docs/guides/api-conventions/querying-lists).

## Resource-Oriented Workflows

Some operations that used to be implicit in client workflows are explicit resource or subresource
operations in v2. Examples already documented in public guides include:

- publication schedules are managed through a schedule subresource
- publishing a publication uses a dedicated publish operation
- task-publication links are declared through publication-side link fields
- root element writes can create or mutate nested tasks and publications in one aggregate payload

Use the relevant guide page for workflow context, then use `/api` for the exact schema.