For the complete documentation index, see llms.txt. This page is also available as Markdown.

REST API

The Alterations module exposes a REST API for submitting, inspecting, and dry-running alteration plans.

Plan submission and dry-run require the run:alterations permission. Reading stored plan and job status requires read:alterations.

Submit a plan

Send POST /alterations/submit with alterations plus a filter:

POST /alterations/submit HTTP/1.1
Host: localhost:5001

{
  "alterations": [
    {
      "type": "ModifyVariable",
      "variableId": "83fde420b5794bc39a0a7db725405511",
      "value": "Hello world!"
    },
    {
      "type": "Migrate",
      "targetVersion": 9
    },
    {
      "type": "ScheduleActivity",
      "activityId": "mY1rb4GRjkW3urm8dcNSog"
    }
  ],
  "filter": {
    "workflowInstanceIds": [
      "88ce68d00e824c78a53af04f16d276ea"
    ]
  }
}

The response includes the generated or accepted plan ID:

Dry-run a filter

Use POST /alterations/dry-run to see which workflow instances a filter would target without creating a plan:

Example response:

The dry-run endpoint accepts the same AlterationWorkflowInstanceFilter model that POST /alterations/submit uses inside filter. In release/3.8.0, that includes:

  • workflowInstanceIds

  • correlationIds

  • names

  • searchTerm

  • definitionIds

  • definitionVersionIds

  • statuses

  • subStatuses

  • hasIncidents

  • isSystem

  • activityFilters

  • timestampFilters

Get plan and job status

This endpoint requires read:alterations.

Use the plan ID to query the current plan and its jobs:

The response includes the stored plan and any generated jobs:

status values are serialized from Elsa's plan and job status enums. Use the plan timestamps and per-job logs to understand whether Elsa found matching instances, whether jobs have started, and which alterations succeeded or failed.

If a plan matches no workflow instances, the response still returns the stored plan, but jobs remains empty.

Last updated