Skip to main content

Journey Engine - Versions Save

Endpoint​

/i/journey-engine/versions/save

Ⓔ Enterprise Only
This API is available exclusively in Countly Enterprise.

Overview​

Create a new journey version or update blocks for an existing version.

Authentication​

  • Authentication methods:
    • API Key (parameter): api_key=YOUR_API_KEY
    • Auth Token (parameter): auth_token=YOUR_AUTH_TOKEN
    • Auth Token (header): countly-token: YOUR_AUTH_TOKEN

Permissions​

  • Required permission: Create on the journey_engine feature

Request Parameters​

Request body JSON:

  • journeyDefinitionId (required): Journey definition ID
  • appId (required): Application ID
  • name (required for create): Version name
  • blocks (required): Block graph for the version
  • _id (optional): Version ID for update case

Response​

Success Response​

{
  "_id": "67164f4a1f1bd90d6354430b",
  "journeyDefinitionId": "67164f4a1f1bd90d6354430a",
  "version": 2,
  "name": "v2",
  "status": "draft",
  "appId": "64afe321d5f9b2f77cb2c8ed",
  "blocks": [
    {
      "id": "block_1",
      "subType": "incoming-data"
    }
  ]
}

Response Fields​

FieldTypeDescription
_idStringJourney version ID
journeyDefinitionIdStringJourney definition ID
versionNumberVersion number
nameStringVersion name
statusStringVersion status
appIdStringApplication ID
blocksArrayVersion block graph

Error Responses​

  • HTTP 400
{
  "result": "Invalid request"
}
  • HTTP 500
{
  "result": "Failed to update journey version"
}
  • HTTP 500
{
  "result": "Failed to create journey version"
}

Examples​

Create new version​

POST /i/journey-engine/versions/save
Content-Type: application/json

{
  "journeyDefinitionId": "67164f4a1f1bd90d6354430a",
  "appId": "64afe321d5f9b2f77cb2c8ed",
  "name": "v2",
  "blocks": [{"id": "block_1", "subType": "incoming-data"}]
}

Update version blocks​

POST /i/journey-engine/versions/save
Content-Type: application/json

{
  "_id": "67164f4a1f1bd90d6354430b",
  "blocks": [{"id": "block_1", "subType": "incoming-data"}]
}

Behavior/Processing​

  • Parses request body JSON and returns Invalid request if it is empty.
  • If _id is provided, updates only blocks for that existing version and returns the request body.
  • If _id is not provided, creates a new version for journeyDefinitionId.
  • New version number is computed as the current maximum version number for the definition plus one.
  • New versions are always created with status draft.

Database Collections​

CollectionUsed forData touched by this endpoint
countly.journey_versionsEndpoint data sourceStores endpoint-related records this endpoint reads or modifies.
  • No related endpoints

Ⓔ Enterprise​

This feature is part of Countly Enterprise.

Get Access:

Already a Customer? Use support portal if you have any questions

Last Updated​

2026-04-18