{ "openapi": "3.0.0", "info": { "title": "Journey API", "description": "API to configure journeys", "version": "1.6.0" }, "security": [ { "EpilotAuth": [] } ], "tags": [ { "name": "Journeys", "description": "Journey operations" }, { "name": "Journeys V2", "description": "Journey V2 operations" }, { "name": "journey_schema", "x-displayName": "Journey", "description": "\n" } ], "x-tagGroups": [ { "name": "APIs", "tags": [ "Journeys", "Journeys V2" ] }, { "name": "Schemas", "tags": [ "journey_schema" ] } ], "paths": { "/v1/journey/organization/{id}": { "get": { "operationId": "getJourneysByOrgId", "summary": "getJourneysByOrgId", "description": "Get all journeys by organization id", "tags": [ "Journeys" ], "parameters": [ { "name": "id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "example": "123" } }, { "name": "hydrate", "in": "query", "description": "Hydrate", "required": false, "schema": { "type": "string", "example": "true" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetJourneysResponse" } } } } } } }, "/v1/journey/configuration/{id}": { "get": { "operationId": "getJourney", "summary": "getJourney", "description": "Get journey by id. Private journeys requires valid private token to be passed", "security": [ {}, { "EpilotAuth": [] }, { "PortalAuth": [] } ], "tags": [ "Journeys" ], "parameters": [ { "name": "id", "in": "path", "description": "Journey ID", "required": true, "schema": { "type": "string", "format": "uuid", "example": "509cdffe-424f-457a-95c2-9708c304ce77" } }, { "name": "version", "in": "query", "description": "Revision row to read. `0` (default) is the journey record, the published version every customer receives; a positive integer `n` reads revision row `n` (used by config-engine for history reads). Distinct from the `revisions` counter on the body, which is the legacy change counter of the published version. Versioning metadata is only available via `publish-state`.\n", "required": false, "schema": { "type": "integer", "default": 0 } }, { "name": "revision_id", "in": "query", "description": "Serve the named revision instead of the published version, so a save-and-continue session can stay on the revision it started on. Only revisions that have been published at least once are served on the public and portal routes; an unpublished revision is served to `EpilotAuth` callers with the edit permission and is otherwise unknown. Cannot be combined with the legacy `version` parameter.\n", "required": false, "schema": { "type": "string", "example": "42" } }, { "name": "source", "in": "query", "description": "What source ID. Journey or Entity ID", "required": false, "schema": { "type": "string" } }, { "name": "orgId", "in": "query", "description": "Organization ID", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Journey" }, { "$ref": "#/components/schemas/JourneyActivationGuarantee" }, { "$ref": "#/components/schemas/JourneyServedRevision" } ] } } } } } }, "delete": { "operationId": "removeJourney", "summary": "removeJourney", "description": "Remove journey by id", "tags": [ "Journeys" ], "parameters": [ { "name": "id", "in": "path", "description": "Journey ID", "required": true, "schema": { "type": "string", "format": "uuid", "example": "509cdffe-424f-457a-95c2-9708c304ce77" } } ], "responses": { "200": { "description": "Success", "content": {} }, "404": { "description": "Journey not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "journey not found" } } } } } } } } }, "/v1/journey/configuration/{id}/revisions": { "post": { "operationId": "createJourneyRevision", "summary": "createJourneyRevision", "description": "Creates a revision: an immutable copy of the complete journey configuration, identified by `revision_id`. Nothing customers receive changes; the revision only becomes the published version when it is published. The payload is complete and is not merged against the journey record or the previous revision. The entity datasource set of the revision is stored separately through the datasources API under the same `revision_id`.\n\nOnly available for organizations with journey versioning enabled; returns `404` otherwise.\n", "tags": [ "Journeys" ], "security": [ { "EpilotAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "description": "Journey ID", "required": true, "schema": { "type": "string", "format": "uuid", "example": "509cdffe-424f-457a-95c2-9708c304ce77" } } ], "requestBody": { "description": "Complete journey configuration for the revision", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JourneyRevisionRequest" } } } }, "responses": { "201": { "description": "Revision created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JourneyRevisionSummary" } } } }, "400": { "description": "Invalid payload" }, "403": { "description": "No permission to edit the journey" }, "404": { "description": "Journey versioning not enabled for the organization, or journey not found" }, "409": { "description": "`parent_revision_id` is not the latest revision: the journey was saved since the editor loaded it. The body carries the current latest revision.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JourneyRevisionConflict" } } } } } }, "get": { "operationId": "listJourneyRevisions", "summary": "listJourneyRevisions", "description": "Lists the journey's revision history, newest first. Metadata only, no configuration payload. `is_published` says whether a revision is the published version right now, which is a different question from `published_at`, which records the last time it was published.\n\nOnly available for organizations with journey versioning enabled; returns `404` otherwise.\n", "tags": [ "Journeys" ], "security": [ { "EpilotAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "description": "Journey ID", "required": true, "schema": { "type": "string", "format": "uuid", "example": "509cdffe-424f-457a-95c2-9708c304ce77" } }, { "name": "limit", "in": "query", "description": "Maximum number of revisions to return", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "description": "Opaque pagination cursor, taken from a previous response's `next_cursor`", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Revision history", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JourneyRevisionList" } } } }, "400": { "description": "Invalid query parameters" }, "403": { "description": "No permission to edit the journey" }, "404": { "description": "Journey versioning not enabled for the organization, or journey not found" } } } }, "/v1/journey/configuration/{id}/revisions/{revision_id}": { "get": { "operationId": "getJourneyRevision", "summary": "getJourneyRevision", "description": "Returns one revision with its full configuration, in the shape the builder holds a journey in, so it can be loaded straight into the editor as unsaved changes. Reading a revision changes nothing; a client persists it, if at all, by posting it back to `POST .../revisions`.\n\nOnly available for organizations with journey versioning enabled; returns `404` otherwise.\n", "tags": [ "Journeys" ], "security": [ { "EpilotAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "description": "Journey ID", "required": true, "schema": { "type": "string", "format": "uuid", "example": "509cdffe-424f-457a-95c2-9708c304ce77" } }, { "name": "revision_id", "in": "path", "description": "Revision ID, as returned in a revision summary", "required": true, "schema": { "type": "string", "example": "42" } } ], "responses": { "200": { "description": "The revision with its configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JourneyRevision" } } } }, "403": { "description": "No permission to edit the journey" }, "404": { "description": "Journey versioning not enabled for the organization, or journey or revision not found" } } } }, "/v1/journey/configuration/{id}/publish": { "post": { "operationId": "publishJourneyRevision", "summary": "publishJourneyRevision", "description": "Makes one revision the published version, the one customers receive, in a single transaction: the revision's configuration is copied onto the journey record, its datasource set onto the published datasources, and `name`, `description`, `published_at` and `published_by` are stamped onto the revision. Any revision can be published, old or new, so publishing an older revision is the rollback.\n\n`name` is generated server-side when omitted, so every published revision carries one; an omitted name never replaces a name a previous publish already set. `settings.isActive` is never changed by a publish.\n\nOnly available for organizations with journey versioning enabled; returns `404` otherwise.\n", "tags": [ "Journeys" ], "security": [ { "EpilotAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "description": "Journey ID", "required": true, "schema": { "type": "string", "format": "uuid", "example": "509cdffe-424f-457a-95c2-9708c304ce77" } } ], "requestBody": { "description": "The revision to publish", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishRevisionRequest" } } } }, "responses": { "200": { "description": "Revision published", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishResult" } } } }, "400": { "description": "Invalid payload" }, "403": { "description": "No permission to edit the journey" }, "404": { "description": "Journey versioning not enabled for the organization, or journey or revision not found" }, "409": { "description": "The journey record changed between read and publish, please try again" } } } }, "/v1/journey/configuration/{id}/publish-state": { "get": { "operationId": "getJourneyPublishState", "summary": "getJourneyPublishState", "description": "Answers which revision is the published version without paging through the history. A journey that has not adopted versioning yet returns `200` with `published_revision_id: null`, not `404`.\n\nOnly available for organizations with journey versioning enabled; returns `404` otherwise.\n", "tags": [ "Journeys" ], "security": [ { "EpilotAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "description": "Journey ID", "required": true, "schema": { "type": "string", "format": "uuid", "example": "509cdffe-424f-457a-95c2-9708c304ce77" } } ], "responses": { "200": { "description": "Publish state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JourneyPublishState" } } } }, "403": { "description": "No permission to edit the journey" }, "404": { "description": "Journey versioning not enabled for the organization, or journey not found" } } } }, "/v1/journey/configuration/{id}/environment": { "get": { "operationId": "getJourneyEnvironment", "summary": "getJourneyEnvironment", "description": "Resolve the environment variables referenced by this journey. Only browser-safe value types are returned.", "security": [ { "EpilotAuth": [] } ], "tags": [ "Journeys" ], "parameters": [ { "name": "id", "in": "path", "description": "Journey ID bound to the supplied journey access token", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Resolved environment-backed datasources", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "Always private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JourneyEnvironmentResponse" } } } }, "401": { "description": "Journey access token missing" }, "403": { "description": "Journey access token does not match the journey" }, "502": { "description": "Environment resolver unavailable" } } } }, "/v1/journey/environment-variables": { "get": { "operationId": "getJourneyEnvironmentVariables", "summary": "getJourneyEnvironmentVariables", "description": "List the organization's environment variables that a journey block may use as an options source. Only Map variables that currently hold a valid value are returned. Intended for the journey builder's authoring UI; requires a journey authoring token, not an environments token.", "security": [ { "EpilotAuth": [] } ], "tags": [ "Journeys" ], "responses": { "200": { "description": "Map environment variables available as an options source", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "Always private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JourneyEnvironmentVariablesResponse" } } } }, "401": { "description": "Authorization token missing" }, "403": { "description": "Not permitted to read this organization's journeys" }, "502": { "description": "Environment resolver unavailable" } } } }, "/v1/journey/products/{id}": { "get": { "operationId": "getJourneyProducts", "summary": "getJourneyProducts", "description": "Get products available in the journey by id. requires public journey token to be passed.", "security": [ { "EpilotAuth": [] } ], "tags": [ "Journeys" ], "parameters": [ { "name": "id", "in": "path", "description": "Journey ID", "required": true, "schema": { "type": "string", "format": "uuid", "example": "509cdffe-424f-457a-95c2-9708c304ce77" } }, { "name": "source", "in": "query", "description": "What source ID. Journey or Entity ID", "required": false, "schema": { "type": "string" } }, { "name": "postal_code", "in": "query", "description": "Zip Code for availibility", "required": false, "schema": { "type": "string" } }, { "name": "city", "in": "query", "description": "city for availibility", "required": false, "schema": { "type": "string" } }, { "name": "street", "in": "query", "description": "street name for availibility", "required": false, "schema": { "type": "string" } }, { "name": "street_number", "in": "query", "description": "street number for availibility", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JourneyProductsResponse" } } } } } } }, "/v1/journey/configuration": { "post": { "operationId": "createJourney", "summary": "createJourney", "description": "Create a Journey", "tags": [ "Journeys" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JourneyCreationRequest" } } }, "description": "Payload" }, "parameters": [ { "name": "skipAutomation", "in": "query", "description": "skip creating an Automation (it takes Yn format \"true, yes, 1, y\")", "required": false, "schema": { "type": "string", "format": "Yn", "example": "true" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Journey" } } } }, "400": { "description": "Validation failed (when validation mode is STRICT)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JourneyValidationError" } } } } } }, "put": { "operationId": "updateJourney", "summary": "updateJourney", "description": "Update a Journey", "tags": [ "Journeys" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JourneyCreationRequest" } } }, "description": "Payload" }, "parameters": [], "responses": { "204": { "description": "Success", "headers": { "X-Resource-Revisions": { "schema": { "type": "integer", "minimum": 0 }, "description": "Last revisions number of the updated resource" } } }, "400": { "description": "Validation failed (when validation mode is STRICT)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JourneyValidationError" } } } }, "409": { "description": "The Journey has been modified since your last read, please refresh it and try again" } } }, "patch": { "operationId": "patchUpdateJourney", "summary": "patchUpdateJourney", "description": "Update a Journey (partially / patch). Support for nested properties updates (e.g. \"property[0].name\").", "tags": [ "Journeys" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchUpdateJourneyRequest" }, "example": { "journeyId": "509cdffe-424f-457a-95c2-9708c304ce77", "name": "New Journey Name", "steps[0].uischema.elements[0].products": [ "123456", "654321" ] } } }, "description": "Payload" }, "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JourneyResponse" } } } }, "400": { "description": "Validation failed (when validation mode is STRICT)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JourneyValidationError" } } } }, "404": { "description": "Journey or associated entity not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "journey not found" } } } } } } } } }, "/v1/journey/configuration/search": { "post": { "operationId": "searchJourneys", "summary": "searchJourneys", "description": "Search Journeys", "tags": [ "Journeys" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchJourneysQueryRequest" } } }, "description": "Payload" }, "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchJourneysResponse" } } } } } } }, "/v1/journey/document:generate": { "post": { "operationId": "generateDocument", "summary": "generateDocument", "description": "Builds document generated from a template with journey values.\"\n\nSupported input document types:\n- .docx\n\nSupported output document types:\n- .pdf\n- .docx but limited to only text based variables\n\nUses [Document API](https://gitlab.com/e-pilot/product/file-management/document-api) to generate the document.\nUses [Template Variables API](https://docs.epilot.io/api/template-variables) to replace variables in the document.\n", "security": [ {}, { "EpilotAuth": [] } ], "tags": [ "Journeys" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateDocumentRequest" } } } }, "responses": { "200": { "description": "Generated document output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateDocumentResponse" } } } } } } }, "/v2/journey/configuration": { "post": { "operationId": "createJourneyV2", "summary": "createJourneyV2", "description": "Create a Journey", "tags": [ "Journeys V2" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JourneyCreationRequestV2" } } }, "description": "Payload" }, "parameters": [ { "name": "skipAutomation", "in": "query", "description": "skip creating an Automation (it takes Yn format \"true, yes, 1, y\")", "required": false, "schema": { "type": "string", "format": "Yn", "example": "true" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JourneyCreationRequestV2" } } } }, "400": { "description": "Validation failed (when validation mode is STRICT)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JourneyValidationError" } } } } } }, "put": { "operationId": "updateJourneyV2", "summary": "updateJourneyV2", "description": "Update a Journey", "tags": [ "Journeys V2" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JourneyCreationRequestV2" } } }, "description": "Payload" }, "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JourneyCreationRequestV2" } } } }, "400": { "description": "Validation failed (when validation mode is STRICT)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JourneyValidationError" } } } }, "404": { "description": "Journey or associated entity not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "journey not found" } } } } } } } }, "patch": { "operationId": "patchUpdateJourneyV2", "summary": "patchUpdateJourneyV2", "description": "Update a Journey (partially / patch). Support for nested properties updates (e.g. \"property[0].name\").", "tags": [ "Journeys V2" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchUpdateJourneyRequest" }, "example": { "journeyId": "509cdffe-424f-457a-95c2-9708c304ce77", "name": "New Journey Name", "steps[0].uischema.elements[0].products": [ "123456", "654321" ] } } }, "description": "Payload" }, "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JourneyCreationRequestV2" } } } }, "400": { "description": "Validation failed (when validation mode is STRICT)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JourneyValidationError" } } } }, "404": { "description": "Journey or associated entity not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "journey not found" } } } } } } } } }, "/v2/journey/configuration/{id}": { "get": { "operationId": "getJourneyV2", "summary": "getJourneyV2", "description": "Get journey by id", "security": [], "tags": [ "Journeys V2" ], "parameters": [ { "name": "id", "in": "path", "description": "Journey ID", "required": true, "schema": { "type": "string", "format": "uuid", "example": "509cdffe-424f-457a-95c2-9708c304ce77" } }, { "name": "version", "in": "query", "description": "Revision row to read. `0` (default) is the journey record, the published version every customer receives; a positive integer `n` reads revision row `n` (used by config-engine for history reads). Distinct from the `revisions` counter on the body, which is the legacy change counter of the published version. Versioning metadata is only available via `publish-state`.\n", "required": false, "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/JourneyCreationRequestV2" }, { "$ref": "#/components/schemas/JourneyActivationGuarantee" } ] } } } } } }, "delete": { "operationId": "removeJourneyV2", "summary": "removeJourneyV2", "description": "Remove journey by id", "tags": [ "Journeys V2" ], "parameters": [ { "name": "id", "in": "path", "description": "Journey ID", "required": true, "schema": { "type": "string", "format": "uuid", "example": "509cdffe-424f-457a-95c2-9708c304ce77" } } ], "responses": { "200": { "description": "Success", "content": {} } } } }, "/v1/journey/{id}/settings": { "get": { "operationId": "getSettingsForJourney", "summary": "getSettingsForJourney", "description": "Get settings related to the journey using journey ID.", "tags": [ "Journeys" ], "security": [ {} ], "parameters": [ { "name": "id", "in": "path", "description": "Journey ID", "required": true, "schema": { "type": "string", "format": "uuid", "example": "509cdffe-424f-457a-95c2-9708c304ce77" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSettingsForJourney" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "journey not found" } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Unknown API Error" } } } } } } } } }, "/v1/journey/button-options": { "get": { "operationId": "getButtonOptions", "summary": "getButtonOptions", "description": "Get button options from a csv file.", "security": [ { "EpilotAuth": [] } ], "tags": [ "Journeys" ], "parameters": [ { "in": "query", "name": "fileId", "required": true, "description": "file id to get button options from", "schema": { "type": "string", "example": "535ef74a-dd66-4d01-94a9-725016e70d1c" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ButtonOption" } } } } }, "400": { "description": "Bad Request - Invalid file or content", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "UTF-8 encoding error while processing CSV content" }, "details": { "type": "string", "example": "Please ensure your CSV file is properly encoded in UTF-8 format" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "File with ID 535ef74a-dd66-4d01-94a9-725016e70d1c not found." } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Unknown API Error" } } } } } } } } } }, "components": { "schemas": { "EnvironmentMapEntry": { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string" }, "value": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "type": "string" } } ] } } }, "EnvironmentMap": { "type": "object", "required": [ "options" ], "properties": { "fallbackLanguage": { "type": "string", "default": "de" }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/EnvironmentMapEntry" } } } }, "EnvironmentLink": { "description": "One link a customer clicks. `label` and `description` are each either a\nplain string or one string per language, deciding that independently.\nMirrors environments-api's `LinkFields`.\n", "type": "object", "required": [ "url", "label" ], "properties": { "url": { "type": "string" }, "label": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "type": "string" } } ] }, "description": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "type": "string" } } ] } } }, "EnvironmentLinkList": { "description": "A list of links, served under this service's own `List` type\ntoken. environments-api types the variable `List` and declares the\nelement type inside the value; journey-api composes the two so a\nconsumer needs only one discriminant.\n", "type": "object", "required": [ "itemType", "items" ], "properties": { "itemType": { "type": "string", "enum": [ "Link" ] }, "fallbackLanguage": { "type": "string", "default": "de" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/EnvironmentLink" } } } }, "JourneyEnvironmentResponse": { "type": "object", "required": [ "items", "errors" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "datasourceId", "type", "value" ], "properties": { "datasourceId": { "type": "string" }, "type": { "type": "string", "enum": [ "Text", "Number", "Boolean", "Map", "List" ] }, "value": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "$ref": "#/components/schemas/EnvironmentMap" }, { "$ref": "#/components/schemas/EnvironmentLinkList" } ] } } } }, "errors": { "type": "array", "items": { "type": "object", "required": [ "datasourceId", "code" ], "properties": { "datasourceId": { "type": "string" }, "code": { "type": "string", "enum": [ "not_found", "unsupported_type", "not_set", "invalid_value", "incompatible_consumer" ] } } } } } }, "JourneyEnvironmentVariablesResponse": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "key", "type", "value" ], "properties": { "key": { "type": "string" }, "type": { "type": "string", "enum": [ "Map", "List" ] }, "value": { "oneOf": [ { "$ref": "#/components/schemas/EnvironmentMap" }, { "$ref": "#/components/schemas/EnvironmentLinkList" } ] }, "description": { "type": "string" } } } } } }, "GetJourneysResponse": { "type": "object" }, "JourneyResponse": { "type": "object", "properties": { "createdJourney": { "$ref": "#/components/schemas/Journey" } } }, "JourneyProductsResponse": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "_schema": { "type": "string" }, "_title": { "type": "string" }, "name": { "type": "string" }, "_id": { "type": "string" }, "_org": { "type": "string" }, "code": { "type": "string" }, "description": { "type": "string" }, "feature": { "type": "array", "items": {} }, "product_images": { "type": "array", "items": {} }, "legal_footnote": { "type": "string" }, "product_downloads": { "type": "array", "items": {} }, "price": { "type": "object" } } } }, "PatchUpdateJourneyRequest": { "type": "object", "properties": { "journeyId": { "type": "string", "format": "uuid", "example": "509cdffe-424f-457a-95c2-9708c304ce77" }, "__lastModifiedAt": { "type": "string", "description": "If passed with value of null, the API won't modify the lastModifiedAt field on updating the journey", "nullable": true } }, "additionalProperties": true, "description": "Patch request to update a journey (journey id is required) Support for nested properties (e.g. steps[0].uischema.elements[0].products) is supported.\n", "required": [ "journeyId" ] }, "JourneyCreationRequest": { "type": "object", "properties": { "journeyId": { "type": "string" }, "organizationId": { "type": "string" }, "brandId": { "type": "string" }, "name": { "type": "string" }, "steps": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "showStepName": { "type": "boolean", "nullable": true }, "title": { "type": "string", "nullable": true }, "subTitle": { "type": "string", "nullable": true }, "showStepSubtitle": { "type": "boolean", "nullable": true }, "showStepper": { "type": "boolean", "nullable": true }, "showStepperLabels": { "type": "boolean", "nullable": true }, "stepperType": { "type": "string", "enum": [ "numbers", "progress bar" ] }, "hideNextButton": { "type": "boolean", "nullable": true }, "name": { "type": "string" }, "stepId": { "type": "string" }, "schema": {}, "uischema": {}, "maxWidth": { "type": "string", "enum": [ "small", "medium", "large", "extra large" ] } }, "required": [ "name", "schema", "uischema" ] } }, "design": { "type": "object", "properties": { "logoUrl": { "type": "string", "nullable": true }, "theme": { "type": "object", "additionalProperties": {} }, "designTokens": { "type": "object" } }, "additionalProperties": false }, "rules": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "inject", "injectWithKey" ] }, "sourceType": { "type": "string", "enum": [ "journey", "step", "block" ] }, "source": { "type": "string" }, "target": { "type": "string" } }, "required": [ "type", "sourceType", "source", "target" ], "additionalProperties": false } }, "logics": { "type": "array", "items": { "type": "object", "properties": { "autoGeneratedId": { "type": "string" }, "conditions": { "type": "array", "items": { "type": "string" } }, "actions": { "type": "array", "items": { "type": "string" } } }, "required": [ "conditions", "actions" ], "additionalProperties": false } }, "logicsV4": { "type": "object", "additionalProperties": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for logic. Use uuidv7" }, "protected": { "type": "boolean", "description": "If true, logic can't be manipulated by the configuring user" }, "action": { "type": "string", "description": "Indicates which action to take in case logic evaluates to true" }, "triggeredOn": { "type": "string", "description": "Indicates when the logic should be evaluated" }, "conditions": { "type": "array", "items": { "type": "array", "items": { "type": "object", "properties": { "operator": { "type": "string", "description": "Operator to be applied between the fact value and the value" }, "functionName": { "type": "string", "description": "If operator is a custom function, this needs to be provided" }, "fact": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for a fact" }, "referenceType": { "type": "string", "description": "Indicates reference type (block or context parameter)" }, "referenceId": { "type": "string", "description": "Id of the reference" }, "path": { "type": "string", "description": "Path to a property. Used if only part of the value is needed" }, "meaning": { "type": "string", "description": "If path is a reference, indicates the intention of it" } } }, "value": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "object" }, { "type": "array", "items": {} } ] }, "args": { "type": "object" } } } } }, "settings": { "type": "object", "description": "Logic specific settings. Will vary by type of logic" } } } }, "contextSchema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the context schema item" }, "type": { "type": "string", "description": "Type of the parameter. It could be either an entity slug, or a text" }, "paramKey": { "type": "string", "description": "Expected key to be received in the context" }, "isRequired": { "type": "boolean", "description": "Indicates if a value is expected to be provided" }, "shouldLoadEntity": { "type": "boolean", "description": "If type is not text, we can instruct the journey to fetch the entity id we receive as value" }, "description": { "type": "string", "nullable": true, "maxLength": 500, "description": "Human-readable note describing the parameter's purpose. Free text; may contain newlines." } }, "required": [ "paramKey", "type" ], "additionalProperties": false } }, "journey_type": { "type": "string", "description": "Journey Template", "example": "Sales template (Premium)" }, "protected": { "type": "boolean", "description": "If true, journey is displayed in read-only mode" }, "protectedEditable": { "type": "array", "items": { "type": "string" }, "description": "Whitelist of paths that remain editable when the journey is protected. Supports wildcard patterns (e.g. steps/*/blocks/**)." }, "settings": { "type": "object", "properties": { "embedOptions": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "full-screen", "inline" ] }, "lang": { "type": "string", "example": "de" }, "width": { "type": "string" }, "topBar": { "type": "boolean" }, "scrollToTop": { "type": "boolean" }, "button": { "type": "object", "properties": { "text": { "type": "string", "nullable": true }, "align": { "type": "string", "enum": [ "left", "center", "right" ] } } } } }, "safeModeAutomation": { "type": "boolean" }, "canary": { "deprecated": true, "description": "DEPRECATED - This API will return hardcoded value of false. Please note that this field is internal to epilot and should not be used by external clients. If you wish to get the canary flag, please use the /v1/journey/{id}/settings API.", "type": "boolean" }, "designId": { "type": "string" }, "templateId": { "type": "string", "nullable": true }, "entityId": { "type": "string", "nullable": true }, "mappingsAutomationId": { "type": "string" }, "newMappings": { "description": "When true, the journey is created without a mapping config or automation; mappings are managed as advanced mappings on a lazily created automation.", "type": "boolean" }, "targetedCustomer": { "type": "string" }, "description": { "type": "string", "nullable": true }, "organizationSettings": { "type": "object", "additionalProperties": { "type": "boolean" }, "nullable": true }, "publicToken": { "type": "string", "nullable": true }, "runtimeEntities": { "type": "array", "items": { "type": "string", "enum": [ "ORDER", "OPPORTUNITY" ] } }, "filePurposes": { "type": "array", "items": { "type": "string" } }, "entityTags": { "type": "array", "items": { "type": "string" } }, "addressSuggestionsFileUrl": { "type": "string", "nullable": true, "deprecated": true, "description": "@deprecated Use addressSuggestionsFileId instead" }, "addressSuggestionsFileId": { "type": "string", "nullable": true }, "addressSuggestionsCountryCode": { "type": "string", "nullable": true, "description": "Country code for address format (e.g. DE, AT, CH, LU)" }, "addressSuggestionsEnableAutoComplete": { "type": "boolean", "description": "Whether address auto-complete is enabled" }, "addressSuggestionsSource": { "type": "array", "items": { "type": "string" }, "description": "Sources for address auto-complete (e.g. deutschePostService, customAddressesFile)" }, "addressSuggestionsEnableFreeText": { "type": "boolean", "description": "Whether free text input is allowed when auto-complete is on" }, "useNewDesign": { "type": "boolean", "deprecated": true, "description": "This property is deprecated and will be removed in a future version" }, "useAustrianLabels": { "type": "boolean", "description": "If true, some journey input labels are in Austrian format" }, "enableDarkMode": { "type": "boolean", "description": "If true, the journey shows an icon to toggle dark mode" }, "accessMode": { "type": "string", "enum": [ "PUBLIC", "PRIVATE" ] }, "authGate": { "type": "object", "description": "Steps after this step require an authenticated session (auth gate)", "required": [ "stepId" ], "properties": { "stepId": { "type": "string", "description": "The step containing the Login & Registration block" } } }, "isPublished": { "type": "boolean" }, "status": { "type": "string" }, "isActive": { "type": "boolean" }, "savingProgress": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "local", "remote", "none" ] }, "supportedRevision": { "type": "number" } } }, "thirdPartyCookies": { "type": "boolean", "description": "If false, third-party cookies are disabled to comply with GDPR regulations without asking for consent." } }, "required": [ "designId" ], "additionalProperties": false }, "validationRules": { "$ref": "#/components/schemas/ValidationRuleRef" }, "_manifest": { "type": "array", "description": "Manifest/Blueprint ID used to create/update the entity", "items": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" } }, "createdBy": { "type": "string" }, "updatedBy": { "type": "string", "nullable": true }, "__lastModifiedAt": { "type": "string", "description": "If passed with value of null, the API won't modify the lastModifiedAt field on updating the journey", "nullable": true } }, "required": [ "organizationId", "name", "steps" ], "additionalProperties": true }, "JourneyCreationRequestV2": { "type": "object", "properties": { "journeyId": { "type": "string" }, "brandId": { "type": "string" }, "name": { "type": "string" }, "steps": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "showStepName": { "type": "boolean", "nullable": true }, "title": { "type": "string", "nullable": true }, "subTitle": { "type": "string", "nullable": true }, "showStepSubtitle": { "type": "boolean", "nullable": true }, "showStepper": { "type": "boolean", "nullable": true }, "showStepperLabels": { "type": "boolean", "nullable": true }, "stepperType": { "type": "string", "enum": [ "numbers", "progress bar" ] }, "hideNextButton": { "type": "boolean", "nullable": true }, "name": { "type": "string" }, "stepId": { "type": "string" }, "schema": {}, "uischema": {}, "maxWidth": { "type": "string", "enum": [ "small", "medium", "large", "extra large" ] } }, "required": [ "name", "schema", "uischema" ] } }, "design": { "type": "object", "properties": { "logoUrl": { "type": "string", "nullable": true }, "theme": { "type": "object", "additionalProperties": {} }, "designTokens": { "type": "object" } }, "additionalProperties": false }, "rules": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "inject", "injectWithKey" ] }, "sourceType": { "type": "string", "enum": [ "journey", "step", "block" ] }, "source": { "type": "string" }, "target": { "type": "string" } }, "required": [ "type", "sourceType", "source", "target" ], "additionalProperties": false } }, "logics": { "type": "array", "items": { "type": "object", "properties": { "autoGeneratedId": { "type": "string" }, "conditions": { "type": "array", "items": { "type": "string" } }, "actions": { "type": "array", "items": { "type": "string" } } }, "required": [ "conditions", "actions" ], "additionalProperties": false } }, "logicsV4": { "type": "object", "additionalProperties": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for logic. Use uuidv7" }, "protected": { "type": "boolean", "description": "If true, logic can't be manipulated by the configuring user" }, "action": { "type": "string", "description": "Indicates which action to take in case logic evaluates to true" }, "triggeredOn": { "type": "string", "description": "Indicates when the logic should be evaluated" }, "conditions": { "type": "array", "items": { "type": "array", "items": { "type": "object", "properties": { "operator": { "type": "string", "description": "Operator to be applied between the fact value and the value" }, "functionName": { "type": "string", "description": "If operator is a custom function, this needs to be provided" }, "fact": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for a fact" }, "referenceType": { "type": "string", "description": "Indicates reference type (block or context parameter)" }, "referenceId": { "type": "string", "description": "Id of the reference" }, "path": { "type": "string", "description": "Path to a property. Used if only part of the value is needed" }, "meaning": { "type": "string", "description": "If path is a reference, indicates the intention of it" } } }, "value": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "object" }, { "type": "array", "items": {} } ] }, "args": { "type": "object" } } } } }, "settings": { "type": "object", "description": "Logic specific settings. Will vary by type of logic" } } } }, "contextSchema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the context schema item" }, "type": { "type": "string", "description": "Type of the parameter. It could be either an entity slug, or a text" }, "paramKey": { "type": "string", "description": "Expected key to be received in the context" }, "isRequired": { "type": "boolean", "description": "Indicates if a value is expected to be provided" }, "shouldLoadEntity": { "type": "boolean", "description": "If type is not text, we can instruct the journey to fetch the entity id we receive as value" }, "description": { "type": "string", "nullable": true, "maxLength": 500, "description": "Human-readable note describing the parameter's purpose. Free text; may contain newlines." } }, "required": [ "paramKey", "type" ], "additionalProperties": false } }, "journey_type": { "type": "string", "description": "Journey Template", "example": "Sales template (Premium)" }, "protected": { "type": "boolean", "description": "If true, journey is displayed in read-only mode" }, "protectedEditable": { "type": "array", "items": { "type": "string" }, "description": "Whitelist of paths that remain editable when the journey is protected. Supports wildcard patterns (e.g. steps/*/blocks/**)." }, "settings": { "type": "object", "properties": { "embedOptions": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "full-screen", "inline" ] }, "lang": { "type": "string", "example": "de" }, "width": { "type": "string" }, "topBar": { "type": "boolean" }, "scrollToTop": { "type": "boolean" }, "button": { "type": "object", "properties": { "text": { "type": "string", "nullable": true }, "align": { "type": "string", "enum": [ "left", "center", "right" ] } } } } }, "safeModeAutomation": { "type": "boolean" }, "designId": { "type": "string" }, "entityId": { "type": "string", "nullable": true }, "mappingsAutomationId": { "type": "string" }, "newMappings": { "description": "When true, the journey is created without a mapping config or automation; mappings are managed as advanced mappings on a lazily created automation.", "type": "boolean" }, "templateId": { "type": "string", "nullable": true }, "targetedCustomer": { "type": "string" }, "description": { "type": "string", "nullable": true }, "publicToken": { "type": "string", "nullable": true }, "runtimeEntities": { "type": "array", "items": { "type": "string", "enum": [ "ORDER", "OPPORTUNITY" ] } }, "filePurposes": { "type": "array", "items": { "type": "string" } }, "entityTags": { "type": "array", "items": { "type": "string" } }, "addressSuggestionsFileUrl": { "type": "string", "nullable": true, "deprecated": true, "description": "@deprecated Use addressSuggestionsFileId instead" }, "addressSuggestionsFileId": { "type": "string", "nullable": true }, "addressSuggestionsCountryCode": { "type": "string", "nullable": true, "description": "Country code for address format (e.g. DE, AT, CH, LU)" }, "addressSuggestionsEnableAutoComplete": { "type": "boolean", "description": "Whether address auto-complete is enabled" }, "addressSuggestionsSource": { "type": "array", "items": { "type": "string" }, "description": "Sources for address auto-complete (e.g. deutschePostService, customAddressesFile)" }, "addressSuggestionsEnableFreeText": { "type": "boolean", "description": "Whether free text input is allowed when auto-complete is on" }, "useNewDesign": { "type": "boolean", "deprecated": true, "description": "This property is deprecated and will be removed in a future version" }, "thirdPartyCookies": { "type": "boolean", "description": "If false, third-party cookies are disabled to comply with GDPR regulations without asking for consent." }, "accessMode": { "type": "string", "enum": [ "PUBLIC", "PRIVATE" ] }, "authGate": { "type": "object", "description": "Steps after this step require an authenticated session (auth gate)", "required": [ "stepId" ], "properties": { "stepId": { "type": "string", "description": "The step containing the Login & Registration block" } } }, "enableDarkMode": { "type": "boolean", "description": "If true, the journey shows an icon to toggle dark mode" }, "useAustrianLabels": { "type": "boolean", "description": "If true, some journey input labels are in Austrian format" }, "isActive": { "type": "boolean" }, "savingProgress": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "local", "remote", "none" ] }, "supportedRevision": { "type": "number" } } } }, "additionalProperties": false }, "validationRules": { "$ref": "#/components/schemas/ValidationRuleRef" }, "_manifest": { "type": "array", "description": "Manifest/Blueprint ID used to create/update the entity", "items": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" } } }, "required": [ "name", "steps" ] }, "SearchJourneysQueryRequest": { "type": "object", "properties": { "q": { "type": "string", "description": "Lucene query syntax\nSee https://lucene.apache.org/core/2_9_4/queryparsersyntax.html ; https://www.elastic.co/guide/en/kibana/current/lucene-query.html\n", "example": "_tags:*Flex*", "default": "*" }, "from": { "type": "integer", "description": "The offset of the first result to return.\nSee https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-from-size.html\n", "example": 0, "default": 0 }, "size": { "type": "integer", "description": "The maximum number of results to return.\nSee https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-from-size.html\n", "example": 25, "default": 25 }, "sort": { "type": "string", "description": "The sort order. Follows Lucene syntax.\n", "example": "_created_at:desc", "default": "_created_at:desc" } } }, "SearchJourneysResponse": { "type": "object", "properties": { "hits": { "type": "number", "description": "The total number of hits.\n", "example": 1 }, "results": { "type": "array", "description": "The results.\n", "items": { "type": "object", "properties": { "_id": { "type": "string", "description": "Journey Entity ID", "format": "uuid", "example": "e0f8f8f8-f8f8-f8f8-f8f8-f8f8f8f8f8f8" }, "_schema": { "type": "string", "description": "Entity Schema (journey always in this case)", "example": "journey" }, "_title": { "type": "string", "description": "Journey Entity Title", "example": "Journey Entity Title" }, "_org": { "type": "string", "description": "Organization ID", "example": "739224" }, "_created_at": { "type": "string", "format": "date-time", "example": "2020-01-01T00:00:00.000Z" }, "_updated_at": { "type": "string", "format": "date-time", "example": "2020-01-01T00:00:00.000Z" }, "_tags": { "type": "array", "items": { "type": "string", "example": "Flex" } }, "_manifest": { "type": "array", "description": "Manifest ID used to create/update the entity", "items": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" } }, "journey_name": { "type": "string", "description": "Journey Name", "example": "Journey Name" }, "journey_id": { "type": "string", "format": "uuid", "description": "Journey config ID", "example": "de7df470-253e-11ed-9174-116b8a718c0a" }, "journey_type": { "type": "string", "description": "Journey Template", "example": "Sales template" }, "design": { "type": "string", "description": "Journey Design Name", "example": "Design EPILOT" }, "created_by": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "User ID", "example": "12345" } } } }, "journey_version": { "type": "string", "description": "Journey Version", "enum": [ "Flex" ] } } } } } }, "Journey": { "allOf": [ { "$ref": "#/components/schemas/JourneyCreationRequest" }, { "$ref": "#/components/schemas/JourneyAuditInfo" }, { "$ref": "#/components/schemas/JourneyFeatureFlags" } ] }, "JourneyServedRevision": { "description": "Which revision the runtime read served: the requested one, or the published version when no revision was requested. Absent while the journey has not adopted versioning and on legacy `version` reads.\n", "type": "object", "properties": { "revision_id": { "type": "string", "example": "42" } } }, "JourneyActivationGuarantee": { "description": "Journeys read from the API always carry an explicit `settings.isActive`. The flag remains optional in request bodies.\n", "type": "object", "required": [ "settings" ], "properties": { "settings": { "type": "object", "required": [ "isActive" ], "properties": { "isActive": { "type": "boolean", "description": "Whether the journey is active (accessible to end customers)" } } } } }, "JourneyFeatureFlags": { "type": "object", "properties": { "featureFlags": { "type": "object", "additionalProperties": true } } }, "JourneyAuditInfo": { "type": "object", "properties": { "createdAt": { "type": "string" }, "lastModifiedAt": { "type": "string" }, "deletedAt": { "type": "string" }, "version": { "type": "number", "description": "Revision row number of this item. `0` is the journey record, the published version.\n" }, "revisions": { "type": "number", "description": "Legacy change counter of the published version, kept for compatibility: bumped whenever the published version changes and used for optimistic concurrency on `PUT`, by submissions (`journey_context.journey_revision`) and by save-and-continue. Saving a revision never changes it. Versioning metadata is only available via `publish-state`.\n" } }, "required": [ "createdAt", "lastModifiedAt", "version", "revisions" ] }, "JourneyRevisionRequest": { "description": "The complete journey configuration a revision is created from, same shape as the `PUT` body. Server-managed attributes of the journey record (`revisions`, `version`, publish metadata) are ignored.\n", "allOf": [ { "$ref": "#/components/schemas/JourneyCreationRequest" }, { "type": "object", "properties": { "parent_revision_id": { "type": "string", "description": "The revision the editor started from. When present and not the latest revision the save is rejected with `409`; absent skips the check.\n", "example": "41" }, "based_on_revision_id": { "type": "string", "description": "Provenance, not configuration: the revision that was loaded into the editor before this save, when it was an older one.\n", "example": "37" }, "mapping_config_version": { "type": "number", "description": "Version of the entity-mapping config stored alongside this revision. Publishing the revision points the journey's automation at it.\n", "example": 12 }, "revision_name": { "type": "string", "description": "What this save changed, for the revision history to list. Distinct from `name`, which is the journey's own name. A publish replaces it with the version name.\n", "example": "Changes to Steps and Logic" } } } ] }, "PublishRevisionRequest": { "type": "object", "required": [ "revision_id" ], "properties": { "revision_id": { "type": "string", "example": "42" }, "name": { "type": "string", "maxLength": 255, "description": "Name stamped onto the revision being published. Optional: when omitted the server generates one, so every revision that has ever been published carries a name. An omitted name never replaces a name a previous publish already set; an explicit one does.\n", "example": "Summer campaign" }, "description": { "type": "string", "maxLength": 8000, "description": "Optional description stamped onto the revision at publish time" } } }, "JourneyRevisionSummary": { "type": "object", "required": [ "revision_id", "created_at", "is_published" ], "properties": { "revision_id": { "type": "string", "description": "Opaque identifier of the revision. Moves on every save.", "example": "42" }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string", "description": "User id of the author. Absent for revisions recorded from writes without a user, e.g. blueprint installs.\n" }, "name": { "type": "string", "description": "Set at publish time only, so present if and only if this revision has been published at least once.\n", "example": "Summer campaign" }, "description": { "type": "string" }, "published_at": { "type": "string", "format": "date-time", "description": "The last time this revision was published. Not the same question as `is_published`: a revision that was the published version yesterday still carries a `published_at`.\n" }, "is_published": { "type": "boolean", "description": "Whether this revision is the published version right now." }, "mapping_config_version": { "type": "number", "description": "Version of the entity-mapping config stored alongside this revision.", "example": 12 } } }, "JourneyRevisionList": { "type": "object", "required": [ "results" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/JourneyRevisionSummary" } }, "next_cursor": { "type": "string", "description": "Opaque cursor to pass back as `cursor` to fetch the next page. Absent when the client has reached the end of the history.\n" } } }, "JourneyRevision": { "allOf": [ { "$ref": "#/components/schemas/JourneyRevisionSummary" }, { "type": "object", "required": [ "configuration" ], "properties": { "configuration": { "description": "The journey configuration as it was saved in this revision, in the shape the builder holds a journey in.\n", "allOf": [ { "$ref": "#/components/schemas/Journey" } ] } } } ] }, "JourneyRevisionConflict": { "type": "object", "required": [ "message", "latest_revision" ], "properties": { "message": { "type": "string", "example": "The journey has been saved since your editor loaded it" }, "latest_revision": { "$ref": "#/components/schemas/JourneyRevisionSummary" } } }, "JourneyPublishState": { "type": "object", "required": [ "journey_id", "published_revision_id" ], "properties": { "journey_id": { "type": "string", "format": "uuid" }, "published_revision_id": { "type": "string", "nullable": true, "description": "An explicit `null` means the journey has not adopted versioning yet: it exists, customers receive its journey record, and no revision is the published version.\n", "example": "42" }, "published_at": { "type": "string", "format": "date-time" }, "published_by": { "type": "string" } } }, "PublishResult": { "type": "object", "required": [ "revision_id", "name", "published_at", "post_publish_warnings" ], "properties": { "revision_id": { "type": "string", "example": "42" }, "name": { "type": "string", "description": "The name now on the revision: the one sent in the request, the one a previous publish set when this request omitted `name`, or the server-generated default.\n", "example": "Summer campaign" }, "published_at": { "type": "string", "format": "date-time" }, "published_by": { "type": "string" }, "post_publish_warnings": { "type": "array", "description": "Names any best-effort side effect that failed after the publish itself succeeded, e.g. the journey entity sync, so a caller can say \"published, but the entity did not update\".\n", "items": { "type": "string" } } } }, "JourneyValidationResponse": { "type": "object", "properties": { "valid": { "type": "boolean", "description": "Whether the journey configuration is valid" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Pattern type (e.g. PatternA_DotsInStepId)" }, "severity": { "type": "string", "enum": [ "critical", "high", "medium", "low" ] }, "message": { "type": "string" }, "affectedStepIds": { "type": "array", "items": { "type": "string" } }, "count": { "type": "integer" }, "autoFix": { "type": "object", "properties": { "feasible": { "type": "boolean" }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ] }, "reason": { "type": "string" }, "details": { "type": "string" } } } } }, "description": "List of detected validation errors" }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" } } }, "description": "List of warnings (non-critical issues)" } }, "required": [ "valid", "errors" ] }, "JourneyValidationError": { "type": "object", "properties": { "error": { "type": "string", "example": "ValidationError", "description": "Error type identifier" }, "message": { "type": "string", "example": "Journey configuration validation failed", "description": "High-level error message" }, "details": { "type": "array", "items": { "type": "object", "properties": { "pattern": { "type": "string", "description": "Validation pattern that failed" }, "severity": { "type": "string", "enum": [ "critical", "high", "medium", "low" ] }, "message": { "type": "string", "description": "Detailed error message" }, "count": { "type": "integer", "description": "Number of issues found" } } }, "description": "Detailed validation errors for each pattern that failed" } }, "required": [ "error", "message", "details" ] }, "S3Reference": { "type": "object", "properties": { "bucket": { "type": "string", "example": "document-api-prod" }, "key": { "type": "string", "example": "uploads/my-template.pdf" } }, "required": [ "bucket", "key" ] }, "TemplateSettings": { "type": "object", "description": "Template Settings for document generation", "properties": { "custom_margins": { "description": "Custom margins for the document", "type": "object", "properties": { "top": { "description": "Top margin in cm", "type": "number", "example": 2.54 }, "bottom": { "description": "Bottom margin in cm", "type": "number", "example": 2.54 } } }, "suggested_margins": { "description": "Suggested margins for the document", "type": "object", "properties": { "top": { "description": "Top margin in cm", "type": "number", "example": 2.54 }, "bottom": { "description": "Bottom margin in cm", "type": "number", "example": 2.54 } } }, "display_margin_guidelines": { "description": "Display margin guidelines (applicable to partial generation only)", "type": "boolean", "example": true }, "enable_data_table_margin_autofix": { "description": "Enable data table margin autofix", "type": "boolean", "example": false }, "template_with_datatable": { "description": "A flag that indicates whether the template has 1 or more data tables in it", "type": "boolean", "example": false }, "enabled_template_settings_persistence": { "description": "Enables the persistance of template settings", "type": "boolean", "example": false }, "misconfigured_margins": { "description": "An indication that the page margins are misconfigured", "type": "boolean", "example": false }, "file_entity_id": { "description": "The file entity id, used when persisting a new template version with updated settings", "type": "string", "format": "uuid", "example": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d" } } }, "GenerateDocumentResponse": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid" }, "job_status": { "description": "Status of the job", "type": "string", "enum": [ "STARTED", "PROCESSING", "SUCCESS", "FAILED" ] }, "message": { "description": "A message explaining the progress", "type": "string" }, "pdf_output": { "type": "object", "properties": { "preview_url": { "description": "Pre-signed S3 GET URL for PDF preview", "type": "string", "example": "https://document-api-prod.s3.eu-central-1.amazonaws.com/preview/my-template-OR-001.pdf" }, "output_document": { "type": "object", "properties": { "filename": { "description": "Generated document filename for PDF", "type": "string", "example": "my-template-OR-001.pdf" }, "s3ref": { "$ref": "#/components/schemas/S3Reference" } }, "example": { "s3ref": { "bucket": "document-api-preview-prod", "key": "preview/my-template.pdf" } } } } }, "docx_output": { "type": "object", "properties": { "preview_url": { "description": "Pre-signed S3 GET URL for DOCX preview", "type": "string", "example": "https://document-api-prod.s3.eu-central-1.amazonaws.com/preview/my-template-OR-001.docx" }, "output_document": { "type": "object", "properties": { "filename": { "description": "Generated document filename for DOCX", "type": "string", "example": "my-template-OR-001.docx" }, "s3ref": { "$ref": "#/components/schemas/S3Reference" } }, "example": { "s3ref": { "bucket": "document-api-preview-prod", "key": "preview/my-template.docx" } } } } }, "variable_payload": { "description": "List of variables and its corresponding replaced values from the document template", "type": "object", "properties": { "additionalProperties": { "type": "string" } } }, "template_settings": { "$ref": "#/components/schemas/TemplateSettings" } } }, "GenerateDocumentRequest": { "type": "object", "properties": { "file_id": { "description": "Entity id for the template being used", "type": "string", "example": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p" }, "context_data": { "description": "Custom values for variables in the template. Takes the higher precedence than others.", "type": "object", "properties": { "additionalProperties": { "type": "string" } } }, "context_entity_id": { "description": "Entity id used to resolve entity and relational template variables", "type": "string", "format": "uuid" }, "language": { "description": "Language code for the document", "type": "string", "example": "de" } }, "required": [ "file_id", "context_data" ] }, "GetSettingsForJourney": { "type": "object", "properties": { "organizationId": { "type": "string", "description": "ID of an organization in epilot platform", "example": "739224" }, "canary": { "type": "boolean", "description": "The canary flag controls update frequency of epilot application: when true, customers receive continuous updates; when false, they only get updates with new version releases.", "example": true }, "thirdPartyCookies": { "type": "boolean", "description": "When set to false, third-party cookies and resources should be completely disabled to comply with GDPR regulations.", "example": true } } }, "ButtonOption": { "type": "object", "description": "A single button option data", "properties": { "value": { "type": "string", "example": "Button Hidden Value", "description": "The value of the button" }, "label": { "type": "string", "example": "Button Label", "description": "The label of the button" } } }, "ValidationRuleRef": { "type": "object", "description": "References to validation rules organized by blocks and fields.\nMaps block IDs to either one or more ordered rule IDs (for block-level rules)\nor rule references (for field-level rules).\n", "additionalProperties": { "oneOf": [ { "type": "string", "description": "Rule ID for block-level validation" }, { "type": "array", "description": "Ordered rule IDs for block-level validation", "minItems": 1, "uniqueItems": true, "items": { "type": "string" } }, { "$ref": "#/components/schemas/RuleRef" } ] }, "example": { "block1": "rule123", "block2": [ "rule456", "rule789" ], "block3": { "field1": "rule101", "field2": [ "rule102", "rule103" ] } } }, "RuleRef": { "type": "object", "description": "Field-level rule references within a block.\nMaps field names to one or more ordered rule IDs.\n", "additionalProperties": { "oneOf": [ { "type": "string", "description": "Rule ID for field-level validation" }, { "type": "array", "description": "Ordered rule IDs for field-level validation", "minItems": 1, "uniqueItems": true, "items": { "type": "string" } } ] }, "example": { "firstName": "rule123", "lastName": [ "rule456", "rule789" ] } } }, "securitySchemes": { "EpilotAuth": { "type": "http", "scheme": "bearer", "description": "Epilot Authorization Bearer Token - public access token / user token", "bearerFormat": "JWT" }, "PortalAuth": { "type": "http", "scheme": "bearer", "description": "Portal Authorization Bearer Token", "bearerFormat": "JWT" } } }, "servers": [ { "url": "https://journey-config.sls.epilot.io" } ] }