Copy page

Resource Guides

Configuration Resources

Configuration resources provide the IDs, codes, and metadata used by element, task, and publication write payloads.

Use this page for v2 behavior. Use the API reference for exact paths, schemas, examples, response status codes, and endpoint-specific validation.

Resource Families

Family	Public v2 surface
Groups	/api/v2/groups
Platforms	/api/v2/platforms
Categories	/api/v2/platforms/{platformId}/categories for list/create, /api/v2/categories/{id} for item operations
Types	/api/v2/platforms/{platformId}/types for list/create, /api/v2/types/{id} for item operations
Element statuses	/api/v2/element-statuses
Publication statuses	/api/v2/publication-statuses and /api/v2/publication-statuses/platform/{platformId}
Task statuses	/api/v2/task-statuses
Task formats	/api/v2/task-formats

Statuses and task formats are read-only through the public API.

Lists And Lookups

Group, platform, status, task-format, category, and type lists use the shared v2 list response shape:

Code
{
  "content": [],
  "size": 20,
  "hasMore": false
}

Use Querying Lists for shared query behavior.

External-ID lookups use /external-id/{externalId} where exposed:

Code
GET /api/v2/groups/external-id/{externalId}
GET /api/v2/platforms/external-id/{externalId}
GET /api/v2/categories/external-id/{externalId}
GET /api/v2/types/external-id/{externalId}

External IDs are integration identifiers, not uniqueness guarantees. Persist the returned v2 id for later writes whenever possible.

Write Models

Resource	Create	Replace	Patch
Group	name, optional externalId, optional parentGroupId	name, optional externalId	presence-aware name and externalId
Platform	name plus platform fields and optional schedule fields	full replacement, including required platform fields	presence-aware patch; schedule fields follow platform schedule rules
Category	platform ID in path, name, optional externalId, optional parentCategoryId	name, optional externalId, required parentCategoryId field that can be null	presence-aware name, externalId, and parentCategoryId
Type	platform ID in path, name, optional externalId	name, optional externalId	presence-aware name and externalId

Create operations for groups, platforms, platform-scoped categories, and platform-scoped types return 201 Created.

Category And Type Placement

Categories and types belong to a publication platform.

For categories:

• list and create categories through /api/v2/platforms/{platformId}/categories.
• use parentCategoryId to create or move a subcategory.
• parentCategoryId: null means top-level placement where the operation documents it.
• existing top-level categories cannot be moved under another parent through PUT or PATCH; send parentCategoryId: null on PUT, or omit it on PATCH.
• only top-level categories can be used as parents.

For types:

• list and create types through /api/v2/platforms/{platformId}/types.
• update a persisted type through /api/v2/types/{id}.
• update and patch payloads do not move a type to another platform.

Delete Behavior

Configuration deletes have two success outcomes:

Resource	Immediate response	Deferred response	Notes
Group	204 No Content	202 Accepted with a message body	Deleting a group with subgroups can fail with 400 Bad Request; delete child groups first.
Platform	204 No Content	202 Accepted with a message body	Only platforms created through the API can be deleted through the API; platforms created in the Kordiam app return 400 Bad Request. This is not exposed in the platform response, so handle it at delete time.
Category	204 No Content	202 Accepted with a message body	Category delete can remove linked publications according to category-delete business rules.
Type	204 No Content	Not exposed	Deletes the addressed type.

Either status can be returned for the same resource, depending on how much related data the deletion has to process. Branch on the status code at runtime: 204 means the deletion is already complete, while 202 means it was accepted and finishes asynchronously — re-read the resource (or its parent) before assuming it is gone.

Statuses And Task Formats

Status families are separate:

• element statuses apply to the root story/event workflow.
• publication statuses apply to publications; platform-scoped status reads include triggersExport (whether reaching that status exports the content to the platform's connected external system).
• task statuses apply to tasks and are used through task formats.

A task format is the kind of deliverable a task produces (text, picture, video, and so on). Task formats expose:

• typeCode for the format kind: 1 text, 2 picture, 3 video, 4 audio, 5 other.
• active.
• defaultTaskStatus.
• taskStatuses.
• textLength only for text formats.

Use IDs from these endpoints when building element, task, or publication write payloads.

Related Guides

• Platform Schedule Configuration
• Write Semantics
• Resource Model
• Configuration Resource Migration