Copy page

Migrating from v1

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.

Code
https://api.kordiam.app/api/v2/elements

Authentication

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

Code
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:

Code
Authorization: Bearer eyJhbGciOi...

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

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

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.