Copy page

Migrating from v1

Elements

This page covers migration notes for root element reads and root element writes.

Use it together with the Elements API reference. The API reference remains the source of truth for exact schemas, examples, status codes, and field-level omission or null semantics.

Task, publication, schedule, task-publication linking, and custom-field value details are only summarized here. See their dedicated guide pages and resource-specific migration pages.

Scope

Covered v2 endpoints:

Area	v2 endpoint
List elements	GET /api/v2/elements
Read one element	GET /api/v2/elements/{id}
Create root element aggregate	POST /api/v2/elements
Replace root element aggregate	PUT /api/v2/elements/{id}
Patch root element aggregate	PATCH /api/v2/elements/{id}
Read external-system bindings	GET /api/v2/elements/{id}/external-elements
Link external-system binding	POST /api/v2/elements/{id}/external-element/link
Unlink external-system binding	POST /api/v2/elements/{id}/external-element/unlink
Patch element custom fields	PATCH /api/v2/elements/{id}/custom-fields

Endpoint Mapping

v1 usage pattern	v2 direction
GET .../elements/{id}	Use GET /api/v2/elements/{id}.
Specialized element collection reads such as platform, group, no-publication, or user-based paths	Use GET /api/v2/elements with filter query parameters and cursor pagination. Per-endpoint mappings are listed in List Elements Migration.
POST .../elements/	Use POST /api/v2/elements with v2 request fields.
PUT .../elements/{id}	Use PUT /api/v2/elements/{id} for full replacement.
Partial root element edits	Use PATCH /api/v2/elements/{id} for presence-aware updates.
PUT .../elements/link-external-element/{id}	Use POST /api/v2/elements/{id}/external-element/link.
Element custom-field patch	Use PATCH /api/v2/elements/{id}/custom-fields and map values through Custom-Field Migration.

List Elements Migration

v1 exposed several specialized list endpoints under /api/v1_0_1/elements/... for platform, group, story-idea, no-publication, and user views. v2 unifies these into a single endpoint, GET /api/v2/elements, driven by query parameters. The endpoint uses cursor pagination and returns an ElementListResponse wrapper instead of a bare JSON array.

Get Platform Elements

Get Group Elements

Add dateFrom and dateTo for the publication date range.

Get Story Ideas

Get Elements Without Platforms

Use modificationDateFrom and modificationDateTo where v1 used fromDate and toDate.

Get User Elements

userId enables user task mode and is required for deadlineFrom, deadlineTo, done, and formatIds. When the deadline range is omitted, it defaults to today through today plus 14 days; tasks without a deadline are included by element modification date from today minus 6 months through today. Explicit deadline ranges must not exceed 366 days.

General notes

• v1 endpoints returned a bare JSON array. v2 returns an ElementListResponse containing content[], size, hasMore, and nextCursor. Follow nextCursor to walk the full result set; the endpoint is cursor-only.
• Comma-separated path IDs in v1 (for example /groups/1,2,3) become comma-separated query parameter values in v2 (groupIds=1,2,3). The same applies to other list filters such as formatIds.
• v1 path-based date ranges (/from/{fromDate}/to/{toDate}) become dateFrom and dateTo query parameters that accept ISO 8601 dates or date-times.

Request Field Mapping

v2 request fields use explicit ID and code names. Common root element mappings:

v1-style field	v2 field
elementStatus	elementStatusId
groups	groupIds
tasks[].status	tasks[].statusId
tasks[].format	tasks[].formatId
tasks[].confirmationStatus	tasks[].confirmationStatusCode
publications[].status	publications[].statusId
publications[].platform	publications[].platformId
publications[].category	publications[].categoryId
publications[].type	publications[].typeId
publications[].assignments	publications[].assignedTaskRefs in root element writes, or assignedTaskIds in standalone publication writes
externalElement.id	externalElement.externalId

Do not send the v2 response body back as a write request without mapping it through the relevant request schema. Response objects include read-only IDs, URLs, timestamps, embedded references, and server-managed metadata.

Response Model Changes

ElementApiModel is an aggregate response. It can include root element fields plus nested tasks, publications, customFields, creator, editor, and external-system data.

The response model uses object references where v1 clients may have parsed scalar values and parallel name fields. Examples:

• elementStatus is an object reference in responses; write elementStatusId in requests.
• groups is a list of group references in responses; write groupIds in requests.
• publication placement uses reference objects in responses; write platformId, categoryId, typeId, and statusId in requests.
• task status, format, and confirmation status use response references; write statusId, formatId, and confirmationStatusCode in requests.

Clients should tolerate additive response fields and parse only the documented fields they need.

Write Semantics

POST /api/v2/elements creates the root aggregate. Optional branches can be omitted when they are not needed, but the resulting element must still satisfy the root content rule: it needs at least one publication, one task assigned to a registered user, or one group association.

PUT /api/v2/elements/{id} is a full replacement of the writable root state. Notable rules:

• confidential is required.
• null is invalid for replacement collections such as attachments, groupIds, tasks, publications, and customFields.
• omitted or empty replacement collections can clear data where the field description documents that behavior.
• nested publication schedules are managed through the schedule subresource, not root PUT.

PATCH /api/v2/elements/{id} is presence-aware:

• omitted fields remain unchanged.
• explicit null clears only fields whose schema documents clear-on-null semantics.
• collection-shaped patch fields use the operation-specific behavior from the field description.
• tasks, publications, and customFields are instruction lists; sending [] means an empty instruction list, while null is invalid.

For method-level rules, see Write Semantics.

External-System Bindings

v2 separates external-system binding commands from the root element response:

• GET /api/v2/elements/{id}/external-elements returns the current binding list.
• POST /api/v2/elements/{id}/external-element/link links or updates a binding and returns the refreshed binding list.
• POST /api/v2/elements/{id}/external-element/unlink removes a binding and returns the refreshed binding list.

The link request uses:

• optional systemUrl
• required externalElement
• at least one of externalElement.externalId or externalElement.link

When systemUrl is omitted, the API resolves the target binding from the current organization settings.

Status Codes And Errors

Element endpoints use the shared v2 error contract:

• 400 for invalid parameters, body shape, validation, and unsupported field values
• 401 for missing or invalid authentication
• 403 for write operations the authenticated caller cannot perform
• 404 when an element or addressed subresource is not found or not visible

Validation errors use application/problem+json and can include field-level errors[]. See Error Contract Changes.

Migration Checklist For Elements

• Replace specialized v1 element collection calls with GET /api/v2/elements filters where possible.
• Re-map root write fields to explicit v2 ...Id, ...Ids, and ...Code names.
• Rebuild task-publication links using assignedTaskRefs for root writes and assignedTaskIds for standalone publication writes.
• Treat root PUT as replacement and root PATCH as partial update.
• Manage root elements through create and update operations only.
• Parse the returned element aggregate as the refreshed state after root and nested writes.
• Update external-system link calls to the v2 link/unlink command endpoints.

Related Guides

• Resource Model
• Write Semantics
• JSON Model Changes
• Task-Publication Linking
• Publication Scheduling