Skip to main content

API Changelog: Breaking Changes

Entries with a breaking change to a core epilot API, newest first. Other changes of the same entry are listed with it. Subscribe via RSS

Showing the core APIs: the APIs integrations are built on, which we keep stable and backwards compatible, together with the core entities and events. APIs for specific platform features change more often and are left out here. Show all APIs

November 11, 2026

Design Builder API

Breaking Deprecated endpoints removed โ€” GET /v1/brands and GET /v1/designs/limit were removed.

New Asynchronous document generation โ€” Start a document generation job and track it.

API details
  • POST /v1/designs/document/generate/jobs
  • GET /v1/designs/document/generate/jobs/{jobId}

Entity Mapping API

Breaking Mapping history removed โ€” The deprecated GET /v1/mappings/history endpoint was removed.

Product Recommendation Entity

Breaking active removed โ€” The active attribute was removed from product recommendations.

Event: Portal User Logged In

Breaking Published directly from portal logins โ€” The event is no longer derived from portal user entity updates, so the operation, activity_id, activity_type, and trigger_entity fields were removed.

New Logins on behalf of the customer โ€” The event now also fires when an epilot or partner user logs in as the customer.

API details
  • New is_admin_login field
  • New optional admin_user_id, admin_email, and admin_org_id fields

Event: Portal User Registered

Breaking Published directly from portal registrations โ€” The event is no longer derived from portal user entity changes. It no longer fires for email changes, manual edits, or imports, and the operation, activity_id, activity_type, and trigger_entity fields were removed.

November 10, 2026

Campaign Entity

Breaking Campaign dates are date-time values โ€” start_date and end_date are now date-time values instead of dates.

New Scheduled status โ€” Campaigns support the new scheduled status.

November 6, 2026

Automation API

Breaking Email forwarding targets accept environment variables โ€” forward_to[].email in automation actions accepts environment variable references such as {{ env.my_variable }} in addition to plain email addresses. The field no longer uses the email format and follows a new pattern instead, across the flow and execution endpoints. This breaks clients that validate the field as an email.

November 2, 2026

Core Entities

Breaking Core entity schemas now reflect how epilot stores data โ€” Assignee fields, footnotes, product features and price tiers changed type in the schemas.

API details
  • User assignment fields such as assigned_to and assignee are now arrays of user or user group references (with user_id, group_id, org_id, email, display_name, phone, and image_uri) instead of a single user object
  • footnotes on coupons, prices, products, and taxes and the product feature field changed from a string to an array of objects
  • Price tiers changed from a single object to an array of tiers

Action needed Null and empty values โ€” Handle null attributes, empty relation arrays and relative link paths when reading entities.

API details
  • Most entity attributes, enum values, and link href values may now be null
  • Empty relations may be returned as empty arrays
  • Link href values may be paths within epilot 360 rather than absolute URLs

New Action needed Richer workflow summaries on entities โ€” Workflow summaries carry more detail about tasks, phases and closing reasons. Be prepared for the new task statuses and for previously required fields being absent.

API details
  • New optional fields: duedate, current_tasks, selected_closing_reasons, closing_reason_description, task_start_date, and phase_assignees
  • Previously required fields are now optional
  • New task statuses: SCHEDULED, PENDING, CONDITION_PENDING, WAITING_FOR_CONFIRMATION, WAITING_FOR_JOURNEY_SUBMISSION, ON_HOLD, and FAILED

October 20, 2026

Journey Config API

Breaking blueprint_customization removed โ€” Journey configurations no longer accept or return blueprint_customization.

API details
  • No longer accepted when creating or updating a journey configuration or revision in v1 and v2
  • No longer returned wherever journey configurations are read

New Journey template variables โ€” List the template variables available to journeys.

API details
  • GET /v1/journey/template-variables
  • v1 journey configurations now carry their templating context wherever they are read

October 19, 2026

Pricing API

Breaking fields is no longer accepted on POST /v1/public/catalog

Changed The required warnings field was removed from the POST /v2/public/catalog response

October 15, 2026

Pricing API

Breaking Variant conditions on POST /v1/conditional-pricing/{slug}/entities/{entity_id}/variants:list and POST /v1/conditional-pricing/{slug}/entities/{entity_id}/variants:tree now use the new ContextConditionValue and PostalCodeFilter shapes; the previous PostalCodeCity and ConditionPredicate shapes are no longer accepted in conditions

October 2, 2026

Submission API

Breaking GET /v1/submission/nonce/{nonce_id} now responds with an object containing a required exists flag and an optional nonce instead of returning the nonce directly

September 29, 2026

Entity API

Breaking The zipcode and zipcode_town values of conditions[].format on entity schemas were renamed to postal_code and postal_code_city โ€” affecting PUT /v1/entity/schemas/{slug} and everywhere entity schemas are read

Integration Toolkit API

Breaking validation.entity_details_truncated was removed from import responses on all /v2/erp/imports endpoints

New New POST /v1/integrations/{integrationId}/outbound/mapping-simulation endpoint was added for simulating outbound mappings

New Dead-lettered outbound messages can now be redriven with the current mapping re-applied through a new optional reapply_mapping field on POST /v1/integrations/{integrationId}/outbound/messages/dlq/redrive โ€” redrive results can now return the new mapping_failed status together with a mapping_error, so consumers must be prepared for this additional status

New New GET /v2/erp/imports/{importId}/download and GET /v2/erp/imports/{importId}/preview endpoints were added for downloading and previewing an import

Changed POST /v2/integrations/{integrationId}/monitoring/stats can now filter by correlation through new optional correlation_id and correlation_ids fields, and group results by the new correlation_id value of group_by

September 22, 2026

Workflows Definition API

Breaking edges[].end_type was removed from flow templates: it is no longer accepted by POST /v2/flows/templates and PUT /v2/flows/templates/{flowId} and no longer returned wherever flow templates are read

Workflows Execution API

Breaking edges[].end_type was removed from flow executions: it is no longer returned wherever flow executions are read

Action needed Task conditions can now be evaluated against the main context: tasks[].conditions[].statements[].source.origin_type returns the new main_context value โ€” so consumers must be prepared for this additional value

Changed Workflow stages can now report that they were never reached: stages[].status returns the new NOT_REACHED value from POST /v2/flows/executions:portal-search and POST /v2/flows/executions:portal-search-batch โ€” so consumers must be prepared for this additional status

Changed Execution contexts now report by which task they were added, and when and by which task they were promoted or demoted, through new optional contexts[].added_by_task_id, contexts[].promoted_at, contexts[].promoted_by_task_id, and contexts[].demoted_by_task_id fields โ€” accepted on POST /v2/flows/executions and PATCH /v2/flows/executions/{execution_id} and returned wherever flow executions are read

Changed Automations can now write their result into a context through a new optional automation_config.output_context field on a task and on the trigger โ€” accepted on POST /v2/flows/executions, POST /v2/flows/executions/{execution_id}/tasks, and PATCH /v2/flows/executions/{execution_id}/tasks/{task_id} and returned wherever flow executions are read

September 15, 2026

Entity API

Breaking Schema conditions no longer carry values; which values a condition matches is now described by a new optional options instead โ€” affecting PUT /v1/entity/schemas/{slug} and everywhere schemas are read

New New optional ui_config.custom_tabs field added to entity schemas, accepted on PUT /v1/entity/schemas/{slug} and returned by the schema read, list and versions endpoints

Changed Capabilities can now declare which fields they manage through a new optional managed_fields field โ€” accepted on POST /v1/entity/schemas/capabilities, PUT /v1/entity/schemas/capabilities/{composite_id}, and PUT /v1/entity/schemas/{slug}, and returned wherever schemas and capabilities are read

September 10, 2026

Event Catalog API

Breaking PATCH /v1/events/{event_name} accepts new optional enabled, auto_trigger, and success_criteria fields, and its request body must now be an object

Changed Catalog events can now be managed through the API: new POST /v1/events for creating an event, PUT /v1/events/{event_name} for replacing it, DELETE /v1/events/{event_name} for removing it, POST /v1/events/{event_name}:preview for previewing what it would produce, and POST /v1/events/{event_name}:publish for publishing it

Changed Catalog events report new optional api_trigger, event_origin, lineage, mapping, and entity_operation.purpose_filters fields, and automation_trigger_only and automation_trigger_seed_node are no longer read-only โ€” returned by GET /v1/events, GET /v1/events/{event_name}, and PATCH /v1/events/{event_name}

September 8, 2026

Integration Toolkit API

Breaking Import validation now reports what it looked at and what went wrong in more detail: new optional validation.entity_details, validation.entity_details_truncated, and validation.issues[].subject fields, together with the new issue codes SCHEMA_NOT_FOUND, SCHEMA_NOT_CONDITIONABLE, SCHEMA_DECLARES_NO_CONDITIONS, ATTRIBUTE_NOT_IN_SCHEMA, ATTRIBUTE_NOT_OVERRIDABLE, CONDITION_VALUE_MISSING, IS_CONDITIONAL_NOT_CONSTANT, GROUPING_KEY_NOT_A_COLUMN, GROUPING_KEY_IS_FOLD_COLUMN, TIER_BANDS_CONFLICT, TIER_ROWS_NOT_GROUPED, and VARIANT_VALUE_CONFLICT โ€” returned by all /v2/erp/imports endpoints, where validation.total_rows is no longer always present

Changed Entity mappings can now be applied conditionally through a new optional configuration.entities[].conditional field โ€” accepted when creating or updating a use case or an integration as well as by POST /v1/erp/updates/direct_simulation and the mapping simulation endpoints, and returned wherever use cases and integrations are read

August 31, 2026

Environments API

Breaking Environment values are no longer text-only: the type of an environment accepts the new Text, Number, Boolean, Map, and JSON values, and its value is no longer always a string but takes the shape matching the type โ€” affecting POST /v1/environments and PUT /v1/environments/{key} as well as everywhere environments are read

Changed PUT /v1/environments/{key} can now respond with 409 when the environment conflicts with the current state

August 28, 2026

Entity API

Breaking The variant_overridable field of schema attributes and capabilities was removed and replaced by a new optional overridable_attribute field โ€” affecting the schema, attribute, and capability endpoints in v1 and v2, in both requests and responses

August 27, 2026

Permissions API

Breaking Grant conditions accept a new optional attributes list for applying a condition to several attributes at once; a condition's values must now contain at least one entry

Changed Grant conditions gained two new types, NotEqualsCondition and NotEqualsCurrentUserCondition, for granting access when a value does not match โ€” accepted on POST /v1/permissions/roles and PUT /v1/permissions/roles/{roleId} and returned wherever roles and grants are read

August 26, 2026

Workflows Execution API

Breaking agent_execution and agent_execution_id on a workflow task may now be null where an object and a string were previously returned โ€” affecting all flow execution and task responses

New New optional loop_iterations field added to workflow tasks, reporting how often a looping task ran; tasks and phases additionally report an optional analytics.skipped_at when they were skipped, and executions an optional analytics.started_by_org_id

August 21, 2026

Integration Toolkit API

Breaking Use case configuration no longer supports constants, lookups, params_mapping, required_params, file_source, fan_out.split_expression, upload.external_id, and upload.success_when โ€” these fields are no longer accepted when creating or updating a use case or an integration, and are no longer returned by the use case, integration, and use case history endpoints

Changed Request steps of a use case gained two new optional fields: body_jsonata for building the request body with a JSONata expression, and enabled for switching a single step off; file uploads additionally accept an optional upload.max_total_bytes limit

Changed POST /v2/erp/imports now accepts an optional import_id to continue working on an existing import, answers with 200 in that case, and can answer with 404 or 409 when the referenced import cannot be used

August 20, 2026

Event: Customer Request Submitted

Breaking The event is now triggered from an automation instead of an entity operation โ€” the operation, activity_id, activity_type, and trigger_entity fields were removed, and _event_source and _trigger_source_type are now always automation

Changed ticket, event_attachments, _trigger_source_type, and _trigger_source are now always present; event_attachments is always sent but may be empty when the request carries no files, and _trigger_source identifies the automation execution and action that triggered the request

August 19, 2026

App API

Breaking The sandbox custom action type was removed โ€” configuration.type no longer accepts sandbox on POST/PATCH /v1/app-configurations/{appId}/versions/{version}/components and it is no longer returned on the app, app-configuration, and public component read endpoints

Action needed App components can now authenticate with basic auth โ€” configuration.auth_type accepts and returns the new basic value, so consumers must be prepared for this additional value

New New optional query request parameter added to the app proxy endpoints (GET/POST/PUT/PATCH/DELETE /v1/public/app/{appId}/proxy/{proxyName}/{path}) for passing a query string on to the proxied request

Changed Apps can now declare functions โ€” a new optional list accepted on PATCH /v1/app-configurations/{appId}/versions/{version} and returned wherever apps and app configurations are read, together with a new function custom action type that lets a component reference one of those functions; APP_FUNCTION is accepted as a componentType filter on GET /v1/app and as an event source on POST /v1/app-events and POST /v1/app-configurations/{appId}/events

Meter Counter Entity

Breaking The megawatt units of the meter_counter unit attribute were corrected from mw and mWh to MW and MWh โ€” the old lowercase values are no longer accepted

August 6, 2026

Workflows Execution API

Breaking automation_execution_id and schedule.schedule_id on workflow tasks may now be null where a string was previously guaranteed โ€” affecting all flow execution and task responses (POST /v2/flows/executions, GET/PATCH /v2/flows/executions/{execution_id}, the task create, update, execute, automation-run, reconcile-automation, and schedule run-now endpoints, and POST /v2/flows/executions:search)

July 30, 2026

Journey Config API

Breaking The journey settings.savingProgress fields were renamed: savingMode is now mode and supportedVersion is now supportedRevision. The old names are no longer accepted on POST/PUT /v1/journey/configuration and are no longer returned by the v1 journey configuration endpoints

Changed settings.savingProgress is now also supported on the v2 journey configuration endpoints โ€” accepted by POST/PUT /v2/journey/configuration and returned by GET /v2/journey/configuration/{id} and the v2 create, update, and patch responses

July 9, 2026

Integration Toolkit API

Breaking The integration notification rule type enum was narrowed โ€” the consecutive_failures, first_error, new_error_code, auth_expiry, ack_timeout, and validation_surge values are no longer accepted on create/update or returned in responses, and the related consecutive rule field was removed from both requests and responses

June 24, 2026

File API

Breaking The summary_status field was removed from file response objects โ€” read summary state from the new summary endpoints instead

Changed AI file summaries are now managed as asynchronous jobs: new GET /v1/files/{id}/summary returns the current summary text and status, POST /v1/files/{id}/summary-jobs creates (or returns) the current summary job, and GET /v1/files/{id}/summary-jobs/current and GET /v1/files/{id}/summary-jobs/{job_id} poll job status; the summary response now exposes per-language preview_summary_de/preview_summary_en and short_summary_de/short_summary_en fields

June 16, 2026

Snapshot API

Breaking The preserve_modified option was removed from POST /v1/snapshots/{id}:restore, and the related skipped arrays (and SkippedResource schema) were removed from restore and capture results on GET /v1/snapshots and GET /v1/snapshots/{id}; drift-based skipping is no longer performed during restore

New New POST /v1/snapshots:capture-org endpoint added for asynchronously snapshotting the caller's entire organization

Changed POST /v1/snapshots/{id}:restore now accepts an optional exclude_target_ids array (target IDs the caller wants left untouched during restore)

June 15, 2026

Integration Toolkit API

Breaking Outbound use case delivery configuration was restructured into a discriminated union of WebhookDeliveryConfig and the new PollDeliveryConfig; the previous flat type, webhook_id, webhook_name, and webhook_url delivery fields were removed

New New endpoints added for managing outbound message queues: POST /v1/integrations/{integrationId}/outbound/messages/poll, .../ack, and .../unblock, plus GET /v1/integrations/{integrationId}/outbound/messages/dlq and POST .../outbound/messages/dlq/redrive for dead-letter handling

May 25, 2026

Webhooks API

Breaking Multipart webhook delivery configuration was restructured: the metadataFieldName field was removed and replaced by fileSource (a JSONata expression selecting which attachments to send), fileFieldStrategy (single or multi), and extraFields (additional form fields populated from JSONata expressions)

April 30, 2026

Integration Toolkit API

Breaking slug request property is now required on all use-case create variants (POST /v1/integrations/{integrationId}/use-cases) โ€” file proxy, inbound, managed call, outbound, and secure proxy

New New optional allowed_origins array field added to FileProxy use case configuration, listing additional origins permitted to call /download (CORS); portal origins remain always allowed

April 28, 2026

Notes API

Breaking created_by field type changed from a single object to an array of objects across all note endpoints โ€” consumers reading created_by fields must handle arrays

Breaking POST /v1/notes:search now requires at least one entry in the contexts array; previously empty arrays were silently accepted

New New optional edited_at timestamp field added to notes and comments

New New optional include_related_schemas array field added to note search requests for including notes on related entity schemas

April 17, 2026

Pricing API

Breaking context.contract.billing_account and context.contract.payment request fields on POST /v1/public/external-catalog/products and POST /v1/public/external-catalog/product-recommendations changed from string relation IDs to objects

Changed context.contract.branch enum constraint removed on the same endpoints; the field now accepts any string instead of only the previous fixed values (power, gas, water, waste_water, district_heating)

March 11, 2026

Pricing API

Breaking Several fields in ExternalCatalogPortalRequest contract context changed type: installment_amount changed from {value, currency} object to number; balance changed from {value, currency} object to number; customer changed from an array to a single object; delivery_address changed from a single object to an array

February 26, 2026

ERP Integration API

Breaking The requires_vpc field in File Proxy use-case configuration is now read-only after creation โ€” it can no longer be set or updated via the API; affects POST /v1/integrations/{integrationId}/use-cases, PUT /v1/integrations/{integrationId}/use-cases/{useCaseId}, and their v2 equivalents

February 25, 2026

Billing API

Breaking booking_date (date) is now a required field when creating or updating billing events โ€” affects POST /v1/billing/events and PATCH /v1/billing/events/{id}

Breaking due_date on InstallmentEvent changed from date-time to date format

New New optional fields were added to all billing event types: direction (debit/credit), status (open/closed), related_event, external_link, attachments, note, and internal_note

Changed Six new billing event types were added to the BillingEvent union: payment, dunning_fee, final_bill, bonus, correction, and custom โ€” clients parsing event responses should handle these new variants

February 24, 2026

ERP Integration API

Breaking payload field on event update endpoints now enforces stricter validation โ€” string payloads require minLength: 2 and object payloads require minProperties: 1; affects POST /v1/erp/updates/events, POST /v2/erp/updates/events, and POST /v3/erp/updates/events

New New warnings array was added to mapping simulation responses (POST /v1/erp/updates/mapping_simulation, POST /v2/erp/updates/mapping_simulation), reporting validation issues about the configuration such as unique ID fields referencing non-indexed attributes

February 10, 2026

ERP Integration API

Breaking reverse-relations was removed from scope_mode enum in inbound use case entity scope

New New POST /v3/erp/updates/events endpoint was added โ€” v3 event processing using integration-based authentication

February 6, 2026

Entity API

Breaking POST /v1/entity/taxonomies/{taxonomySlug}/classifications โ€” deleted response type changed from object to array

December 2, 2025

ERP Integration API

Breaking Use case create/update request body changed to a discriminated union (CreateInboundUseCaseRequest | CreateOutboundUseCaseRequest)

New New GET .../use-cases/{useCaseId}/history endpoint was added for use case configuration history