Editorial Concepts
This page explains the editorial domain concepts behind the Kordiam API. Understanding these concepts helps you map API resources to real Kordiam editorial workflows.
Use this page for domain context. The Resource Model page covers the technical resource model, and the API reference is the source of truth for exact contracts.
Stories and Events
In Kordiam, an Element is the top-level editorial planning item. Depending on its contents, it can represent:
- A story: an editorial piece planned for one or more publication channels
- An event: a real-world happening (press conference, sports match, election day)
- Both at the same time: a story that covers a specific event
- A group-based planning entry or task-only assignment
Story-like elements carry a description (slug), a title, notes, and optional event data such as
date, time, and location. The API resource Element maps to this top-level concept.
Tasks
A Task is a work assignment within a story. Each task represents a deliverable that someone needs to produce: an article, a photo, a video, an audio piece, or another organization-specific deliverable.
Task Formats
Every task has a format (also called task type) that determines its nature and available options. The public API exposes built-in format type codes for text, picture, video, audio, and other. Organizations can still name and configure their task formats to match local workflows.
Format metadata exposes the task statuses configured for that format. Public REST task writes
validate statusId against the statuses active for the organization. For the exact resource and
reference-data mapping, see Resource Model.
Task Lifecycle
Tasks follow a status-driven workflow. A typical progression:
Code
Task format metadata may expose different workflow stages for different formats, such as text and video. Administrators configure these per organization.
Tasks expose a done state. Public REST writes change it through the dedicated done-state operation; root task create, replace, and patch payloads do not infer done-state changes from other task fields.
Task Confirmation
Tasks support a confirmation workflow where the assignee can confirm or reject the assignment.
In API payloads, this is represented through confirmationStatusCode:
| Code | Meaning |
|---|---|
-2 | Confirmation not requested |
-1 | Rejected by assignee |
0 | Confirmation requested, awaiting response |
1 | Confirmed by assignee |
Task create and replace payloads must send confirmationStatusCode where the schema requires it.
Do not rely on user type to provide an implicit public API default.
Task Cost Tracking
Tasks can carry cost data for tracking editorial assignment expenses. In the API, the cost
object on task payloads includes amount and currency. Omitting cost, or sending it as
null, creates a task without cost unless the endpoint schema says otherwise.
Text Length
Text-type tasks can specify a text length requirement: a predefined option that indicates
the expected word count or length category. Text length options are defined per task format and
referenced by optionId in the API.
Publications
A Publication represents a scheduled or published output of a story on a specific platform. A single story can have multiple publications across different channels.
Each publication belongs to exactly one Platform and can optionally have a Category and a Type (both defined within that platform).
Task-Publication Links
Tasks and publications can be linked to each other within the same story.
- A task may contribute to one publication or to several publications.
- A publication may depend on one task or on several tasks.
- The link answers a practical planning question: which assignments contribute to which output.
In the API, this link is always explicit rather than inferred automatically. For the exact payload
shapes and localId rules, see Task-Publication Linking.
Publication Scheduling
Publications can be:
- Undated: no schedule assigned yet
- Single-dated: scheduled for one specific date, optionally with a time or time slot
- Recurring: repeating on a daily (weekday-based) or manual (issue-based) schedule
For details on the scheduling API, see Publication Scheduling.
Time Slots
Platforms can define time slots: named time ranges for scheduling publications. For example, a digital platform might have "Morning" (6:00-9:00), "Noon" (11:00-13:00), and "Evening" (18:00-21:00) slots.
Platform responses expose each slot with id, name, start, and end. Publication schedules
reference an existing slot by timeSlotId in the schedule timing object.
For v1-to-v2 platform schedule and time-slot migration notes, see Platform Schedule Configuration Migration.
Publication CMS Data
When a publication is connected to a content management system, the cms object on the
publication carries integration data:
cms.articleId: the publication's identifier in the CMScms.publishedLink: a link object for the public-facing published contentcms.editLink: a link object for opening the content in the CMS editorial UI
This data model supports CMS integrations where Kordiam and an external CMS exchange article references.
Statuses
Kordiam uses three independent status systems that operate at different levels of the editorial model. Available statuses are configured per organization and, for tasks and publications, further scoped by format or platform.
This section explains what each status system means in the Kordiam editorial workflow. For the exact reference endpoints and field names, see Resource Model.
Element Status
Applies to the entire story or event, regardless of how many tasks or publications it has. Commonly used for:
- Editorial decision-making: moving stories through a pitch-to-publish pipeline (e.g., Proposed → Accepted → In Progress → Ready)
- Priority flagging: marking important stories for filtering
Publication Status
Applies per publication. One story with three publications can have three different statuses. Used for:
- Platform-specific decisions: which channels will run the story
- Production tracking: from proposal through editing to publication
Each platform can define which publication statuses are relevant to it, including a default that product workflows may preselect. Public REST write defaults are defined by the endpoint schemas.
Task Status
Tracks the workflow stage of individual tasks (e.g., Requested → Received → Approved). Task-format
metadata can expose different status lists for different formats, while public task writes validate
statusId against the organization's active task statuses.
Custom Fields
Custom fields extend the data model with organization-specific attributes on stories, tasks, and publications.
They are split into definitions (what fields exist) and values (what data a specific story, task, or publication carries).
The public write model supports text, single selection, multiple selection, date, and number values. Some internal definition types are intentionally hidden from public definition reads and are not writable through the public API.
Scoping
Custom fields can be scoped to:
- Elements: story- or event-level metadata
- Tasks: assignment-specific metadata, optionally limited to selected task formats
- Publications: output-specific metadata, optionally limited to selected platforms
For the exact resource split between field definitions, field options, and stored values, see Resource Model.
Platforms and Categories
Platforms
A Platform represents a publication channel such as a website, print newspaper, mobile app, newsletter, or social media account. Each platform can define its own:
- Categories: content sections (Politics, Sports, Culture)
- Subcategories: nested sections within categories
- Types: content formats (Article, Interview, Opinion, Review)
- Time slots: named scheduling windows
- Publication statuses: which statuses are relevant for this channel
Categories
Categories organize content within a platform and support one level of nesting: a category can have subcategories, but subcategories cannot have their own children.
Groups
Groups are organizational units such as editorial desks, departments, or teams. They help express:
- Which users belong to which organizational unit
- Which stories are relevant to which department
- Platform and category access relationships
Groups can reference a parent group. User responses can include the groups a user works for.
In practice, groups help express editorial ownership, desk responsibility, and access boundaries.
Users
Users in Kordiam fall into two categories:
| User type | Description |
|---|---|
| Internal | Staff members with full or scoped access |
| External | Freelancers and contractors |
Users can also carry additional identifiers for system integration:
supplierIdexternalId
Both identifiers are optional and depend on the organization's integration setup; the public schema does not assign them different meanings by user type.
Shifts and Absences
Shifts define recurring work schedules (e.g., "Early Morning Shift", "Night Desk"). Each shift has a weekly schedule, start/end times, time zone, and an availability code indicating whether assigned users are available for additional work.
Absences are user availability exceptions such as vacation, business trips, days off, and short-work periods.
Related Pages
- Resource Model: technical resource model and ERD diagrams
- Write Semantics: how
POST,PUT,PATCH, andDELETEbehave - Task-Publication Linking: linking rules and
localIdusage - Publication Scheduling: schedule subresource API
- Publishing Publications: publish lifecycle operation