Migrating from v1
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. 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
- Start with Breaking Changes to identify areas that can require client code changes.
- Review Contract Changes for method, endpoint, pagination, filtering, and authentication patterns.
- Review JSON Model Changes before mapping JSON payloads.
- Review Error Contract Changes before updating retry, validation, and support workflows.
- Use the Migration Checklist to track implementation work.
- For each resource, validate against the API reference, the relevant guide page, and published resource-specific notes such as 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, andDELETEhave documented method semantics- most list responses use a shared pagination shape with offset and cursor modes;
GET /api/v2/elementsis cursor-only - scalar reference fields use explicit names such as
platformId,categoryId, andstatusId - 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:
For any area not covered by a dedicated migration page, use the API reference and the existing guide pages for that area.
Useful starting points: