Copy page

Getting Started

Resource Model

This page explains how the Kordiam API is organized and how the main resources fit together.

Use this page for the technical resource model. Use the API reference for the exact field-level contract.

If you have used an earlier Kordiam API, some business terms may look familiar. Use this API's own request, response, and write contracts as the source of truth.

For the editorial meaning behind stories, tasks, publications, statuses, and planning in Kordiam, see Editorial Concepts.

Content Production

The core of Kordiam is the editorial workflow: an Element aggregate contains Tasks (work assignments) and Publications (scheduled outputs).

• An Element is the main editorial aggregate. Depending on its contents, it can represent a story, a group-based planning entry, or a task-only assignment. Story-like elements can carry event data directly on the element.
• A Task is a work assignment within an element: writing, photography, video production, and similar editorial work. A task can be assigned to a User and can contain content fields such as headline, lead, and text.
• A Publication is a scheduled or published output of an element. Every publication belongs to a Platform. It can optionally have a Category and a Type, both defined within that platform.
• A task can be linked to multiple publications, and a publication can have multiple tasks. This many-to-many link represents which tasks contribute to which outputs.

Element Aggregate

• Element is the top-level (parent) resource of the editorial model. Clients typically start from /api/v2/elements and treat the returned element body as the canonical current state.
• Read endpoints are aggregate-oriented: GET /api/v2/elements and GET /api/v2/elements/{id} return element documents with tasks, publications, and custom-field values inline.
• Task and Publication writes are nested under /api/v2/elements/{id} because both belong to one parent element.
• After creating or updating a nested task or publication, clients should treat the returned element body as the refreshed state of the parent element.

Element Content Requirement

An element must contain at least one of the following to be valid:

• Publication - at least one publication (on any platform)
• Task assigned to a registered user - a task only counts if it is assigned to a registered user (user.id is set). Tasks assigned to non-registered users (identified only by name and email) do not satisfy this requirement.
• Group - at least one group association

This rule matters for element creation and root element write flows such as POST /api/v2/elements and root element PUT or PATCH. For nested task and publication operations, rely on the exact endpoint contract in API reference instead of assuming that every nested write re-validates the same root rule. For method-level behavior such as create defaults, replacement semantics, partial updates, and deletes, see Write Semantics.

Task Assignees

Task writes accept either a registered user ID or an unregistered assignee:

• provide user.id to assign a registered user; it takes precedence over name and email.
• when id is omitted, user.email is resolved to an accessible registered user when possible.
• if the email does not resolve, the API uses or creates an unregistered assignee from name and email.

Only tasks assigned to registered users count toward the element content requirement above.

Organization & Configuration

Platforms, groups, users, and reference data form the configuration layer that the content model references.

• A Platform represents a publication channel such as a website, print edition, newsletter, mobile app, or social media account. Each platform contains its own Categories, Types, and optionally Time Slots.
• Categories organize content within a platform, such as Politics, Sports, or Culture, and support one level of nesting.
• Groups are organizational units such as editorial desks or departments and can reference a parent group.
• Users have Absences (time-off records) and Shifts (work schedule definitions). Users may be internal staff members or external contributors, depending on the organization setup. Public v2 user endpoints are read-only; absences and shift day notes have dedicated write endpoints.

Statuses

Kordiam provides three independent status systems that operate at different levels of the editorial model. Available statuses are configured per organization.

Status type	Applies to	Endpoint	Typical use
Element Status	Element	/api/v2/element-statuses	Editorial decision pipeline (pitch → publish)
Publication Status	Publication	/api/v2/publication-statuses	Per-channel production tracking
Task Status	Task	/api/v2/task-statuses	Assignment workflow (requested → approved)

• Element statuses apply to the whole element regardless of tasks or platforms. Common for decision-making (accepted/rejected) and priority flagging. Element writes use the organization's active default status when elementStatusId is omitted or null; if status selection is disabled or no active default exists, the element is assigned the special No Status value.
• Publication statuses are per publication. One element with three publications can carry three different statuses. Each platform can define which statuses are available and which default publication status product workflows may preselect. Public REST create and patch semantics for omitted or null statusId are method-specific; use the endpoint schema as the source of truth.
• Task statuses track individual assignment progress. Task-format metadata can expose different status lists for different formats. Tasks have no No Status value; omitted or null write behavior is method-specific.

Each Task Format (text, picture, video, audio, other) exposes task-format metadata such as its configured task-status list. Public v2 task-format endpoints are read-only under /api/v2/task-formats.

For the full editorial context behind statuses, see Editorial Concepts.

Custom Fields

Custom fields allow extending the data model with organization-specific attributes. There are three definition scopes, each with its own endpoint:

Scope	Definition Endpoint	Values Stored On
Element	/api/v2/custom-fields	Element
Task	/api/v2/task-custom-fields	Task
Publication	/api/v2/publication-custom-fields	Publication

The public custom-field value write model supports five types:

Type	Description
Text	Free-form text input.
Single selection	One option from a predefined list. Options can be color-coded.
Multiple selection	Multiple options from a predefined list.
Date	An additional date value beyond the publication schedule.
Number	Numeric value for quantities, scores, or other measurements.

Task custom fields can be scoped to specific task formats, and publication custom fields can be scoped to specific platforms. Some internal definition types are intentionally hidden from public definition reads and are not writable through the public API.

Custom fields are split into two layers:

• Definitions and options live on the top-level custom-field endpoints and describe which fields are available.
• Actual values travel inside the customFields arrays on element, task, and publication payloads.

For selection-type fields, the custom-field endpoints manage the reusable options. Element, task, and publication writes only send the chosen values.

For v1-to-v2 field mapping, see Custom-Field Migration.

Publication CMS Model

Publication CMS data is intentionally grouped inside the nested cms object.

• cms.articleId identifies the publication in the connected CMS.
• cms.publishedLink is a link object for the public-facing content URL.
• cms.editLink is a link object for opening the publication in the CMS editorial UI.

This keeps CMS-specific data together instead of scattering CMS fields across the top level of the publication payload.

Resources

Resource	Endpoint	Description
Element	/api/v2/elements	Core editorial aggregate
Task	/api/v2/elements/{id}/tasks	Work assignment within an element (text, photo, video)
Publication	/api/v2/elements/{id}/publications	Scheduled or published output of an element
Group	/api/v2/groups	Organizational unit (editorial desk, department)
Category	/api/v2/categories/{id} and /api/v2/platforms/{platformId}/categories	Content category within a platform
Platform	/api/v2/platforms	Publication channel (website, print edition, app)
Type	/api/v2/types/{id} and /api/v2/platforms/{platformId}/types	Content type within a platform
User	/api/v2/users	System user
Absence	/api/v2/absences	User availability exception
Shift	/api/v2/shifts	Work shift definition
Task Format	/api/v2/task-formats	Task type and format metadata
Element Status	/api/v2/element-statuses	Workflow status for elements
Task Status	/api/v2/task-statuses	Workflow status for tasks
Publication Status	/api/v2/publication-statuses	Workflow status for publications
Element Custom Field	/api/v2/custom-fields	Custom field definition scoped to elements
Task Custom Field	/api/v2/task-custom-fields	Custom field definition scoped to tasks
Publication Custom Field	/api/v2/publication-custom-fields	Custom field definition scoped to publications

Identifiers

Most resources expose a Kordiam-owned numeric id. Many configuration and scheduling resources also carry an optional externalId for integration with another system.

• Use the returned numeric id when linking resources in request bodies.
• Use /external-id/{externalId} lookup paths only where the API reference exposes them.
• External IDs are integration identifiers, not a global uniqueness guarantee across all resource families.
• Elements do not use a top-level /external-id lookup; external-system bindings are managed through /api/v2/elements/{id}/external-element/* commands.

Examples of exposed external-ID lookups include groups, platforms, categories, types, absences, shifts, and custom-field options.

Formats And Conventions

Common wire-format conventions:

• Date-only values use ISO 8601 calendar dates, for example 2026-01-15.
• Date-time values use ISO 8601 date-times such as 2026-01-15T10:30:00Z or an explicit offset.
• List query date filters document where both full instants and yyyy-MM-dd values are accepted.
• Task cost.currency uses an ISO-4217 currency code such as EUR.

Element-Scoped Writes

Tasks and publications are managed as nested writes under an existing element. Common examples:

Code
POST /api/v2/elements/{id}/tasks
PATCH /api/v2/elements/{id}/tasks/{taskId}
POST /api/v2/elements/{id}/publications
PATCH /api/v2/elements/{id}/publications/{publicationId}
PATCH /api/v2/elements/{id}/custom-fields
PATCH /api/v2/elements/{id}/tasks/{taskId}/custom-fields

Other element-scoped operations, such as external-system linking, publication publishing, schedule updates, and batch task done-state changes, are also exposed under the addressed element. Use the API reference for the exact endpoint set and request contracts.

The API stays aggregate-first: clients fetch whole elements rather than separate read-only task or publication collections. Other resources such as groups, categories, platforms, users, and custom-field definitions remain top-level.

Task-Publication Links

Task-publication links are explicit in the API.

• The link is publication-driven: publications declare which tasks are linked to them.
• Root element writes and standalone publication writes use different request fields for these links.

For full linking rules, examples, and localId constraints, see Task-Publication Linking.

For list filtering, sorting, and pagination patterns, see Querying Lists. For the editorial domain context behind these resources, see Editorial Concepts. For v1-to-v2 configuration mapping, see Configuration Resources Migration. For user, absence, shift, and shift-day-note migration details, see People And Scheduling Migration.