OpsChain API (v1)

Download OpenAPI specification:

Introduction

OpsChain is an orchestration and change automation platform based in GitOps principles with a core objective to Unify Change. Connect, automate, and orchestrate people, processes, and tools across your on-premise and cloud platforms.

version: 2026-11-17 (5b38af9e1)

Projects

Endpoints to interact with projects.

Notes:

  • The show and list response payloads include links to the project's assets, changes, scheduled activity, bookmarks and MintModels endpoints. These endpoints act like the assets, changes, scheduled activity, bookmarks and MintModels endpoints respectively.
  • The list, create, show, update and archive asset endpoints are available via the /<path/to/asset/owner>/assets path. The example endpoints in this section reflect assets owned by a project.

List projects

Lists all projects (including archived projects).

Each project in the response includes a link to:

  • the project's changes endpoint for managing changes belonging to this project. It acts like the changes endpoint.
  • the project's scheduled_activities endpoint for managing scheduled activities belonging to this project. It acts like a scheduled activities endpoint.
  • the project's bookmarks endpoint for managing the bookmarks belonging to this project. It acts like a bookmarks endpoint.
  • the project's mintmodels endpoint for managing the MintModels belonging to this project. It acts like a MintModels endpoint.
  • the project's mintmodel_history endpoint for viewing this project's MintModel history. It acts like a MintModel history endpoint.
  • the project's workflows endpoint for viewing this project's workflows. It acts like a Workflows endpoint. .
query Parameters
filter[<query/sort filter>]=
string
Example: filter[<query/sort filter>]==> filter[code_eq]=opc

API filtering guide. Named filters: filter[created_by_eq], filter[created_by_in].

download
string
Example: download=projects.csv

Download the projects in CSV format with the specified file name. The projects will be ordered from oldest to newest when this parameter is specified, irrespective of the sort order requested.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e730-887b-7fae-8dab-43dd64de3697",
      • "type": "project",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true,
      • "delete": true
      }
    }
}

Create project

Creates a project.

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "code": "opc",
      • "name": "OpsChain",
      • "description": "OpsChain project"
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e730-8a36-7ebc-98a7-9fa7552e9d21",
    • "type": "project",
    • "attributes": {
      • "code": "3jpsg",
      • "name": "adipisci850",
      • "description": "Omnis culpa vel et.",
      • "archived": false,
      • "created_by": "logged_in_user",
      • "created_by_name": "logged_in_user"
      },
    • "relationships": {
      • "properties": {
        },
      • "parents": {
        },
      • "settings": {
        },
      • "children": {
        },
      • "bookmarks": {
        }
      },
    • "links": {
      • "self": "/api/projects/3jpsg",
      • "artifacts": "/api/projects/3jpsg/artifacts",
      • "bookmarks": "/api/projects/3jpsg/bookmarks",
      • "changes": "/api/projects/3jpsg/changes",
      • "scheduled_activities": "/api/projects/3jpsg/scheduled_activities",
      • "git_remotes": "/api/projects/3jpsg/git_remotes",
      • "workflows": "/api/projects/3jpsg/workflows",
      • "workflow_runs": "/api/projects/3jpsg/workflow_runs",
      • "templates": "/api/projects/3jpsg/templates",
      • "environments": "/api/projects/3jpsg/environments",
      • "assets": "/api/projects/3jpsg/assets",
      • "agents": "/api/projects/3jpsg/agents"
      },
    • "meta": {
      • "can_have_changes": true,
      • "can_have_children": true,
      • "can_have_properties": true,
      • "can_have_settings": true,
      • "can_have_templates": true,
      • "requires_template": false,
      • "child_node_types": [
        ],
      • "can_have_workflows": true,
      • "can_have_actions": false,
      • "authorisations": {
        }
      }
    }
}

Show project

Shows a project, including any direct children.

The response includes a link to:

  • the project's changes endpoint for managing changes belonging to this project. It acts like the changes endpoint.
  • the project's scheduled_activities endpoint for managing scheduled activities belonging to this project. It acts like a scheduled activities endpoint.
  • the project's bookmarks endpoint for managing the bookmarks belonging to this project. It acts like a bookmarks endpoint.
  • the project's mintmodels endpoint for managing the MintModels belonging to this project. It acts like a MintModels endpoint.
  • the project's mintmodel_history endpoint for viewing this project's MintModel history. It acts like a MintModel history endpoint.
  • the project's workflows endpoint for viewing this project's workflows. It acts like a Workflows endpoint. .
path Parameters
project_code
required
string
Example: opc

project code

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e730-8e94-7974-b682-dbc2b5b65bcc",
    • "type": "project",
    • "attributes": {
      • "code": "opc",
      • "name": "OpsChain",
      • "description": "OpsChain project",
      • "archived": false,
      • "created_by": "honey.kilback-3011",
      • "created_by_name": "honey.kilback-3011"
      },
    • "relationships": {
      • "properties": {
        },
      • "parents": {
        },
      • "settings": {
        },
      • "children": {
        },
      • "bookmarks": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc",
      • "artifacts": "/api/projects/opc/artifacts",
      • "bookmarks": "/api/projects/opc/bookmarks",
      • "changes": "/api/projects/opc/changes",
      • "scheduled_activities": "/api/projects/opc/scheduled_activities",
      • "git_remotes": "/api/projects/opc/git_remotes",
      • "workflows": "/api/projects/opc/workflows",
      • "workflow_runs": "/api/projects/opc/workflow_runs",
      • "templates": "/api/projects/opc/templates",
      • "environments": "/api/projects/opc/environments",
      • "assets": "/api/projects/opc/assets",
      • "agents": "/api/projects/opc/agents"
      },
    • "meta": {
      • "can_have_changes": true,
      • "can_have_children": true,
      • "can_have_properties": true,
      • "can_have_settings": true,
      • "can_have_templates": true,
      • "requires_template": false,
      • "child_node_types": [
        ],
      • "can_have_workflows": true,
      • "can_have_actions": false,
      • "authorisations": {
        },
      • "secret_vault": {
        }
      }
    },
  • "included": [ ]
}

Update project

Updates a project.

path Parameters
project_code
required
string
Example: opc

project code

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "name": "Modified",
      • "description": "The updated project",
      • "archived": false
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e730-910d-775c-9343-1c9705abef9a",
    • "type": "project",
    • "attributes": {
      • "code": "opc",
      • "name": "veritatis862",
      • "description": "Quisquam et vel ut.",
      • "archived": true,
      • "created_by": "dusty-3017",
      • "created_by_name": "dusty-3017"
      },
    • "relationships": {
      • "properties": {
        },
      • "parents": {
        },
      • "settings": {
        },
      • "children": {
        },
      • "bookmarks": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc",
      • "artifacts": "/api/projects/opc/artifacts",
      • "bookmarks": "/api/projects/opc/bookmarks",
      • "changes": "/api/projects/opc/changes",
      • "scheduled_activities": "/api/projects/opc/scheduled_activities",
      • "git_remotes": "/api/projects/opc/git_remotes",
      • "workflows": "/api/projects/opc/workflows",
      • "workflow_runs": "/api/projects/opc/workflow_runs",
      • "templates": "/api/projects/opc/templates",
      • "environments": "/api/projects/opc/environments",
      • "assets": "/api/projects/opc/assets",
      • "agents": "/api/projects/opc/agents"
      },
    • "meta": {
      • "can_have_changes": true,
      • "can_have_children": true,
      • "can_have_properties": true,
      • "can_have_settings": true,
      • "can_have_templates": true,
      • "requires_template": false,
      • "child_node_types": [
        ],
      • "can_have_workflows": true,
      • "can_have_actions": false,
      • "authorisations": {
        }
      }
    }
}

Archive project

Archives a project.

path Parameters
project_code
required
string
Example: opc

project code

query Parameters
ignore_in_use
boolean

When true and the requesting user is a superuser, bypasses in use checks and force-destroys the project.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    • {
      • "status": 403,
      • "title": "You do not have permission to delete the project",
      • "detail": "Your authorisation rules let you view the project but not delete it."
      }
    ]
}

Environments

Endpoints to interact with environments.

Notes:

  • The show and list response payloads include links to the environment's assets, changes, scheduled activity, bookmarks and MintModels endpoints. These endpoints act like the assets, changes, scheduled activity, bookmarks and MintModels endpoints respectively.
  • The list, create, show, update and archive asset endpoints are available via the /<path/to/asset/owner>/assets path. The example endpoints in this section reflect assets owned by a project.

List environments

Lists all project environments (including archived environments).

Each environment in the response includes a link to:

  • the environment's changes endpoint for managing changes belonging to this environment. It acts like the changes endpoint.
  • the environment's scheduled_activities endpoint for managing scheduled activities belonging to this environment. It acts like a scheduled activities endpoint.
  • the environment's bookmarks endpoint for managing the bookmarks belonging to this environment. It acts like a bookmarks endpoint.
  • the environment's mintmodels endpoint for managing the MintModels belonging to this environment. It acts like a MintModels endpoint.
  • the environment's mintmodel_history endpoint for viewing this environment's MintModel history. It acts like a MintModel history endpoint.
  • the environment's workflows endpoint for viewing this environment's workflows. It acts like a Workflows endpoint. .
path Parameters
project_code
required
string
Example: opc

project code

query Parameters
filter[<query/sort filter>]=
string
Example: filter[<query/sort filter>]==> filter[name_eq]=Test

API filtering guide. Named filters: filter[created_by_eq], filter[created_by_in].

download
string
Example: download=environments.csv

Download the project environments in CSV format with the specified file name. The environments will be ordered from oldest to newest when this parameter is specified, irrespective of the sort order requested.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e72f-e97d-75e7-833d-ab537f3323ee",
      • "type": "environment",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true,
      • "delete": true
      }
    }
}

Create environment

Creates an environment.

path Parameters
project_code
required
string
Example: opc

project code

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "code": "dev",
      • "name": "Development",
      • "description": "OpsChain development environment"
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72f-f000-76c8-a6ba-d536f663dcfd",
    • "type": "environment",
    • "attributes": {
      • "code": "u2u1i",
      • "name": "debitis756",
      • "description": "Explicabo numquam aut voluptatem.",
      • "archived": false,
      • "created_by": "logged_in_user",
      • "created_by_name": "logged_in_user"
      },
    • "relationships": {
      • "properties": {
        },
      • "parents": {
        },
      • "settings": {
        },
      • "parent": {
        },
      • "project": {
        },
      • "children": {
        },
      • "bookmarks": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/environments/u2u1i",
      • "artifacts": "/api/projects/opc/environments/u2u1i/artifacts",
      • "bookmarks": "/api/projects/opc/environments/u2u1i/bookmarks",
      • "changes": "/api/projects/opc/environments/u2u1i/changes",
      • "scheduled_activities": "/api/projects/opc/environments/u2u1i/scheduled_activities",
      • "parent": "/api/projects/opc",
      • "assets": "/api/projects/opc/environments/u2u1i/assets"
      },
    • "meta": {
      • "can_have_changes": true,
      • "can_have_children": true,
      • "can_have_properties": true,
      • "can_have_settings": true,
      • "can_have_templates": false,
      • "requires_template": false,
      • "child_node_types": [
        ],
      • "can_have_workflows": false,
      • "can_have_actions": false,
      • "authorisations": {
        }
      }
    }
}

Show environment

Shows an environment.

The response includes a link to:

  • the environment's changes endpoint for managing changes belonging to this environment. It acts like the changes endpoint.
  • the environment's scheduled_activities endpoint for managing scheduled activities belonging to this environment. It acts like a scheduled activities endpoint.
  • the environment's bookmarks endpoint for managing the bookmarks belonging to this environment. It acts like a bookmarks endpoint.
  • the environment's mintmodels endpoint for managing the MintModels belonging to this environment. It acts like a MintModels endpoint.
  • the environment's mintmodel_history endpoint for viewing this environment's MintModel history. It acts like a MintModel history endpoint.
  • the environment's workflows endpoint for viewing this environment's workflows. It acts like a Workflows endpoint. .
path Parameters
project_code
required
string
Example: opc

project code

environment_code
required
string
Example: dev

environment code

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72f-faa6-7715-ae14-de684ab4e836",
    • "type": "environment",
    • "attributes": {
      • "code": "dev",
      • "name": "Development",
      • "description": "OpsChain development environment",
      • "archived": false,
      • "created_by": "abram_gulgowski-2598",
      • "created_by_name": "abram_gulgowski-2598"
      },
    • "relationships": {
      • "properties": {
        },
      • "parents": {
        },
      • "settings": {
        },
      • "parent": {
        },
      • "project": {
        },
      • "children": {
        },
      • "bookmarks": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/environments/dev",
      • "artifacts": "/api/projects/opc/environments/dev/artifacts",
      • "bookmarks": "/api/projects/opc/environments/dev/bookmarks",
      • "changes": "/api/projects/opc/environments/dev/changes",
      • "scheduled_activities": "/api/projects/opc/environments/dev/scheduled_activities",
      • "parent": "/api/projects/opc",
      • "assets": "/api/projects/opc/environments/dev/assets"
      },
    • "meta": {
      • "can_have_changes": true,
      • "can_have_children": true,
      • "can_have_properties": true,
      • "can_have_settings": true,
      • "can_have_templates": false,
      • "requires_template": false,
      • "child_node_types": [
        ],
      • "can_have_workflows": false,
      • "can_have_actions": false,
      • "authorisations": {
        },
      • "secret_vault": {
        }
      }
    },
  • "included": [
    • {
      • "id": "01a1e72f-fa70-7025-8ed8-4e98ad1acc82",
      • "type": "project",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": {
        }
      }
    ]
}

Update environment

Updates an environment.

path Parameters
project_code
required
string
Example: opc

project code

environment_code
required
string
Example: dev

environment code

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "name": "Modified",
      • "description": "The updated environment",
      • "archived": false
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72f-fd72-795c-a689-6adc8338dde2",
    • "type": "environment",
    • "attributes": {
      • "code": "dev",
      • "name": "veniam770",
      • "description": "Placeat unde voluptatem beatae.",
      • "archived": true,
      • "created_by": "america.kris-2606",
      • "created_by_name": "america.kris-2606"
      },
    • "relationships": {
      • "properties": {
        },
      • "parents": {
        },
      • "settings": {
        },
      • "parent": {
        },
      • "project": {
        },
      • "children": {
        },
      • "bookmarks": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/environments/dev",
      • "artifacts": "/api/projects/opc/environments/dev/artifacts",
      • "bookmarks": "/api/projects/opc/environments/dev/bookmarks",
      • "changes": "/api/projects/opc/environments/dev/changes",
      • "scheduled_activities": "/api/projects/opc/environments/dev/scheduled_activities",
      • "parent": "/api/projects/opc",
      • "assets": "/api/projects/opc/environments/dev/assets"
      },
    • "meta": {
      • "can_have_changes": true,
      • "can_have_children": true,
      • "can_have_properties": true,
      • "can_have_settings": true,
      • "can_have_templates": false,
      • "requires_template": false,
      • "child_node_types": [
        ],
      • "can_have_workflows": false,
      • "can_have_actions": false,
      • "authorisations": {
        }
      }
    }
}

Archive environment

Archives an environment.

path Parameters
project_code
required
string
Example: opc

project code

environment_code
required
string
Example: dev

environment code

query Parameters
ignore_in_use
boolean

When true and the requesting user is a superuser, bypasses in use checks and force-destroys the environment.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    • {
      • "status": 403,
      • "title": "You do not have permission to delete the environment",
      • "detail": "Your authorisation rules let you view the environment but not delete it."
      }
    ]
}

Show converged settings

Show the converged settings for this environment, merged from the project and environment settings. Unless include_global=true is passed, only the values that differ from the global settings are returned: a setting whose converged value matches the global value is omitted, even when it is set directly on a node, so the response is empty when nothing differs from the global settings.

The response includes a setting_sources meta object that attributes each setting value to its originating source.

path Parameters
project_code
required
string
Example: opc

project code

environment_code
required
string
Example: dev

environment code

query Parameters
include_global
boolean
Example: include_global=true

Also return the settings whose converged value matches the global settings

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "dev",
    • "type": "converged_settings",
    • "attributes": {
      • "data": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/environments/dev/converged_settings"
      },
    • "meta": {
      • "setting_sources": {
        }
      }
    }
}

Show converged properties

Show the converged properties for this environment, merged from all database properties sources in the hierarchy (project and environment properties).

The API response will also include the individual database properties that were included in the result.

path Parameters
project_code
required
string
Example: opc

project code

environment_code
required
string
Example: dev

environment code

query Parameters
converge_date
string
Example: converge_date=2026-11-17T01:42:02+00:00

Specify the date (and optionally time), to derive the active environment properties from.

exclude_layers[]
string
Example: exclude_layers[]=template

Exclude a property layer from the converged result. Repeat the parameter to exclude several layers, e.g. > exclude_layers[]=template&exclude_layers[]=asset. Suffix a layer with _repository or _database to exclude only that half of it, e.g. > exclude_layers[]=asset_repository. The layers available for the node, and whether each one is currently included, are listed in the property_layers response meta. The template layer covers the properties files held under the <template code> folder of the template repository, as well as the template's database properties; the template_version layer covers the template version database properties only. Excluding a layer is a preview - the result is not cached and nothing is persisted.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "dev",
    • "type": "converged_properties",
    • "attributes": {
      • "data": {
        }
      },
    • "relationships": {
      • "repository_properties": {
        },
      • "properties": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/environments/dev/converged_properties"
      },
    • "meta": {
      • "property_sources": {
        },
      • "property_layers": [
        ]
      }
    },
  • "included": [
    • {
      • "id": "01a1e730-0cbd-74d9-b1b6-4137cdfbca25",
      • "type": "properties_version",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": { }
      },
    • {
      • "id": "01a1e730-0e3d-73c4-a810-cbbc49fff79e",
      • "type": "properties_version",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": { }
      }
    ]
}

Agents

Endpoints to interact with agents.

Notes:

  • The show and list response payloads include links to the agent's assets, changes, scheduled activity, bookmarks and MintModels endpoints. These endpoints act like the assets, changes, scheduled activity, bookmarks and MintModels endpoints respectively.
  • The list, create, show, update and archive asset endpoints are available via the /<path/to/asset/owner>/assets path. The example endpoints in this section reflect assets owned by a project.

Build agent image

Builds the container image for an agent. Note, this does not restart the agent.

path Parameters
project_code
required
string
Example: opc

project code

agent_code
required
string
Example: agent1

agent code

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72b-7982-7347-8854-58a43de3b00c",
    • "type": "node_background_task",
    • "attributes": {
      • "request_number": 2,
      • "status_code": "initializing",
      • "error_message": null,
      • "created_by": "logged_in_user",
      • "created_by_name": "logged_in_user",
      • "task_type": "BuildAgentImageTask",
      • "created_at": "2026-11-17T01:42:28.481043Z",
      • "updated_at": "2026-11-17T01:42:28.481043Z",
      • "image_sha": null,
      • "image_purged": false,
      • "image_in_use": false
      },
    • "relationships": {
      • "template_version_history": {
        },
      • "owner": {
        }
      },
    • "links": {
      • "template_version": "/api/projects/opc/templates/01a1e72b-782e-7465-8cae-fd71b9a25cdb/versions/2026_Q1_2",
      • "self": "/api/projects/opc/agents/agent1/node_background_tasks/01a1e72b-7982-7347-8854-58a43de3b00c",
      • "agent": "/api/projects/opc/agents/agent1",
      • "log_lines": "/api/node_background_task_log_lines?node_background_task_id=01a1e72b-7982-7347-8854-58a43de3b00c"
      }
    }
}

List agent background tasks

Lists the image build, start and stop tasks run for the agent's current template version.

path Parameters
project_code
required
string
Example: opc

project code

agent_code
required
string
Example: agent1

agent code

query Parameters
filter[<query/sort filter>]=
string
Example: filter[<query/sort filter>]==> filter[request_number_eq]=1

API filtering guide. Named filters: filter[created_by_eq], filter[created_by_in].

limit
integer [ 1 .. 10000 ]
Default: 100
Example: limit=50

Limit the number of tasks returned. When more records match than the limit a 206 response is returned and meta.partial_response is true.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e72b-7f85-7ed0-b982-7d0238c56ed1",
      • "type": "node_background_task",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true,
      • "delete": true
      },
    • "partial_response": false
    }
}

Show agent background task

Show a specific agent image build, start or stop task.

path Parameters
project_code
required
string
Example: opc

project code

agent_code
required
string
Example: agent1

agent code

node_background_task_id
required
string
Example: 01a1e72a-f74f-712d-85fc-66e4e50bffa7

agent background task id

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72b-825e-74ed-b592-a2cf11f01f5c",
    • "type": "node_background_task",
    • "attributes": {
      • "request_number": 1,
      • "status_code": "success",
      • "error_message": null,
      • "created_by": "bryon-377",
      • "created_by_name": "bryon-377",
      • "task_type": "BuildAgentImageTask",
      • "created_at": "2026-11-17T01:42:30.749227Z",
      • "updated_at": "2026-11-17T01:42:30.763617Z",
      • "image_sha": "sha256:7655e0d4a9fe96130dc9e62dd8d85536e3ba743398d5e5ba5801a9fb0bbd2082",
      • "image_purged": false,
      • "image_in_use": true
      },
    • "relationships": {
      • "template_version_history": {
        },
      • "owner": {
        }
      },
    • "links": {
      • "template_version": "/api/projects/opc/templates/01a1e72b-8161-7619-aa70-d0482fcc7704/versions/2026_Q1_2",
      • "self": "/api/projects/opc/agents/agent1/node_background_tasks/01a1e72b-825e-74ed-b592-a2cf11f01f5c",
      • "agent": "/api/projects/opc/agents/agent1",
      • "log_lines": "/api/node_background_task_log_lines?node_background_task_id=01a1e72b-825e-74ed-b592-a2cf11f01f5c"
      }
    }
}

Show agent status

Shows the status for an agent.

path Parameters
project_code
required
string
Example: opc

project code

agent_code
required
string
Example: agent1

agent code

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72b-849d-786d-ac7b-e184ad95dccf",
    • "type": "agent_status",
    • "attributes": {
      • "desired_status": "running",
      • "status": "initializing",
      • "image_build_status": "ready",
      • "active_image_sha": null,
      • "newest_image_sha": "sha256:7655e0d4a9fe96130dc9e62dd8d85536e3ba743398d5e5ba5801a9fb0bbd2082",
      • "cluster_name": "opschain-db",
      • "failure_reason": null
      },
    • "relationships": {
      • "node": {
        },
      • "referenced_build_agent_image_task": {
        },
      • "available_build_agent_image_tasks": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/agents/agent1/status",
      • "log_lines": "/api/projects/opc/agents/agent1/status/log_lines"
      }
    },
  • "included": [
    • {
      • "id": "01a1e72b-849b-7a9f-b14d-2b3bd634ce12",
      • "type": "node_background_task",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      }
    ]
}

Update agent status

Update an agent status.

path Parameters
project_code
required
string
Example: opc

project code

agent_code
required
string
Example: agent1

agent code

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "desired_status": "running",
      • "image_sha": "sha256:de10faf919fc71ba4eb1dd7bd6449566d012b0c9436b1c61bfee21d621b009aa"
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72b-86b1-7514-94a6-cd6341532744",
    • "type": "agent_status",
    • "attributes": {
      • "desired_status": "running",
      • "status": "initializing",
      • "image_build_status": "ready",
      • "active_image_sha": null,
      • "newest_image_sha": "sha256:7655e0d4a9fe96130dc9e62dd8d85536e3ba743398d5e5ba5801a9fb0bbd2082",
      • "cluster_name": "opschain-db",
      • "failure_reason": null
      },
    • "relationships": {
      • "node": {
        },
      • "referenced_build_agent_image_task": {
        },
      • "available_build_agent_image_tasks": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/agents/agent1/status",
      • "log_lines": "/api/projects/opc/agents/agent1/status/log_lines"
      }
    },
  • "included": [
    • {
      • "id": "01a1e72b-86af-74cd-9498-992ce4e4c273",
      • "type": "node_background_task",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      }
    ]
}

Show agent log lines

Shows log lines for the agent.

path Parameters
project_code
required
string
Example: opc

project code

agent_code
required
string
Example: agent1

agent code

query Parameters
filter[<query/sort filter>]=
string
Example: filter[<query/sort filter>]==> filter[message_cont]=dolorem
limit
integer [ 1 .. 10000 ]
Default: 10000
Example: limit=50

Limit the number of log lines returned. When more records match than the limit a 206 response is returned and meta.partial_response is true.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e72b-92b5-7420-a2ca-4330dd7a64dd",
      • "type": "agent_log_line",
      • "attributes": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true
      },
    • "partial_response": false
    }
}

Show agent Kubernetes events

Shows Kubernetes events for the agent. When the agent is not deployed in Kubernetes, the list is empty and meta.agent_deployed is false.

path Parameters
project_code
required
string
Example: opc

project code

agent_code
required
string
Example: agent1

agent code

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "0",
      • "type": "agent_event",
      • "attributes": {
        }
      }
    ],
  • "meta": {
    • "agent_deployed": true
    }
}

List agents

Lists all agents (including archived agents) that belong to the project.

Each agent in the response includes a link to:

  • the agent's changes endpoint for managing changes belonging to this agent. It acts like the changes endpoint.
  • the agent's scheduled_activities endpoint for managing scheduled activities belonging to this agent. It acts like a scheduled activities endpoint.
  • the agent's bookmarks endpoint for managing the bookmarks belonging to this agent. It acts like a bookmarks endpoint.
  • the agent's mintmodels endpoint for managing the MintModels belonging to this agent. It acts like a MintModels endpoint.
  • the agent's mintmodel_history endpoint for viewing this agent's MintModel history. It acts like a MintModel history endpoint.
  • the agent's workflows endpoint for viewing this agent's workflows. It acts like a Workflows endpoint. .
path Parameters
project_code
required
string
Example: opc

project code

query Parameters
filter[<query/sort filter>]=
string
Example: filter[<query/sort filter>]==> filter[name_eq]=Test

API filtering guide. Named filters: filter[created_by_eq], filter[created_by_in].

download
string
Example: download=agents.csv

Download the agents in CSV format with the specified file name. The agents will be ordered from oldest to newest when this parameter is specified, irrespective of the sort order requested.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e72f-6c30-79ce-8722-367df0b05cd4",
      • "type": "agent",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true,
      • "delete": true
      }
    }
}

Create agent

Creates an agent.

path Parameters
project_code
required
string
Example: opc

project code

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "code": "agent1",
      • "name": "Agent",
      • "description": "Asset description",
      • "template_code": "agn",
      • "template_version": "2026_Q1_2"
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72f-7153-722b-8b76-e8339d351970",
    • "type": "agent",
    • "attributes": {
      • "code": "huydk",
      • "name": "asperiores654",
      • "description": "Illo in culpa et.",
      • "archived": false,
      • "created_by": "logged_in_user",
      • "created_by_name": "logged_in_user",
      • "task_active": true
      },
    • "relationships": {
      • "properties": {
        },
      • "parents": {
        },
      • "settings": {
        },
      • "parent": {
        },
      • "project": {
        },
      • "template_version": {
        },
      • "bookmarks": {
        },
      • "template": {
        },
      • "latest_node_background_tasks": {
        },
      • "agent_status": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/agents/huydk",
      • "bookmarks": "/api/projects/opc/agents/huydk/bookmarks",
      • "converged_properties": "/api/projects/opc/agents/huydk/converged_properties",
      • "parent": "/api/projects/opc",
      • "node_background_tasks": "/api/projects/opc/agents/huydk/node_background_tasks",
      • "version_history": "/api/projects/opc/agents/huydk/version_history"
      },
    • "meta": {
      • "can_have_changes": false,
      • "can_have_children": false,
      • "can_have_properties": true,
      • "can_have_settings": true,
      • "can_have_templates": false,
      • "requires_template": true,
      • "child_node_types": [ ],
      • "can_have_workflows": false,
      • "can_have_actions": false,
      • "authorisations": {
        }
      }
    }
}

Show agent

Shows an agent belonging to a project.

The response includes a link to:

  • the agent's changes endpoint for managing changes belonging to this agent. It acts like the changes endpoint.
  • the agent's scheduled_activities endpoint for managing scheduled activities belonging to this agent. It acts like a scheduled activities endpoint.
  • the agent's bookmarks endpoint for managing the bookmarks belonging to this agent. It acts like a bookmarks endpoint.
  • the agent's mintmodels endpoint for managing the MintModels belonging to this agent. It acts like a MintModels endpoint.
  • the agent's mintmodel_history endpoint for viewing this agent's MintModel history. It acts like a MintModel history endpoint.
  • the agent's workflows endpoint for viewing this agent's workflows. It acts like a Workflows endpoint. .
path Parameters
project_code
required
string
Example: opc

project code

agent_code
required
string
Example: agent1

agent code

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72f-7a63-7627-87c2-60a052451383",
    • "type": "agent",
    • "attributes": {
      • "code": "agent1",
      • "name": "Agent",
      • "description": "Asset description",
      • "archived": false,
      • "created_by": "shane_west-2289",
      • "created_by_name": "shane_west-2289",
      • "task_active": false
      },
    • "relationships": {
      • "properties": {
        },
      • "parents": {
        },
      • "settings": {
        },
      • "parent": {
        },
      • "project": {
        },
      • "template_version": {
        },
      • "bookmarks": {
        },
      • "template": {
        },
      • "latest_node_background_tasks": {
        },
      • "agent_status": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/agents/agent1",
      • "bookmarks": "/api/projects/opc/agents/agent1/bookmarks",
      • "converged_properties": "/api/projects/opc/agents/agent1/converged_properties",
      • "parent": "/api/projects/opc",
      • "node_background_tasks": "/api/projects/opc/agents/agent1/node_background_tasks",
      • "version_history": "/api/projects/opc/agents/agent1/version_history"
      },
    • "meta": {
      • "can_have_changes": false,
      • "can_have_children": false,
      • "can_have_properties": true,
      • "can_have_settings": true,
      • "can_have_templates": false,
      • "requires_template": true,
      • "child_node_types": [ ],
      • "can_have_workflows": false,
      • "can_have_actions": false,
      • "authorisations": {
        },
      • "secret_vault": {
        }
      }
    },
  • "included": [
    • {
      • "id": "01a1e72f-7969-75e1-bca0-5bca4fb6d641",
      • "type": "project",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": {
        }
      },
    • {
      • "id": "01a1e72f-79b0-7e50-80d9-39ca8cb29483",
      • "type": "template",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e72f-79ed-7143-8d79-2b6b35fa5db3",
      • "type": "template_version",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e72f-7a92-7405-90ae-2e4d629ff4dd",
      • "type": "node_background_task",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e72f-7a94-753e-9d3e-d6fa29633589",
      • "type": "agent_status",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      }
    ]
}

Update agent

Updates an agent belonging to a project.

path Parameters
project_code
required
string
Example: opc

project code

agent_code
required
string
Example: agent1

agent code

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "name": "Modified",
      • "description": "The updated agent",
      • "archived": false
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72f-7fb5-7fbd-92c8-6eb7bcfdd8e6",
    • "type": "agent",
    • "attributes": {
      • "code": "agent1",
      • "name": "soluta668",
      • "description": "Velit delectus impedit ut.",
      • "archived": true,
      • "created_by": "hailey.adams-2298",
      • "created_by_name": "hailey.adams-2298",
      • "task_active": false
      },
    • "relationships": {
      • "properties": {
        },
      • "parents": {
        },
      • "settings": {
        },
      • "parent": {
        },
      • "project": {
        },
      • "template_version": {
        },
      • "bookmarks": {
        },
      • "template": {
        },
      • "latest_node_background_tasks": {
        },
      • "agent_status": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/agents/agent1",
      • "bookmarks": "/api/projects/opc/agents/agent1/bookmarks",
      • "converged_properties": "/api/projects/opc/agents/agent1/converged_properties",
      • "parent": "/api/projects/opc",
      • "node_background_tasks": "/api/projects/opc/agents/agent1/node_background_tasks",
      • "version_history": "/api/projects/opc/agents/agent1/version_history"
      },
    • "meta": {
      • "can_have_changes": false,
      • "can_have_children": false,
      • "can_have_properties": true,
      • "can_have_settings": true,
      • "can_have_templates": false,
      • "requires_template": true,
      • "child_node_types": [ ],
      • "can_have_workflows": false,
      • "can_have_actions": false,
      • "authorisations": {
        }
      }
    }
}

Archive agent

Archives an agent belonging to a project.

path Parameters
project_code
required
string
Example: opc

project code

agent_code
required
string
Example: agent1

agent code

query Parameters
ignore_in_use
boolean

When true and the requesting user is a superuser, bypasses in use checks and force-destroys the agent.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    • {
      • "status": 403,
      • "title": "You do not have permission to delete the agent",
      • "detail": "Your authorisation rules let you view the agent but not delete it."
      }
    ]
}

Show converged settings

Show the converged settings for this agent, merged from the project and agent settings. Unless include_global=true is passed, only the values that differ from the global settings are returned: a setting whose converged value matches the global value is omitted, even when it is set directly on a node, so the response is empty when nothing differs from the global settings.

The response includes a setting_sources meta object that attributes each setting value to its originating source.

path Parameters
project_code
required
string
Example: opc

project code

agent_code
required
string
Example: agent1

agent code

query Parameters
include_global
boolean
Example: include_global=true

Also return the settings whose converged value matches the global settings

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "agent1",
    • "type": "converged_settings",
    • "attributes": {
      • "data": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/agents/agent1/converged_settings"
      },
    • "meta": {
      • "setting_sources": {
        }
      }
    }
}

Show converged properties

Show the converged properties as they will appear for this agent. i.e. the endpoint will

  1. merge any template (repository) properties from the agent's template (in the order described in the documentation)
  2. merge any project properties
  3. merge any properties assigned to the agent

The API response will also include all the individual repository and database properties that were included in the result.

path Parameters
project_code
required
string
Example: opc

project code

agent_code
required
string
Example: agent1

agent code

query Parameters
converge_date
string
Example: converge_date=2026-11-17T01:42:02+00:00

Specify the date (and optionally time), to derive the active template version and agent properties from.

exclude_layers[]
string
Example: exclude_layers[]=template

Exclude a property layer from the converged result. Repeat the parameter to exclude several layers, e.g. > exclude_layers[]=template&exclude_layers[]=asset. Suffix a layer with _repository or _database to exclude only that half of it, e.g. > exclude_layers[]=asset_repository. The layers available for the node, and whether each one is currently included, are listed in the property_layers response meta. The template layer covers the properties files held under the <template code> folder of the template repository, as well as the template's database properties; the template_version layer covers the template version database properties only. Excluding a layer is a preview - the result is not cached and nothing is persisted.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "agent1",
    • "type": "converged_properties",
    • "attributes": {
      • "data": {
        }
      },
    • "relationships": {
      • "repository_properties": {
        },
      • "properties": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/agents/agent1/converged_properties"
      },
    • "meta": {
      • "property_sources": {
        },
      • "property_layers": [
        ]
      }
    },
  • "included": [
    • {
      • "id": "01a1e72f-9355-75c9-b7d6-045ae52c26bd",
      • "type": "properties_version",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": { }
      },
    • {
      • "id": "01a1e72f-9390-7efd-b838-70ca44d99795",
      • "type": "properties_version",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": { }
      },
    • {
      • "id": "01a1e72f-945f-775a-9fbf-5c8c827a3289",
      • "type": "properties_version",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": {
        }
      },
    • {
      • "id": "01a1e72f-94be-7757-b250-9111c77a1be6",
      • "type": "properties_version",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": {
        }
      },
    • {
      • "id": "properties/properties.yaml",
      • "type": "repository_properties",
      • "attributes": {
        },
      • "links": {
        }
      },
    • {
      • "id": "properties/projects/opc/properties.yaml",
      • "type": "repository_properties",
      • "attributes": {
        },
      • "links": {
        }
      }
    ]
}

Assets

Endpoints to interact with assets.

Notes:

  • The show and list response payloads include links to the asset's changes, scheduled activity, bookmarks and MintModels endpoints. These endpoints act like the changes, scheduled activity, bookmarks and MintModels endpoints respectively.
  • The list, create, show, update and archive asset endpoints are available via the /<path/to/asset/owner>/assets path. The example endpoints in this section reflect assets owned by a project.

List asset summaries

Lists a summary of each asset accessible to the user, combining the asset with its project, environment, template, template version, background task and latest change details.

Notes:

  1. Exactly one of filter[parent_path_eq] or filter[template_version_id_eq] must be supplied. filter[parent_path_eq] lists the assets directly under a project or environment, and filter[template_version_id_eq] lists the assets using a template version, across every project the user can access.
  2. Each asset's meta.authorisations reports what the user may do to that asset.
  3. The top level meta.authorisations reports whether the user may create (update) or delete assets under the parent, and is only returned for a filter[parent_path_eq] request.
query Parameters
required
object

API filtering guide Exactly one of filter[parent_path_eq] or filter[template_version_id_eq] is required.

download
string
Example: download=assets.csv

Download the asset summaries in CSV format with the specified file name.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e72c-138d-7454-b5dd-bc1097648113",
      • "type": "asset",
      • "attributes": {
        },
      • "links": {
        },
      • "meta": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true,
      • "delete": true
      }
    }
}

List assets

Lists all assets (including archived assets) that belong to the project.

Each asset in the response includes a link to:

  • the asset's changes endpoint for managing changes belonging to this asset. It acts like the changes endpoint.
  • the asset's scheduled_activities endpoint for managing scheduled activities belonging to this asset. It acts like a scheduled activities endpoint.
  • the asset's bookmarks endpoint for managing the bookmarks belonging to this asset. It acts like a bookmarks endpoint.
  • the asset's mintmodels endpoint for managing the MintModels belonging to this asset. It acts like a MintModels endpoint.
  • the asset's mintmodel_history endpoint for viewing this asset's MintModel history. It acts like a MintModel history endpoint.
  • the asset's workflows endpoint for viewing this asset's workflows. It acts like a Workflows endpoint. .
path Parameters
project_code
required
string
Example: opc

project code

query Parameters
filter[<query/sort filter>]=
string
Example: filter[<query/sort filter>]==> filter[name_eq]=Test

API filtering guide. Named filters: filter[created_by_eq], filter[created_by_in].

download
string
Example: download=assets.csv

Download the project assets in CSV format with the specified file name. The assets will be ordered from oldest to newest when this parameter is specified, irrespective of the sort order requested.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e72f-974f-7d99-a62f-2254a6f96486",
      • "type": "asset",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true,
      • "delete": true
      }
    }
}

Create asset

Creates an asset belonging to the project.

path Parameters
project_code
required
string
Example: opc

project code

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "code": "prj_soa",
      • "name": "Project asset",
      • "description": "Project asset description",
      • "template_code": "soa",
      • "template_version": "2023_Q4_2"
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72f-9a05-7539-bf25-91d51f8104ff",
    • "type": "asset",
    • "attributes": {
      • "code": "zq67r",
      • "name": "enim694",
      • "description": "Et et in vel.",
      • "archived": false,
      • "created_by": "logged_in_user",
      • "created_by_name": "logged_in_user",
      • "task_active": true
      },
    • "relationships": {
      • "properties": {
        },
      • "parents": {
        },
      • "settings": {
        },
      • "parent": {
        },
      • "project": {
        },
      • "template_version": {
        },
      • "bookmarks": {
        },
      • "template": {
        },
      • "latest_node_background_tasks": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/assets/zq67r",
      • "actions": "/api/projects/opc/assets/zq67r/actions",
      • "artifacts": "/api/projects/opc/assets/zq67r/artifacts",
      • "bookmarks": "/api/projects/opc/assets/zq67r/bookmarks",
      • "changes": "/api/projects/opc/assets/zq67r/changes",
      • "scheduled_activities": "/api/projects/opc/assets/zq67r/scheduled_activities",
      • "converged_properties": "/api/projects/opc/assets/zq67r/converged_properties",
      • "mintmodels": "/api/projects/opc/assets/zq67r/mintmodels",
      • "mintmodel_history": "/api/projects/opc/assets/zq67r/mintmodel_history",
      • "parent": "/api/projects/opc",
      • "node_background_tasks": "/api/projects/opc/assets/zq67r/node_background_tasks",
      • "version_history": "/api/projects/opc/assets/zq67r/version_history"
      },
    • "meta": {
      • "can_have_changes": true,
      • "can_have_children": false,
      • "can_have_properties": true,
      • "can_have_settings": true,
      • "can_have_templates": false,
      • "requires_template": true,
      • "child_node_types": [ ],
      • "can_have_workflows": false,
      • "can_have_actions": true,
      • "authorisations": {
        }
      }
    }
}

Show asset

Shows an asset belonging to a project.

The response includes a link to:

  • the asset's changes endpoint for managing changes belonging to this asset. It acts like the changes endpoint.
  • the asset's scheduled_activities endpoint for managing scheduled activities belonging to this asset. It acts like a scheduled activities endpoint.
  • the asset's bookmarks endpoint for managing the bookmarks belonging to this asset. It acts like a bookmarks endpoint.
  • the asset's mintmodels endpoint for managing the MintModels belonging to this asset. It acts like a MintModels endpoint.
  • the asset's mintmodel_history endpoint for viewing this asset's MintModel history. It acts like a MintModel history endpoint.
  • the asset's workflows endpoint for viewing this asset's workflows. It acts like a Workflows endpoint. .
path Parameters
project_code
required
string
Example: opc

project code

asset_code
required
string
Example: prj_soa

asset code

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72f-9f56-7839-b7b4-f845ee9bc57f",
    • "type": "asset",
    • "attributes": {
      • "code": "prj_soa",
      • "name": "Project asset",
      • "description": "Project asset description",
      • "archived": false,
      • "created_by": "dwight-2394",
      • "created_by_name": "dwight-2394",
      • "mintmodel_valid": true,
      • "mintmodel_invalid_reason": null,
      • "erb_file_content": "<MintModel erb file contents>",
      • "task_active": false
      },
    • "relationships": {
      • "properties": {
        },
      • "parents": {
        },
      • "settings": {
        },
      • "parent": {
        },
      • "project": {
        },
      • "template_version": {
        },
      • "bookmarks": {
        },
      • "template": {
        },
      • "latest_node_background_tasks": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/assets/prj_soa",
      • "actions": "/api/projects/opc/assets/prj_soa/actions",
      • "artifacts": "/api/projects/opc/assets/prj_soa/artifacts",
      • "bookmarks": "/api/projects/opc/assets/prj_soa/bookmarks",
      • "changes": "/api/projects/opc/assets/prj_soa/changes",
      • "scheduled_activities": "/api/projects/opc/assets/prj_soa/scheduled_activities",
      • "converged_properties": "/api/projects/opc/assets/prj_soa/converged_properties",
      • "mintmodels": "/api/projects/opc/assets/prj_soa/mintmodels",
      • "mintmodel_history": "/api/projects/opc/assets/prj_soa/mintmodel_history",
      • "parent": "/api/projects/opc",
      • "node_background_tasks": "/api/projects/opc/assets/prj_soa/node_background_tasks",
      • "version_history": "/api/projects/opc/assets/prj_soa/version_history"
      },
    • "meta": {
      • "can_have_changes": true,
      • "can_have_children": false,
      • "can_have_properties": true,
      • "can_have_settings": true,
      • "can_have_templates": false,
      • "requires_template": true,
      • "child_node_types": [ ],
      • "can_have_workflows": false,
      • "can_have_actions": true,
      • "authorisations": {
        },
      • "secret_vault": {
        }
      }
    },
  • "included": [
    • {
      • "id": "01a1e72f-9e98-7694-9b1c-619958995f9e",
      • "type": "project",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": {
        }
      },
    • {
      • "id": "01a1e72f-9faa-7eef-a623-77ffebeff956",
      • "type": "bookmark",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e72f-9ecf-7b54-9a00-ecaf48477ff1",
      • "type": "template",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e72f-9f0b-77dd-aa61-54385f9dfee5",
      • "type": "template_version",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      }
    ]
}

Update asset

Updates an asset belonging to a project.

path Parameters
project_code
required
string
Example: opc

project code

asset_code
required
string
Example: prj_soa

asset code

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "name": "Modified",
      • "description": "The updated asset",
      • "archived": false
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72f-a323-74b0-bfc8-0528690ca886",
    • "type": "asset",
    • "attributes": {
      • "code": "prj_soa",
      • "name": "facilis708",
      • "description": "Vel rerum esse beatae.",
      • "archived": true,
      • "created_by": "trenton_schowalter-2404",
      • "created_by_name": "trenton_schowalter-2404",
      • "task_active": false
      },
    • "relationships": {
      • "properties": {
        },
      • "parents": {
        },
      • "settings": {
        },
      • "parent": {
        },
      • "project": {
        },
      • "template_version": {
        },
      • "bookmarks": {
        },
      • "template": {
        },
      • "latest_node_background_tasks": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/assets/prj_soa",
      • "actions": "/api/projects/opc/assets/prj_soa/actions",
      • "artifacts": "/api/projects/opc/assets/prj_soa/artifacts",
      • "bookmarks": "/api/projects/opc/assets/prj_soa/bookmarks",
      • "changes": "/api/projects/opc/assets/prj_soa/changes",
      • "scheduled_activities": "/api/projects/opc/assets/prj_soa/scheduled_activities",
      • "converged_properties": "/api/projects/opc/assets/prj_soa/converged_properties",
      • "mintmodels": "/api/projects/opc/assets/prj_soa/mintmodels",
      • "mintmodel_history": "/api/projects/opc/assets/prj_soa/mintmodel_history",
      • "parent": "/api/projects/opc",
      • "node_background_tasks": "/api/projects/opc/assets/prj_soa/node_background_tasks",
      • "version_history": "/api/projects/opc/assets/prj_soa/version_history"
      },
    • "meta": {
      • "can_have_changes": true,
      • "can_have_children": false,
      • "can_have_properties": true,
      • "can_have_settings": true,
      • "can_have_templates": false,
      • "requires_template": true,
      • "child_node_types": [ ],
      • "can_have_workflows": false,
      • "can_have_actions": true,
      • "authorisations": {
        }
      }
    }
}

Archive asset

Archives an asset belonging to a project.

path Parameters
project_code
required
string
Example: opc

project code

asset_code
required
string
Example: prj_soa

asset code

query Parameters
ignore_in_use
boolean

When true and the requesting user is a superuser, bypasses in use checks and force-destroys the asset.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    • {
      • "status": 403,
      • "title": "You do not have permission to delete the asset",
      • "detail": "Your authorisation rules let you view the asset but not delete it."
      }
    ]
}

Show converged settings

Show the converged settings for this asset, merged from the project, environment and asset settings. Unless include_global=true is passed, only the values that differ from the global settings are returned: a setting whose converged value matches the global value is omitted, even when it is set directly on a node, so the response is empty when nothing differs from the global settings.

The response includes a setting_sources meta object that attributes each setting value to its originating source.

path Parameters
project_code
required
string
Example: opc

project code

asset_code
required
string
Example: prj_soa

asset code

query Parameters
include_global
boolean
Example: include_global=true

Also return the settings whose converged value matches the global settings

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "prj_soa",
    • "type": "converged_settings",
    • "attributes": {
      • "data": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/assets/prj_soa/converged_settings"
      },
    • "meta": {
      • "setting_sources": {
        }
      }
    }
}

Show converged properties

Show the converged properties as they will appear to actions run on this asset. i.e. the endpoint will

  1. merge any template (repository) properties from the asset's template (in the order described in the documentation)
  2. merge any project properties
  3. merge any properties assigned to the project asset

The API response will also include all the individual repository and database properties that were included in the result.

path Parameters
project_code
required
string
Example: opc

project code

asset_code
required
string
Example: prj_soa

asset code

query Parameters
converge_date
string
Example: converge_date=2026-11-17T01:42:02+00:00

Specify the date (and optionally time), to derive the active template version and asset properties from.

exclude_layers[]
string
Example: exclude_layers[]=template

Exclude a property layer from the converged result. Repeat the parameter to exclude several layers, e.g. > exclude_layers[]=template&exclude_layers[]=asset. Suffix a layer with _repository or _database to exclude only that half of it, e.g. > exclude_layers[]=asset_repository. The layers available for the node, and whether each one is currently included, are listed in the property_layers response meta. The template layer covers the properties files held under the <template code> folder of the template repository, as well as the template's database properties; the template_version layer covers the template version database properties only. Excluding a layer is a preview - the result is not cached and nothing is persisted.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "prj_soa",
    • "type": "converged_properties",
    • "attributes": {
      • "data": {
        }
      },
    • "relationships": {
      • "repository_properties": {
        },
      • "properties": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/assets/prj_soa/converged_properties"
      },
    • "meta": {
      • "property_sources": {
        },
      • "property_layers": [
        ]
      }
    },
  • "included": [
    • {
      • "id": "01a1e72f-bb49-723c-ad16-4255cbbdc92e",
      • "type": "properties_version",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": { }
      },
    • {
      • "id": "01a1e72f-bbcf-7b24-952c-2063d76548d6",
      • "type": "properties_version",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": { }
      },
    • {
      • "id": "01a1e72f-bc07-7ca7-b6e1-aaff2c1f6f36",
      • "type": "properties_version",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": {
        }
      },
    • {
      • "id": "01a1e72f-bc51-7ce0-9e3c-f7fbee6644e8",
      • "type": "properties_version",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": {
        }
      },
    • {
      • "id": "properties/properties.yaml",
      • "type": "repository_properties",
      • "attributes": {
        },
      • "links": {
        }
      },
    • {
      • "id": "properties/projects/opc/properties.yaml",
      • "type": "repository_properties",
      • "attributes": {
        },
      • "links": {
        }
      }
    ]
}

List generate actions request log lines

List the log lines generated while building an image and querying the actions available for this asset / template version combination.

Note: See the list filtered log lines API docs for filtering options.

query Parameters
node_background_task_id
required
string
Example: node_background_task_id=01a1e72a-f444-7621-999d-3ba87fb77fb9
filter[<query/sort filter>]=
string
Example: filter[<query/sort filter>]==> filter[message_cont]=dolorem
download
string
Example: download=change.log

Download the log lines with the specified file name. The logs will be ordered from oldest to newest when this parameter is specified, irrespective of the sort order requested.

limit
integer [ 1 .. 10000 ]
Default: 10000
Example: limit=50

Limit the number of log lines returned. When more records match than the limit a 206 response is returned and meta.partial_response is true.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e72f-c009-7848-b4ad-9eb0dd44ee30",
      • "type": "node_background_task_log_line",
      • "attributes": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true
      },
    • "partial_response": false
    }
}

Create generate actions request

Create a request to refresh the actions list for an asset.

path Parameters
project_code
required
string
Example: opc

project code

asset_code
required
string
Example: prj_soa

asset code

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "build_without_cache": false
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72f-cb19-7038-94fd-6904c40fe7a1",
    • "type": "node_background_task",
    • "attributes": {
      • "request_number": 3,
      • "status_code": "initializing",
      • "error_message": null,
      • "created_by": "logged_in_user",
      • "created_by_name": "logged_in_user",
      • "actions_count": 0,
      • "task_type": "GenerateActionsRequest",
      • "created_at": "2026-11-17T01:47:11.511964Z",
      • "updated_at": "2026-11-17T01:47:11.511964Z",
      • "build_without_cache": false
      },
    • "relationships": {
      • "template_version_history": {
        },
      • "owner": {
        }
      },
    • "links": {
      • "template_version": "/api/projects/opc/templates/01a1e72f-c686-7ef2-8b64-21e8c71c9797/versions/2023_Q4_2",
      • "self": "/api/projects/opc/assets/prj_soa/node_background_tasks/01a1e72f-cb19-7038-94fd-6904c40fe7a1",
      • "asset": "/api/projects/opc/assets/prj_soa",
      • "log_lines": "/api/node_background_task_log_lines?node_background_task_id=01a1e72f-cb19-7038-94fd-6904c40fe7a1"
      }
    }
}

List generate actions requests

Lists all generate actions requests made for the asset's current template version.

path Parameters
project_code
required
string
Example: opc

project code

asset_code
required
string
Example: prj_soa

asset code

query Parameters
filter[<query/sort filter>]=
string
Example: filter[<query/sort filter>]==> filter[request_number_eq]=1

API filtering guide. Named filters: filter[created_by_eq], filter[created_by_in].

limit
integer [ 1 .. 10000 ]
Default: 100
Example: limit=50

Limit the number of requests returned. When more records match than the limit a 206 response is returned and meta.partial_response is true.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e72f-d60d-7b27-a04b-3705ef332234",
      • "type": "node_background_task",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e72f-d5de-774b-8955-7eda4ef82783",
      • "type": "node_background_task",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true,
      • "delete": true
      },
    • "partial_response": false
    }
}

Show generate actions request

Show a specific actions generation request.

path Parameters
project_code
required
string
Example: opc

project code

asset_code
required
string
Example: prj_soa

asset code

node_background_task_id
required
string
Example: 01a1e72a-f444-7621-999d-3ba87fb77fb9

generate actions request id

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72f-da0a-763f-8509-9b22a3e4f364",
    • "type": "node_background_task",
    • "attributes": {
      • "request_number": 1,
      • "status_code": "success",
      • "error_message": null,
      • "created_by": "jacalyn.nolan-2529",
      • "created_by_name": "jacalyn.nolan-2529",
      • "actions": [
        ],
      • "actions_count": 1,
      • "task_type": "GenerateActionsRequest",
      • "created_at": "2026-11-17T01:47:15.337117Z",
      • "updated_at": "2026-11-17T01:47:15.351223Z",
      • "build_without_cache": false
      },
    • "relationships": {
      • "template_version_history": {
        },
      • "owner": {
        }
      },
    • "links": {
      • "template_version": "/api/projects/opc/templates/01a1e72f-d8df-737a-94eb-c0337bb3631d/versions/2023_Q4_2",
      • "self": "/api/projects/opc/assets/prj_soa/node_background_tasks/01a1e72f-da0a-763f-8509-9b22a3e4f364",
      • "asset": "/api/projects/opc/assets/prj_soa",
      • "log_lines": "/api/node_background_task_log_lines?node_background_task_id=01a1e72f-da0a-763f-8509-9b22a3e4f364"
      }
    }
}

Cancel generate actions request

Cancels the generate actions request.

path Parameters
project_code
required
string
Example: opc

project code

asset_code
required
string
Example: prj_soa

asset code

node_background_task_id
required
string
Example: 01a1e72a-f444-7621-999d-3ba87fb77fb9

generate actions request id

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    • {
      • "status": 403,
      • "title": "You do not have permission to cancel the generate actions request",
      • "detail": "Your authorisation rules let you view the generate actions request but not cancel it."
      }
    ]
}

List properties history

Lists all properties versions and template versions for the asset and its parents.

path Parameters
project_code
required
string
Example: opc

project code

asset_code
required
string
Example: prj_soa

asset code

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e730-99bd-7db4-a205-2153b360b729",
      • "type": "project",
      • "attributes": {
        }
      },
    • {
      • "id": "01a1e730-99f7-7f85-9571-afd45b61ef9d",
      • "type": "template",
      • "attributes": {
        }
      },
    • {
      • "id": "01a1e730-9a70-7ebd-85c5-bfc54a1ee508",
      • "type": "asset",
      • "attributes": {
        }
      }
    ]
}

List template version history

Lists the template versions that have been assigned to the asset.

path Parameters
project_code
required
string
Example: opc

project code

asset_code
required
string
Example: prj_soa

asset code

query Parameters
filter[<query/sort filter>]=
string
Example: filter[<query/sort filter>]==> filter[name_eq]=Test

API filtering guide. Named filters: filter[created_by_eq], filter[created_by_in].

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e731-ebaa-7802-bc06-fa9d558adcca",
      • "type": "template_version_history",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true
      }
    }
}

Show template version history

Shows a specific project asset's template version history record.

path Parameters
project_code
required
string
Example: opc

project code

asset_code
required
string
Example: prj_soa

asset code

id
required
string
Example: 01a1e72a-f3c3-7e71-950d-91cd9e27ca6b

version history id

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e731-ee95-7a39-acfd-f4481c4a81df",
    • "type": "template_version_history",
    • "attributes": {
      • "created_by": "isiah-3702",
      • "created_by_name": "isiah-3702",
      • "commit_sha": "3edbb60f626b9864f327f26879d5373442994b68",
      • "active_from": "2026-11-17T01:49:31.667779Z",
      • "active_to": null
      },
    • "relationships": {
      • "owner": {
        },
      • "template_version": {
        },
      • "node_background_tasks": {
        }
      },
    • "links": {
      • "template_version": "/api/projects/opc/templates/01a1e731-ede0-7a73-8c47-568fa55b4121/versions/2023_Q4_2",
      • "self": "/api/projects/opc/assets/prj_soa/version_history/01a1e731-ee95-7a39-acfd-f4481c4a81df",
      • "asset": "/api/projects/opc/assets/prj_soa"
      }
    },
  • "included": [
    • {
      • "id": "01a1e731-ee5f-7396-b3d3-badeb0ae77ef",
      • "type": "asset",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": {
        }
      },
    • {
      • "id": "01a1e731-ee1d-7b18-9ae9-9fd292e31981",
      • "type": "template_version",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      }
    ]
}

Actions

Endpoints to query the action step trees available for a templated node.

Notes:

  • The list and show action endpoints are routed for any templated node, via the /<path/to/node>/actions path, but only assets build an action catalog; an agent's action list is always empty. The example endpoints in this section reflect the actions of a project asset.
  • Only the top level actions of the catalog are addressable, by their action name or their step_name. Child actions are not individually addressable - they are included in each action's children attribute by the show endpoint, and by the list endpoint when include_children is set.

List actions

Lists every action available for the asset.

path Parameters
project_code
required
string
Example: opc

project code

asset_code
required
string
Example: prj_soa

asset code

query Parameters
include_children
boolean
Example: include_children=true

By default each action is returned without its children. Set this to return the full step tree of every action.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "deploy",
      • "type": "action",
      • "links": {
        },
      • "attributes": {
        }
      },
    • {
      • "id": "provision",
      • "type": "action",
      • "links": {
        },
      • "attributes": {
        }
      }
    ]
}

Show action

Shows the step tree of one of the asset's actions. The action can be identified by its action name or its step_name.

path Parameters
project_code
required
string
Example: opc

project code

asset_code
required
string
Example: prj_soa

asset code

id
required
string
Example: deploy

action name or step name

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "deploy",
    • "type": "action",
    • "links": {
      • "self": "/api/projects/opc/assets/prj_soa/actions/deploy"
      },
    • "attributes": {
      • "action": "deploy",
      • "children": [
        ],
      • "pre_reqs": [ ],
      • "full_path": "deploy",
      • "step_name": "deploy",
      • "stage_step": false,
      • "description": "Deploy the asset",
      • "ignore_failure": false,
      • "child_execution_strategy": "sequential"
      }
    }
}

Templates

Templates provide the available actions and a base set of repository properties that will be used to configure the asset.

Create template

Create a template.

path Parameters
project_code
required
string
Example: opc

project code

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "code": "soa",
      • "name": "Oracle SOA template",
      • "template_type": "asset",
      • "description": "Oracle SOA Suite 12c (12.2.1.4.0)",
      • "git_remote_name": "github"
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e731-b20f-770b-99b4-55353fea2024",
    • "type": "template",
    • "attributes": {
      • "code": "ypvo7",
      • "name": "fernando",
      • "description": "Repellendus et explicabo eveniet.",
      • "archived": false,
      • "disabled": false,
      • "template_type": "asset",
      • "created_at": "2026-11-17T01:49:16.174443Z",
      • "updated_at": "2026-11-17T01:49:16.174443Z"
      },
    • "relationships": {
      • "properties": {
        },
      • "settings": {
        },
      • "git_remote": {
        },
      • "template_versions": {
        },
      • "nodes": {
        },
      • "project": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/templates/01a1e731-b20f-770b-99b4-55353fea2024",
      • "template_versions": "/api/projects/opc/templates/01a1e731-b20f-770b-99b4-55353fea2024/versions",
      • "project": "/api/projects/opc"
      }
    }
}

List templates

Lists all templates for a project.

path Parameters
project_code
required
string
Example: opc

project code

query Parameters
filter[<query/sort filter>]=
string
Example: filter[<query/sort filter>]==> filter[name_cont]=base
exclude_archived_nodes
boolean
Example: exclude_archived_nodes=true

when true, excludes archived nodes from each template's nodes relationship

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e731-b83c-748b-b5f9-315dd29eadc2",
      • "type": "template",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true,
      • "delete": true
      }
    }
}

Archive unused template versions

Archives the versions of a project's templates that have not been used for a period.

Notes:

  1. A version is unused when nothing has created it, used it in a change or assigned it to an asset for filters.template_versions.unused_for_days days. A version is never archived while an asset points at it (archived assets included), an unfinished change uses it, it is locked, or an unarchived version of an unarchived workflow names a template version with the same name. Archived versions keep their name reserved.
  2. filters.template_versions.unused_for_days is required and must be a whole number of days from 1 to 365, otherwise the request is rejected with a 422 error on filters. filters.template_versions.keep_latest keeps the newest N versions of each template by creation date, counting versions in use, and the other template_versions keys are ransack filters, e.g. template_id_in to limit the request to selected templates or version_cont to match version names.
  3. Only versions of the project's templates, and its environments' and assets' templates, that the user may update are included.
  4. The result is returned in the top level meta object. meta.template_versions lists the path of each archived version and meta.archived_count counts them. The result is also recorded in an info:data_cleanup:template_versions event on the project, whose id is returned in meta.event_id.
path Parameters
project_code
required
string
Example: opc

project code

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "filters": {
        }
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": null,
  • "meta": {
    • "archived_count": 0,
    • "template_versions": [ ],
    • "event_id": "01a1e731-bae2-71a0-b9d5-a91c3592ec93"
    }
}

Preview archiving unused template versions

Lists the versions of a project's templates that the archive_unused_versions endpoint would archive, without archiving anything.

Notes:

  1. A version is unused when nothing has created it, used it in a change or assigned it to an asset for filters.template_versions.unused_for_days days. A version is never archived while an asset points at it (archived assets included), an unfinished change uses it, it is locked, or an unarchived version of an unarchived workflow names a template version with the same name. Archived versions keep their name reserved.
  2. filters.template_versions.unused_for_days is required and must be a whole number of days from 1 to 365, otherwise the request is rejected with a 422 error on filters. filters.template_versions.keep_latest keeps the newest N versions of each template by creation date, counting versions in use, and the other template_versions keys are ransack filters, e.g. template_id_in to limit the request to selected templates or version_cont to match version names.
  3. Only versions of the project's templates, and its environments' and assets' templates, that the user may update are included.
  4. The result is returned in the top level meta object. meta.template_versions lists the path of each version that a request at the same time would archive, and meta.total counts them.
path Parameters
project_code
required
string
Example: opc

project code

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "filters": {
        }
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": null,
  • "meta": {
    • "template_versions": [ ],
    • "total": 0
    }
}

Show template

Shows a project template.

path Parameters
project_code
required
string
Example: opc

project code

template_id
required
string
Example: 01a1e72a-f150-7b02-b744-c5bfc406c905

template id

query Parameters
exclude_archived_nodes
boolean
Example: exclude_archived_nodes=true

when true, excludes archived nodes from each template's nodes relationship

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e731-ccf3-7526-85c6-f89ff22d43e5",
    • "type": "template",
    • "attributes": {
      • "code": "soa",
      • "name": "Oracle SOA template",
      • "description": "Oracle SOA Suite 12c (12.2.1.4.0)",
      • "archived": false,
      • "disabled": false,
      • "template_type": "asset",
      • "created_at": "2026-11-17T01:49:23.058426Z",
      • "updated_at": "2026-11-17T01:49:23.058426Z"
      },
    • "relationships": {
      • "properties": {
        },
      • "settings": {
        },
      • "git_remote": {
        },
      • "template_versions": {
        },
      • "nodes": {
        },
      • "project": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/templates/01a1e731-ccf3-7526-85c6-f89ff22d43e5",
      • "template_versions": "/api/projects/opc/templates/01a1e731-ccf3-7526-85c6-f89ff22d43e5/versions",
      • "project": "/api/projects/opc"
      }
    },
  • "meta": {
    • "authorisations": {
      • "update": true,
      • "delete": true
      }
    }
}

Archive template

Archives/unarchives a template.

path Parameters
project_code
required
string
Example: opc

project code

id_to_archive
required
string
Example: 01a1e72a-f150-7b02-b744-c5bfc406c905

template id

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "archived": true
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e731-d1b3-7651-b600-5d71e3c2f392",
    • "type": "template",
    • "attributes": {
      • "code": "soa",
      • "name": "Oracle SOA template",
      • "description": "Oracle SOA Suite 12c (12.2.1.4.0)",
      • "archived": true,
      • "disabled": false,
      • "template_type": "asset",
      • "created_at": "2026-11-17T01:49:24.274546Z",
      • "updated_at": "2026-11-17T01:49:24.354200Z"
      },
    • "relationships": {
      • "properties": {
        },
      • "settings": {
        },
      • "git_remote": {
        },
      • "template_versions": {
        },
      • "nodes": {
        },
      • "project": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/templates/01a1e731-d1b3-7651-b600-5d71e3c2f392",
      • "template_versions": "/api/projects/opc/templates/01a1e731-d1b3-7651-b600-5d71e3c2f392/versions",
      • "project": "/api/projects/opc"
      }
    }
}

Update template

Update a templates details.

path Parameters
project_code
required
string
Example: opc

project code

id_to_update
required
string
Example: 01a1e72a-f150-7b02-b744-c5bfc406c905

template id

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "name": "Oracle SOA template",
      • "description": "Oracle SOA Suite 12c (12.2.1.4.0)",
      • "git_remote_name": "github",
      • "disabled": false
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e731-d77c-7b43-b02d-754413ce3fc5",
    • "type": "template",
    • "attributes": {
      • "code": "soa",
      • "name": "updated_name",
      • "description": "updated_description",
      • "archived": false,
      • "disabled": false,
      • "template_type": "asset",
      • "created_at": "2026-11-17T01:49:25.755904Z",
      • "updated_at": "2026-11-17T01:49:25.821891Z"
      },
    • "relationships": {
      • "properties": {
        },
      • "settings": {
        },
      • "git_remote": {
        },
      • "template_versions": {
        },
      • "nodes": {
        },
      • "project": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/templates/01a1e731-d77c-7b43-b02d-754413ce3fc5",
      • "template_versions": "/api/projects/opc/templates/01a1e731-d77c-7b43-b02d-754413ce3fc5/versions",
      • "project": "/api/projects/opc"
      }
    }
}

Delete template

Deletes a project template. A template cannot be deleted while it is assigned to a node or referenced by a change.

path Parameters
project_code
required
string
Example: opc

project code

id_to_delete
required
string
Example: 01a1e72a-f150-7b02-b744-c5bfc406c905

template id

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    • {
      • "status": 403,
      • "title": "You do not have permission to delete the template",
      • "detail": "Your authorisation rules let you view the template but not delete it."
      }
    ]
}

Show converged settings

Show the converged settings for this template, merged from the global, project and template settings. Unless include_global=true is passed, only the values that differ from the global settings are returned: a setting whose converged value matches the global value is omitted, so the response is empty when nothing differs from the global settings.

The response includes a setting_sources meta object that attributes each setting value to its originating source.

path Parameters
project_code
required
string
Example: opc

project code

template_id
required
string
Example: 01a1e72a-f150-7b02-b744-c5bfc406c905

template id

query Parameters
include_global
boolean
Example: include_global=true

Also return the settings whose converged value matches the global settings

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e731-e52a-7d12-a397-4ce05b739426",
    • "type": "converged_settings",
    • "attributes": {
      • "data": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/templates/01a1e731-e52a-7d12-a397-4ce05b739426/converged_settings"
      },
    • "meta": {
      • "setting_sources": {
        }
      }
    }
}

Show converged properties

Show the converged properties for this template, merged from the global, project and template settings, merged from the database properties of the project and the template.

The API response will also include the individual database properties that were included in the result.

path Parameters
project_code
required
string
Example: opc

project code

template_id
required
string
Example: 01a1e72a-f150-7b02-b744-c5bfc406c905

template id

query Parameters
converge_date
string
Example: converge_date=2026-11-17T01:42:03+00:00

Specify the date (and optionally time), to derive the active properties from.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e731-e838-7edf-af61-dfaf5f6736d0",
    • "type": "converged_properties",
    • "attributes": {
      • "data": {
        }
      },
    • "relationships": {
      • "repository_properties": {
        },
      • "properties": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/templates/01a1e731-e838-7edf-af61-dfaf5f6736d0/converged_properties"
      },
    • "meta": {
      • "property_sources": {
        },
      • "property_layers": [
        ]
      }
    },
  • "included": [
    • {
      • "id": "01a1e731-e800-7cfa-878f-0da694b35c5e",
      • "type": "properties_version",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": { }
      },
    • {
      • "id": "01a1e731-e84a-7d98-895e-324a2469541b",
      • "type": "properties_version",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": { }
      }
    ]
}

List template versions

Lists all versions of a specific template.

path Parameters
project_code
required
string
Example: opc

project code

template_id
required
string
Example: 01a1e72a-f150-7b02-b744-c5bfc406c905

template id

query Parameters
filter[<query/sort filter>]=
string
Example: filter[<query/sort filter>]==> filter[version_cont]=1.0

API filtering guide. Named filters: filter[created_by_eq], filter[created_by_in], filter[keep_latest], filter[unused_for_days].

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e731-f05d-7683-bc1d-3be9483be487",
      • "type": "template_version",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true,
      • "delete": true
      }
    }
}

Create or update a template version

Create or update a template version.

path Parameters
project_code
required
string
Example: opc

project code

template_id
required
string
Example: 01a1e72a-f150-7b02-b744-c5bfc406c905

template id

version
required
string
Example: 2023_Q4_2

template version

Request Body schema: application/vnd.api+json
required
object
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "description": "Added additional configuration options",
      • "git_rev": "open-source",
      • "archived": "false",
      • "locked": "false",
      • "float_git_rev": "false"
      }
    },
  • "meta": {
    • "ignore_in_use": false,
    • "fetch_revision": false
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e731-f46b-7c94-9099-92bfdfbdef1e",
    • "type": "template_version",
    • "attributes": {
      • "version": "2023_Q4_2",
      • "description": "Cupiditate non odit in autem eveniet enim nisi qui sed sit dolor ea voluptatibus",
      • "state": "initializing",
      • "created_by": "logged_in_user",
      • "created_by_name": "logged_in_user",
      • "archived": false,
      • "initialization_error": null,
      • "locked": false,
      • "float_git_rev": false,
      • "float_refresh_error": null,
      • "created_at": "2026-11-17T01:49:33.162758Z",
      • "updated_at": "2026-11-17T01:49:33.162758Z",
      • "committed_at": null,
      • "has_mintmodel": false,
      • "git_rev": "cross-platform",
      • "commit_sha": null,
      • "git_remote_name": "github"
      },
    • "relationships": {
      • "properties": {
        },
      • "settings": {
        },
      • "project": {
        },
      • "template": {
        },
      • "pending_commit": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/templates/01a1e731-f33c-7ad8-8647-0a8592f99d14/versions/2023_Q4_2",
      • "template": "/api/projects/opc/templates/01a1e731-f33c-7ad8-8647-0a8592f99d14"
      }
    }
}

Show template version

Shows a specific template version.

path Parameters
project_code
required
string
Example: opc

project code

template_id
required
string
Example: 01a1e72a-f150-7b02-b744-c5bfc406c905

template id

version
required
string
Example: 2023_Q4_2

template version

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e731-fc9f-73a4-a2ef-dbc2806db78d",
    • "type": "template_version",
    • "attributes": {
      • "version": "2023_Q4_2",
      • "description": "Added additional configuration options",
      • "state": "ready",
      • "created_by": "shawna-3746",
      • "created_by_name": "shawna-3746",
      • "archived": false,
      • "initialization_error": null,
      • "locked": false,
      • "float_git_rev": false,
      • "float_refresh_error": null,
      • "created_at": "2026-11-17T01:49:35.262278Z",
      • "updated_at": "2026-11-17T01:49:35.262278Z",
      • "committed_at": null,
      • "has_mintmodel": true,
      • "git_rev": "virtual",
      • "commit_sha": "8119fe97250695c40f361c1e6836806d74221908",
      • "git_remote_name": "github"
      },
    • "relationships": {
      • "properties": {
        },
      • "settings": {
        },
      • "project": {
        },
      • "template": {
        },
      • "pending_commit": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/templates/01a1e731-fc68-79ef-bf86-1ab3e814b38d/versions/2023_Q4_2",
      • "template": "/api/projects/opc/templates/01a1e731-fc68-79ef-bf86-1ab3e814b38d"
      }
    },
  • "meta": {
    • "authorisations": {
      • "update": true,
      • "delete": true
      }
    }
}

Delete template version

Delete or archive a template version.

  • If the template version has never been assigned to an asset, it will be deleted.
  • If the template version has previously been assigned to an asset, it will be archived so the assignment history is preserved.
  • If the template version is currently assigned to an asset, it can be neither deleted nor archived.
path Parameters
project_code
required
string
Example: opc

project code

template_id
required
string
Example: 01a1e72a-f150-7b02-b744-c5bfc406c905

template id

version
required
string
Example: 2023_Q4_2

template version

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e732-01e9-7795-95d8-fc53f0cc98f7",
    • "type": "template_version",
    • "attributes": {
      • "version": "2023_Q4_2",
      • "description": "Added additional configuration options",
      • "state": "ready",
      • "created_by": "janett_harber-3758",
      • "created_by_name": "janett_harber-3758",
      • "archived": true,
      • "initialization_error": null,
      • "locked": false,
      • "float_git_rev": false,
      • "float_refresh_error": null,
      • "created_at": "2026-11-17T01:49:36.616544Z",
      • "updated_at": "2026-11-17T01:49:37.215954Z",
      • "committed_at": null,
      • "has_mintmodel": true,
      • "git_rev": "redundant",
      • "commit_sha": "9b5da1d4eafdb4ea12b23589fe3b693863ea72ba",
      • "git_remote_name": "github"
      },
    • "relationships": {
      • "properties": {
        },
      • "settings": {
        },
      • "project": {
        },
      • "template": {
        },
      • "pending_commit": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/templates/01a1e732-01b4-7593-8d49-d91f7558bee4/versions/2023_Q4_2",
      • "template": "/api/projects/opc/templates/01a1e732-01b4-7593-8d49-d91f7558bee4"
      }
    }
}

Bulk assign assets to template versions

Assign assets to the template version.

path Parameters
project_code
required
string
Example: opc

project code

template_id
required
string
Example: 01a1e72a-f150-7b02-b744-c5bfc406c905

template id

version
required
string
Example: 2023_Q4_2

template version

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "asset_paths": [
        ]
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e732-1201-73c1-b5c5-c46f84fe4616",
    • "type": "template_version",
    • "attributes": {
      • "version": "2023_Q4_2",
      • "description": "Added additional configuration options",
      • "state": "ready",
      • "created_by": "fairy-3785",
      • "created_by_name": "fairy-3785",
      • "archived": false,
      • "initialization_error": null,
      • "locked": false,
      • "float_git_rev": false,
      • "float_refresh_error": null,
      • "created_at": "2026-11-17T01:49:40.736411Z",
      • "updated_at": "2026-11-17T01:49:40.736411Z",
      • "committed_at": null,
      • "has_mintmodel": true,
      • "git_rev": "cross-platform",
      • "commit_sha": "e9a373e99fc8ef8ad23c7031ecdf29637c2d0cc4",
      • "git_remote_name": "github"
      },
    • "relationships": {
      • "properties": {
        },
      • "settings": {
        },
      • "project": {
        },
      • "template": {
        },
      • "pending_commit": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/templates/01a1e732-11d1-73a0-8a8d-e8ae0f3c00fb/versions/2023_Q4_2",
      • "template": "/api/projects/opc/templates/01a1e732-11d1-73a0-8a8d-e8ae0f3c00fb"
      }
    }
}

Cancel a template version Git SHA refresh

Cancel an in-progress Git SHA refresh for the template version. When the version was previously resolved it is returned to that commit, otherwise the version is left broken.

path Parameters
project_code
required
string
Example: opc

project code

template_id
required
string
Example: 01a1e72a-f150-7b02-b744-c5bfc406c905

template id

version
required
string
Example: 2023_Q4_2

template version

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e732-1d6a-7274-9ec8-755c0dbd2c5a",
    • "type": "template_version",
    • "attributes": {
      • "version": "r397e",
      • "description": "Est consequatur optio tempora amet tenetur pariatur quaerat rem",
      • "state": "ready",
      • "created_by": "sidney_hoeger-3814",
      • "created_by_name": "sidney_hoeger-3814",
      • "archived": false,
      • "initialization_error": null,
      • "locked": false,
      • "float_git_rev": false,
      • "float_refresh_error": null,
      • "created_at": "2026-11-17T01:49:43.657164Z",
      • "updated_at": "2026-11-17T01:49:43.747400Z",
      • "committed_at": null,
      • "has_mintmodel": false,
      • "git_rev": "online",
      • "commit_sha": "bb2c9d06a4bba1d9ff9cc660015fa1b2ef93461c",
      • "git_remote_name": "lynda_schinner"
      },
    • "relationships": {
      • "properties": {
        },
      • "settings": {
        },
      • "project": {
        },
      • "template": {
        },
      • "pending_commit": {
        }
      },
    • "links": {
      • "self": "/api/projects/xfdi2/templates/01a1e732-1cf5-7056-8a81-e33be0ae15fd/versions/r397e",
      • "template": "/api/projects/xfdi2/templates/01a1e732-1cf5-7056-8a81-e33be0ae15fd"
      }
    }
}

Show converged settings

Show the converged settings for this template version, merged from the global, project, template and template version settings. Unless include_global=true is passed, only the values that differ from the global settings are returned: a setting whose converged value matches the global value is omitted, so the response is empty when nothing differs from the global settings.

The response includes a setting_sources meta object that attributes each setting value to its originating source.

path Parameters
project_code
required
string
Example: opc

project code

template_id
required
string
Example: 01a1e72a-f150-7b02-b744-c5bfc406c905

template id

version
required
string
Example: 2023_Q4_2

template version

query Parameters
include_global
boolean
Example: include_global=true

Also return the settings whose converged value matches the global settings

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "2023_Q4_2",
    • "type": "converged_settings",
    • "attributes": {
      • "data": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/templates/01a1e732-2455-7dac-a532-c7bbccaf747a/versions/2023_Q4_2/converged_settings"
      },
    • "meta": {
      • "setting_sources": {
        }
      }
    }
}

Show converged properties

Show the converged properties for this template version, merged from the global, project, template and template version settings, merged from the database properties of the project and the template and template version.

The API response will also include the individual database properties that were included in the result.

path Parameters
project_code
required
string
Example: opc

project code

template_id
required
string
Example: 01a1e72a-f150-7b02-b744-c5bfc406c905

template id

version
required
string
Example: 2023_Q4_2

template version

query Parameters
converge_date
string
Example: converge_date=2026-11-17T01:42:03+00:00

Specify the date (and optionally time), to derive the active properties from.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "2023_Q4_2",
    • "type": "converged_properties",
    • "attributes": {
      • "data": {
        }
      },
    • "relationships": {
      • "repository_properties": {
        },
      • "properties": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/templates/01a1e732-2a0c-7dda-9779-2e844f1b9d5a/versions/2023_Q4_2/converged_properties"
      },
    • "meta": {
      • "property_sources": {
        },
      • "property_layers": [
        ]
      }
    },
  • "included": [
    • {
      • "id": "01a1e732-29df-7cd8-bb31-48119e3c246a",
      • "type": "properties_version",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": { }
      },
    • {
      • "id": "01a1e732-2a1f-78d9-85ab-0a4ddcf8a78c",
      • "type": "properties_version",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": { }
      },
    • {
      • "id": "01a1e732-2a5b-789a-b661-eeb8d1fe6fef",
      • "type": "properties_version",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": {
        }
      }
    ]
}

Git remotes

Endpoints to interact with git remotes.

Create Git remote

Create a project Git remote.

For HTTP(S) remotes provide the user and password credentials. For SSH remotes provide the ssh_key_data private key and, if the key is encrypted, its passphrase. Supplying password for an SSH remote (or passphrase for an HTTP(S) remote) is rejected.

When meta.add_known_host is true and the remote uses an SSH URL, OpsChain scans the host with ssh-keyscan and stores the fetched host key in the global known_hosts setting before validating the connection, so the same request - and all future fetches - trust the host. On success the response meta.known_hosts_added lists the registered host key lines. This requires superuser access (a non-superuser receives a 403). The scanned key is trusted on first use (TOFU); verify the reported host key out of band.

path Parameters
project_code
required
string
Example: opc

project code

Request Body schema: application/vnd.api+json
required
object
object

Responses

Request samples

Content type
application/vnd.api+json
{}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72f-1389-7198-b7c1-0239cc2c5022",
    • "type": "git_remote",
    • "attributes": {
      • "name": "github",
      • "public_url": null,
      • "archived": false,
      • "disabled": false,
      • "periodic_fetch_interval": null,
      • "created_at": "2026-11-17T01:46:24.519963Z",
      • "updated_at": "2026-11-17T01:46:24.519963Z",
      • "user": null,
      • "ssh_key_data": null,
      • "password": null,
      • "passphrase": null
      },
    • "relationships": {
      • "templates": {
        },
      • "project": {
        }
      },
    • "links": {
      • "project": "/api/projects/opc",
      • "templates": "/api/projects/opc/templates?filter%5Bgit_remote_name_eq%5D=github",
      • "self": "/api/projects/opc/git_remotes/01a1e72f-1389-7198-b7c1-0239cc2c5022"
      },
    • "meta": null
    }
}

List Git remotes

Lists all Git remotes for a project.

path Parameters
project_code
required
string
Example: opc

project code

query Parameters
filter[<query/sort filter>]=
string
Example: filter[<query/sort filter>]==> filter[name_cont]=origin

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e72f-1c4d-78c5-9fd8-4468da62c160",
      • "type": "git_remote",
      • "attributes": {},
      • "relationships": {
        },
      • "links": {
        },
      • "meta": null
      },
    • {
      • "id": "01a1e72f-1c6d-7d22-9295-9459ea057efd",
      • "type": "git_remote",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": null
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true,
      • "delete": true
      },
    • "default_periodic_fetch_interval": 900
    }
}

Show Git remote

Shows a project Git remote.

Note: Git remote credentials are obfuscated for security reasons.

path Parameters
project_code
required
string
Example: opc

project code

remote_id
required
string
Example: 01a1e72a-f0cc-7a86-9dad-3fda525db936

remote id

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72f-2595-7452-a161-e901859ebdc6",
    • "type": "git_remote",
    • "attributes": {},
    • "relationships": {
      • "templates": {
        },
      • "project": {
        }
      },
    • "links": {
      • "project": "/api/projects/opc",
      • "templates": "/api/projects/opc/templates?filter%5Bgit_remote_name_eq%5D=github",
      • "self": "/api/projects/opc/git_remotes/01a1e72f-2595-7452-a161-e901859ebdc6"
      },
    • "meta": null
    }
}

Archive Git remote

Archives/unarchives a project Git remote.

path Parameters
project_code
required
string
Example: opc

project code

id_to_archive
required
string
Example: 01a1e72a-f0cc-7a86-9dad-3fda525db936

remote id

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "archived": true
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72f-2ad2-7550-83e9-82e6cf3a0d08",
    • "type": "git_remote",
    • "attributes": {},
    • "relationships": {
      • "templates": {
        },
      • "project": {
        }
      },
    • "links": {
      • "project": "/api/projects/opc",
      • "templates": "/api/projects/opc/templates?filter%5Bgit_remote_name_eq%5D=github",
      • "self": "/api/projects/opc/git_remotes/01a1e72f-2ad2-7550-83e9-82e6cf3a0d08"
      },
    • "meta": null
    }
}

Update Git remote

Update the URL and/or credentials of a project Git remote. The remote must be active (not archived), and OpsChain verifies the remote is reachable with the updated values before saving. The URL may only be edited to change its credentials, scheme, or port - the host and path cannot change (delete and recreate the remote to point at a different repository).

For HTTP(S) remotes provide the user and password credentials. For SSH remotes provide the ssh_key_data private key and, if the key is encrypted, its passphrase. Supplying password for an SSH remote (or passphrase for an HTTP(S) remote) is rejected. Changing a remote's protocol clears the existing credentials - supply the new protocol's credentials in the same request.

When meta.add_known_host is true and the request changes the URL to an SSH URL, OpsChain scans the new host with ssh-keyscan and stores the fetched host key in the global known_hosts setting before validating the connection. On success the response meta.known_hosts_added lists the registered host key lines. This requires superuser access (a non-superuser receives a 403). The scanned key is trusted on first use (TOFU); verify the reported host key out of band.

path Parameters
project_code
required
string
Example: opc

project code

id_to_update
required
string
Example: 01a1e72a-f0cc-7a86-9dad-3fda525db936

remote id

Request Body schema: application/vnd.api+json
required
object
object

Responses

Request samples

Content type
application/vnd.api+json
{}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72f-3411-7424-a42d-0f0acad47310",
    • "type": "git_remote",
    • "attributes": {},
    • "relationships": {
      • "templates": {
        },
      • "project": {
        }
      },
    • "links": {
      • "project": "/api/projects/opc",
      • "templates": "/api/projects/opc/templates?filter%5Bgit_remote_name_eq%5D=github",
      • "self": "/api/projects/opc/git_remotes/01a1e72f-3411-7424-a42d-0f0acad47310"
      },
    • "meta": null
    }
}

Delete Git remote

Deletes a project Git remote if it has no changes, otherwise it removes the credentials.

path Parameters
project_code
required
string
Example: opc

project code

id_to_delete
required
string
Example: 01a1e72a-f0cc-7a86-9dad-3fda525db936

remote id

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72f-3f73-74e3-9a68-765aaab82216",
    • "type": "git_remote",
    • "attributes": {},
    • "relationships": {
      • "templates": {
        },
      • "project": {
        }
      },
    • "links": {
      • "project": "/api/projects/opc",
      • "templates": "/api/projects/opc/templates?filter%5Bgit_remote_name_eq%5D=github",
      • "self": "/api/projects/opc/git_remotes/01a1e72f-3f73-74e3-9a68-765aaab82216"
      },
    • "meta": {
      • "credentials_removed": true,
      • "messages": [
        ]
      }
    }
}

Bookmarks

Endpoints to interact with bookmarks.

Notes:

  • The list, create, show, update and delete bookmark endpoints are available via the /<path/to/bookmark/owner>/bookmarks path. The example endpoints in this section reflect bookmarks owned by a project asset.

Create bookmark

Create a bookmark for a specific project, environment or asset.

path Parameters
project_code
required
string
Example: opc

project code

asset_code
required
string
Example: prj_soa

asset code

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72d-0f52-7b6b-96b3-c345a4eb2e6a",
    • "type": "bookmark",
    • "attributes": {
      • "description": "Consequatur nostrum ducimus libero. 1",
      • "created_by": "logged_in_user",
      • "created_by_name": "logged_in_user",
      • "created_at": "2026-11-17T01:44:12.369358Z",
      • "updated_at": "2026-11-17T01:44:12.369358Z"
      },
    • "relationships": {
      • "parent": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/assets/prj_soa/bookmarks/01a1e72d-0f52-7b6b-96b3-c345a4eb2e6a",
      • "parent": "/api/projects/opc/assets/prj_soa"
      }
    }
}

List bookmarks

Lists all bookmarks for a specific project, environment or asset.

path Parameters
project_code
required
string
Example: opc

project code

asset_code
required
string
Example: prj_soa

asset code

query Parameters
filter[<query/sort filter>]=
string
Example: filter[<query/sort filter>]==> filter[description_cont]=server

API filtering guide. Named filters: filter[created_by_eq], filter[created_by_in].

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e72d-2221-784a-ab8f-8bcc92dde5f6",
      • "type": "bookmark",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true,
      • "delete": true
      }
    }
}

Show bookmark

Show a bookmark for a specific project, environment or asset.

path Parameters
project_code
required
string
Example: opc

project code

asset_code
required
string
Example: prj_soa

asset code

bookmark_id
required
string
Example: 01a1e72a-f4bc-7668-879e-e5460a929fb9

bookmark id

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72d-2620-7daa-9e49-8f646741c338",
    • "type": "bookmark",
    • "attributes": {
      • "description": "SOA administration console",
      • "created_by": "vicente-1383",
      • "created_by_name": "vicente-1383",
      • "created_at": "2026-11-17T01:44:18.205064Z",
      • "updated_at": "2026-11-17T01:44:18.205064Z"
      },
    • "relationships": {
      • "parent": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/assets/prj_soa/bookmarks/01a1e72d-2620-7daa-9e49-8f646741c338",
      • "parent": "/api/projects/opc/assets/prj_soa"
      }
    }
}

Update bookmark

Update a bookmark for a specific project, environment or asset.

path Parameters
project_code
required
string
Example: opc

project code

asset_code
required
string
Example: prj_soa

asset code

bookmark_id
required
string
Example: 01a1e72a-f4bc-7668-879e-e5460a929fb9

bookmark id

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72d-2f38-72f6-b048-1ec283deedf6",
    • "type": "bookmark",
    • "attributes": {
      • "description": "Updated server console path",
      • "created_by": "hee-1397",
      • "created_by_name": "hee-1397",
      • "created_at": "2026-11-17T01:44:20.534850Z",
      • "updated_at": "2026-11-17T01:44:20.585109Z"
      },
    • "relationships": {
      • "parent": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/assets/prj_soa/bookmarks/01a1e72d-2f38-72f6-b048-1ec283deedf6",
      • "parent": "/api/projects/opc/assets/prj_soa"
      }
    }
}

Delete bookmark

Delete a bookmark for a specific project, environment or asset.

path Parameters
project_code
required
string
Example: opc

project code

asset_code
required
string
Example: prj_soa

asset code

bookmark_id
required
string
Example: 01a1e72a-f4bc-7668-879e-e5460a929fb9

bookmark id

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    • {
      • "status": 403,
      • "title": "You do not have permission to delete the bookmark",
      • "detail": "Your authorisation rules let you view the bookmark but not delete it."
      }
    ]
}

MintModels

Endpoints to query and generate MintModels for assets.

Notes:

  • The list, show and generate MintModel endpoints are available for all assets, via the /<path/to/mintmodel/owner>/mintmodels path. The example endpoints in this section reflect MintModels owned by a project asset.
  • The list and show endpoints will display all MintModels for the asset, regardless whether they were applied successfully or not. Use the parent_mintmodel_history link in the API response to access the asset's MintModel history.

List MintModel history

Lists the asset's MintModel history.

path Parameters
project_code
required
string
Example: opc

project code

asset_code
required
string
Example: prj_soa

asset code

query Parameters
filter[<query/sort filter>]=
string
Example: filter[<query/sort filter>]==> filter[created_at_gteq]=2026-01-01
limit
integer [ 1 .. 10000 ]
Default: 100
Example: limit=50

Limit the number of MintModel history records returned. When more records match than the limit a 206 response is returned and meta.partial_response is true.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e72f-5589-77a1-937f-0ea6dbbfc9dc",
      • "type": "mintmodel_history",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true
      },
    • "partial_response": false
    }
}

Show MintModel history

Shows an asset's MintModel history record.

path Parameters
project_code
required
string
Example: opc

project code

asset_code
required
string
Example: prj_soa

asset code

id
required
string
Example: 01a1e72b-130a-7e21-9cc3-6d6aefc88ae4

MintModel history id

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72f-582b-7271-aaa2-4e2376b17095",
    • "type": "mintmodel_history",
    • "attributes": {
      • "created_at": "2026-11-17T01:46:42.090426Z",
      • "updated_at": "2026-11-17T01:46:42.090426Z"
      },
    • "relationships": {
      • "parents": {
        },
      • "mintmodel": {
        },
      • "opschain_changes": {
        },
      • "template_version": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/assets/prj_soa/mintmodel_history/01a1e72f-582b-7271-aaa2-4e2376b17095"
      }
    },
  • "included": [
    • {
      • "id": "01a1e72f-5823-7fdb-9d06-d8b2041d19ca",
      • "type": "mintmodel",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      }
    ]
}

List MintModels

List all MintModels for an asset.

path Parameters
project_code
required
string
Example: opc

project code

asset_code
required
string
Example: prj_soa

asset code

query Parameters
version
string
Example: version=2023_Q4_2

Return only the unique MintModels that have been generated for the asset while this version of its template was assigned. Returns an error if the version has never been assigned to the asset.

filter[<query/sort filter>]=
string
Example: filter[<query/sort filter>]==> filter[created_at_gteq]=2026-01-01
limit
integer [ 1 .. 10000 ]
Default: 100
Example: limit=50

Limit the number of MintModels returned. When more records match than the limit a 206 response is returned and meta.partial_response is true.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e72f-58e2-7275-885b-8ded173623bb",
      • "type": "mintmodel",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true
      },
    • "partial_response": false
    }
}

Generate MintModel diff

Generate a MintModel of the differences between two existing MintModels.

path Parameters
project_code
required
string
Example: opc

project code

asset_code
required
string
Example: prj_soa

asset code

old_mintmodel_id
required
string
Example: 01a1e72b-0d72-7e31-b132-498591860a2f

old MintModel id

new_mintmodel_id
required
string
Example: 01a1e72b-0d89-7d2d-a901-66f3aff31d8d

new MintModel id

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "MintModelDiff",
    • "type": "diff_mintmodel",
    • "attributes": {
      • "diff_mintmodel": {
        },
      • "step_trees": [
        ]
      },
    • "links": {
      • "old_mintmodel": "/projects/opc/assets/prj_soa/mintmodels/01a1e72f-5d89-773e-81fd-8749a059ef76",
      • "new_mintmodel": "/projects/opc/assets/prj_soa/mintmodels/01a1e72f-5d97-7cde-9cbd-52e2cf6d9d3a",
      • "parent": "/projects/opc/assets/prj_soa"
      }
    }
}

Show MintModel

Shows an asset MintModel.

path Parameters
project_code
required
string
Example: opc

project code

asset_code
required
string
Example: prj_soa

asset code

mintmodel_id
required
string
Example: 01a1e72a-f4ec-7e39-90fa-4eb14b08fdab

MintModel id

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72f-615b-7dca-b8b6-05f7e6ecc427",
    • "type": "mintmodel",
    • "attributes": {
      • "data": {
        },
      • "sha256": "77526a9ef926aee8c98f90ec845f5bd12f58cd7afb29fb2db5ef8f95deec44f8",
      • "created_at": "2026-11-17T01:46:44.441512Z",
      • "updated_at": "2026-11-17T01:46:44.441512Z",
      • "render_logs": {
        },
      • "phase_output": { }
      },
    • "relationships": {
      • "mintmodel_history": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/assets/prj_soa/mintmodels/01a1e72f-615b-7dca-b8b6-05f7e6ecc427",
      • "parent_mintmodel_history": "/api/projects/opc/assets/prj_soa/mintmodel_history"
      }
    }
}

Concretise MintModel

Concretise the MintModel for this asset in the background, using the latest properties and template version.

Note: This enqueues a MintModel concretisation task and returns it immediately. Poll the returned task to track its progress; the concretised MintModel is assigned to the asset once the task completes successfully.

path Parameters
project_code
required
string
Example: opc

project code

asset_code
required
string
Example: prj_soa

asset code

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72f-69ef-7042-99ca-4d9d099d46de",
    • "type": "node_background_task",
    • "attributes": {
      • "request_number": 2,
      • "status_code": "initializing",
      • "error_message": null,
      • "created_by": "logged_in_user",
      • "created_by_name": "logged_in_user",
      • "actions_count": 0,
      • "task_type": "MintModelConcretiseTask",
      • "created_at": "2026-11-17T01:46:46.637603Z",
      • "updated_at": "2026-11-17T01:46:46.637603Z"
      },
    • "relationships": {
      • "template_version_history": {
        },
      • "owner": {
        }
      },
    • "links": {
      • "template_version": "/api/projects/opc/templates/01a1e72f-68ee-7286-9701-e5cbb7fe900a/versions/2023_Q4_2",
      • "self": "/api/projects/opc/assets/prj_soa/node_background_tasks/01a1e72f-69ef-7042-99ca-4d9d099d46de",
      • "asset": "/api/projects/opc/assets/prj_soa",
      • "log_lines": "/api/node_background_task_log_lines?node_background_task_id=01a1e72f-69ef-7042-99ca-4d9d099d46de"
      }
    }
}

Workflows

Endpoints to interact with project workflows

List workflows

Lists all workflows for a project.

path Parameters
project_code
required
string
Example: opc

project code

query Parameters
filter[<query/sort filter>]=
string
Example: filter[<query/sort filter>]==> filter[name_cont]=deploy

API filtering guide. Named filters: filter[created_by_eq], filter[created_by_in].

limit
integer [ 1 .. 10000 ]
Default: 100
Example: limit=50

Limit the number of workflows returned. When more records match than the limit a 206 response is returned and meta.partial_response is true.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e736-74a1-7094-9a7e-3aeb104997d3",
      • "type": "workflow",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true,
      • "delete": true
      },
    • "partial_response": false
    }
}

Create workflow

Create a workflow

path Parameters
project_code
required
string
Example: opc

project code

Request Body schema: application/vnd.api+json
required
object
object

Responses

Request samples

Content type
application/vnd.api+json
Example
{
  • "data": {
    • "attributes": {
      • "code": "ypfez",
      • "archived": false,
      • "name": "ziihv8jvbk",
      • "description": "You can't connect the matrix without quantifying the wireless SDD microchip!",
      • "steps": [
        ],
      • "draft": true
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e736-79e6-7d0f-91b7-e07526797a4a",
    • "type": "workflow",
    • "attributes": {
      • "code": "assets_new",
      • "name": "assets workflow_new",
      • "description": null,
      • "draft": false,
      • "archived": false,
      • "created_by": "logged_in_user",
      • "created_by_name": "logged_in_user",
      • "created_at": "2026-11-17T01:54:29.478005Z",
      • "updated_at": "2026-11-17T01:54:29.478005Z",
      • "source_yaml": "---\nsteps:\n- type: change\n name: run asset action\n target: \"/projects/opc/assets/prj_soa\"\n action: run\n",
      • "steps": [
        ],
      • "resolved_steps": [ ],
      • "sample_properties": { },
      • "latest_version": 1,
      • "latest_published_version": 1
      },
    • "relationships": {
      • "parent": {
        },
      • "versions": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/workflows/assets_new",
      • "runs": "/api/projects/opc/workflows/assets_new/runs",
      • "versions": "/api/projects/opc/workflows/assets_new/versions",
      • "latest_version": "/api/projects/opc/workflows/assets_new/versions/1",
      • "latest_published_version": "/api/projects/opc/workflows/assets_new/versions/1"
      }
    }
}

Show workflow

Shows a workflow.

path Parameters
project_code
required
string
Example: opc

project code

workflow_code
required
string
Example: assets

workflow code

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e736-8885-7dda-b3b3-5215924e33c7",
    • "type": "workflow",
    • "attributes": {
      • "code": "assets",
      • "name": "assets workflow",
      • "description": "workflow for assets",
      • "draft": false,
      • "archived": false,
      • "created_by": "isa-6117",
      • "created_by_name": "isa-6117",
      • "created_at": "2026-11-17T01:54:33.221133Z",
      • "updated_at": "2026-11-17T01:54:33.221133Z",
      • "source_yaml": "---\nsteps:\n- type: change\n name: run asset action\n target: \"/projects/opc/assets/prj_soa\"\n action: run\n",
      • "steps": [
        ],
      • "resolved_steps": [ ],
      • "sample_properties": {
        },
      • "latest_version": 2,
      • "latest_published_version": 2
      },
    • "relationships": {
      • "parent": {
        },
      • "versions": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/workflows/assets",
      • "runs": "/api/projects/opc/workflows/assets/runs",
      • "versions": "/api/projects/opc/workflows/assets/versions",
      • "latest_version": "/api/projects/opc/workflows/assets/versions/2",
      • "latest_published_version": "/api/projects/opc/workflows/assets/versions/2"
      }
    }
}

Update workflow

Update a workflow.

Once the workflow has been run (or scheduled to run), its steps, source YAML and draft state can no longer be changed. A validation request that supplies custom sample properties (property_overrides with validate_flag set) is still permitted, so the stored steps can be validated against those properties.

path Parameters
project_code
required
string
Example: opc

project code

workflow_code
required
string
Example: assets

workflow code

Request Body schema: application/vnd.api+json
required
object
object

Responses

Request samples

Content type
application/vnd.api+json
Example
{
  • "data": {
    • "attributes": {
      • "archived": false,
      • "name": "kqwskvaupr",
      • "description": "Try to copy the GB alarm, maybe it will synthesize the neural port!",
      • "steps": [
        ],
      • "draft": true
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e736-8d18-78fd-8db4-f4e7f869ed34",
    • "type": "workflow",
    • "attributes": {
      • "code": "assets",
      • "name": "new workflow name",
      • "description": "new description",
      • "draft": false,
      • "archived": false,
      • "created_by": "sam-6135",
      • "created_by_name": "sam-6135",
      • "created_at": "2026-11-17T01:54:34.391379Z",
      • "updated_at": "2026-11-17T01:54:34.504288Z",
      • "source_yaml": "---\nsteps:\n- type: change\n name: run asset action\n target: \"/projects/opc/assets/prj_soa\"\n action: run\n",
      • "steps": [
        ],
      • "resolved_steps": [
        ],
      • "sample_properties": {
        },
      • "latest_version": 2,
      • "latest_published_version": 2
      },
    • "relationships": {
      • "parent": {
        },
      • "versions": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/workflows/assets",
      • "runs": "/api/projects/opc/workflows/assets/runs",
      • "versions": "/api/projects/opc/workflows/assets/versions",
      • "latest_version": "/api/projects/opc/workflows/assets/versions/2",
      • "latest_published_version": "/api/projects/opc/workflows/assets/versions/2"
      }
    }
}

Delete workflow

Delete or archive a workflow.

  • If the workflow has not been run before, it will be deleted.
  • If the workflow has been run before, it will be archived and all draft and unused versions will be deleted..
path Parameters
project_code
required
string
Example: opc

project code

workflow_code
required
string
Example: assets

workflow code

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    • {
      • "status": 403,
      • "title": "You do not have permission to delete the workflow",
      • "detail": "Your authorisation rules let you view the workflow but not delete it."
      }
    ]
}

Workflow versions

List workflow versions

Lists all versions for a workflow.

path Parameters
project_code
required
string
Example: opc

project code

workflow_code
required
string
Example: assets

workflow code

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e736-a3b9-7d07-803e-02705f410565",
      • "type": "workflow_version",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e736-a3b3-7374-b29a-6553520dd842",
      • "type": "workflow_version",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true,
      • "delete": true,
      • "execute": true
      }
    }
}

Delete draft workflow versions

Deletes all draft versions of a workflow.

Note: At least one version will remain. If all versions are drafts, the latest draft version will be kept.

path Parameters
project_code
required
string
Example: opc

project code

workflow_code
required
string
Example: assets

workflow code

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e736-aecc-74d4-9b8a-abc20eaff84a",
    • "type": "workflow",
    • "attributes": {
      • "code": "assets",
      • "name": "assets workflow",
      • "description": "workflow for assets",
      • "draft": false,
      • "archived": false,
      • "created_by": "eboni_zemlak-6242",
      • "created_by_name": "eboni_zemlak-6242",
      • "created_at": "2026-11-17T01:54:43.019486Z",
      • "updated_at": "2026-11-17T01:54:43.019486Z",
      • "source_yaml": "---\nsteps:\n- type: change\n name: run asset action\n target: \"/projects/opc/assets/prj_soa\"\n action: run\n",
      • "steps": [
        ],
      • "resolved_steps": [ ],
      • "sample_properties": {
        },
      • "latest_version": 2,
      • "latest_published_version": 2
      },
    • "relationships": {
      • "parent": {
        },
      • "versions": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/workflows/assets",
      • "runs": "/api/projects/opc/workflows/assets/runs",
      • "versions": "/api/projects/opc/workflows/assets/versions",
      • "latest_version": "/api/projects/opc/workflows/assets/versions/2",
      • "latest_published_version": "/api/projects/opc/workflows/assets/versions/2"
      }
    }
}

Show workflow version

Shows a workflow version.

path Parameters
project_code
required
string
Example: opc

project code

workflow_code
required
string
Example: assets

workflow code

version
required
string
Example: 2

version

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e736-b95e-771a-a1ca-9312639c3e57",
    • "type": "workflow_version",
    • "attributes": {
      • "code": "assets",
      • "name": "assets workflow",
      • "description": "workflow for assets",
      • "draft": false,
      • "archived": false,
      • "created_by": "devorah_kuhn-6282",
      • "created_by_name": "devorah_kuhn-6282",
      • "created_at": "2026-11-17T01:54:45.725484Z",
      • "updated_at": "2026-11-17T01:54:45.752572Z",
      • "source_yaml": "---\nsteps:\n- type: change\n name: run asset action\n target: \"/projects/opc/assets/prj_soa\"\n action: run\n",
      • "steps": [
        ],
      • "resolved_steps": [ ],
      • "sample_properties": {
        },
      • "version": 2
      },
    • "relationships": {
      • "parent": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/workflows/assets/versions/2",
      • "runs": "/api/projects/opc/workflows/assets/versions/2/runs",
      • "workflow": "/api/projects/opc/workflows/assets"
      }
    }
}

Update workflow

Update a workflow version.

Once the workflow version has been run (or scheduled to run), its steps, source YAML and draft state can no longer be changed. A validation request that supplies custom sample properties (property_overrides with validate_flag set) is still permitted, so the stored steps can be validated against those properties.

path Parameters
project_code
required
string
Example: opc

project code

workflow_code
required
string
Example: assets

workflow code

version
required
string
Example: 2

version

Request Body schema: application/vnd.api+json
required
object
object

Responses

Request samples

Content type
application/vnd.api+json
Example
{
  • "data": {
    • "attributes": {
      • "code": "wdq9c",
      • "node_id": "01a1e72b-44e9-755d-94fa-414cc56a51cc",
      • "archived": false,
      • "name": "gbaewzmwif",
      • "description": "Connecting the microchip won't do anything, we need to bypass the wireless ai monitor!",
      • "steps": [
        ],
      • "draft": true
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e736-c382-7baa-bba7-877f892ebe89",
    • "type": "workflow_version",
    • "attributes": {
      • "code": "assets",
      • "name": "new workflow name",
      • "description": "new description",
      • "draft": true,
      • "archived": false,
      • "created_by": "ramiro_lueilwitz-6318",
      • "created_by_name": "ramiro_lueilwitz-6318",
      • "created_at": "2026-11-17T01:54:48.321690Z",
      • "updated_at": "2026-11-17T01:54:48.389082Z",
      • "source_yaml": "---\nsteps:\n- type: change\n name: run asset action\n target: \"/projects/opc/assets/prj_soa\"\n action: run\n",
      • "steps": [
        ],
      • "resolved_steps": [ ],
      • "sample_properties": {
        },
      • "version": 2
      },
    • "relationships": {
      • "parent": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/workflows/assets/versions/2",
      • "runs": "/api/projects/opc/workflows/assets/versions/2/runs",
      • "workflow": "/api/projects/opc/workflows/assets"
      }
    }
}

Delete workflow version

Delete or archive a workflow version.

  • If the workflow version has not been run before, it will be deleted.
  • If the workflow version has been run before, it will be archived.
path Parameters
project_code
required
string
Example: opc

project code

workflow_code
required
string
Example: assets

workflow code

version
required
string
Example: 2

version

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    • {
      • "status": 403,
      • "title": "You do not have permission to delete the workflow version",
      • "detail": "Your authorisation rules let you view the workflow version but not delete it."
      }
    ]
}

Clone nodes

Clone an environment or asset

Clones an environment's properties, settings and assets, or a single asset's properties and settings, into a new or existing node of the same type in the same project. Assets may be cloned between the project and its environments. Nothing is removed from the target, and nothing is written if any node fails validation.

Secrets in the cloned documents are cloned as they are, and listed by key path in warnings. Set dry_run to see the report without writing anything. Actions for created assets are generated in the background after the clone returns.

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "source_path": "/projects/opc/environments/dev",
      • "target_path": "/projects/opc/environments/uat",
      • "target": {
        },
      • "properties": "skip",
      • "settings": "skip",
      • "assets": {
        },
      • "dry_run": false
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "/projects/opc/environments/dev:/projects/opc/environments/uat",
    • "type": "node_clone",
    • "attributes": {
      • "source_path": "/projects/opc/environments/dev",
      • "target_path": "/projects/opc/environments/uat",
      • "dry_run": true,
      • "summary": {
        },
      • "nodes": [
        ],
      • "warnings": [ ]
      }
    }
}

Properties

Endpoints to interact with properties.

Show properties

Shows the current properties JSON and its version.

path Parameters
properties_id
required
string
Example: 01a1e72a-f052-70c4-8e7b-0be691c20308

properties id

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e730-9d6b-7e9d-9057-f81787b1184a",
    • "type": "properties",
    • "attributes": {
      • "data": {
        },
      • "version": 1,
      • "created_at": "2026-11-17T01:48:05.354482Z"
      },
    • "relationships": {
      • "owner": {
        }
      },
    • "links": {
      • "self": "/api/properties/01a1e730-9d6b-7e9d-9057-f81787b1184a",
      • "current_version": "/api/properties/01a1e730-9d6b-7e9d-9057-f81787b1184a/versions/1",
      • "versions": "/api/properties/01a1e730-9d6b-7e9d-9057-f81787b1184a/versions"
      }
    }
}

Update properties

Updates a properties JSON if the included version matches the current properties version.

path Parameters
id_to_update
required
string
Example: 01a1e72a-f052-70c4-8e7b-0be691c20308

properties id

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "data": {
        },
      • "version": 1
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e730-a1de-7662-936e-9b47b2891a3a",
    • "type": "properties",
    • "attributes": {
      • "data": {
        },
      • "version": 2,
      • "created_at": "2026-11-17T01:48:06.492650Z"
      },
    • "relationships": {
      • "owner": {
        }
      },
    • "links": {
      • "self": "/api/properties/01a1e730-a1de-7662-936e-9b47b2891a3a",
      • "current_version": "/api/properties/01a1e730-a1de-7662-936e-9b47b2891a3a/versions/2",
      • "versions": "/api/properties/01a1e730-a1de-7662-936e-9b47b2891a3a/versions"
      }
    }
}

Update properties (unsafe)

Updates a properties JSON, without any version checking (always updates).

path Parameters
id_to_set
required
string
Example: 01a1e72a-f052-70c4-8e7b-0be691c20308

properties id

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "data": {
        }
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e730-a821-7ecb-9856-49ac1a00e8f1",
    • "type": "properties",
    • "attributes": {
      • "data": {
        },
      • "version": 2,
      • "created_at": "2026-11-17T01:48:08.096874Z"
      },
    • "relationships": {
      • "owner": {
        }
      },
    • "links": {
      • "self": "/api/properties/01a1e730-a821-7ecb-9856-49ac1a00e8f1",
      • "current_version": "/api/properties/01a1e730-a821-7ecb-9856-49ac1a00e8f1/versions/2",
      • "versions": "/api/properties/01a1e730-a821-7ecb-9856-49ac1a00e8f1/versions"
      }
    }
}

Create or update a file property

Create or update a file property in the properties.

Notes:

  • When the file is stored in the secret vault and you hold no secret vault credential for the properties owner and its vault, the request is rejected, and the error's meta.secret_vault_credential_required lists the vault a credential is needed for.
path Parameters
properties_id
required
string
Example: 01a1e72a-f052-70c4-8e7b-0be691c20308

properties id

Request Body schema: multipart/form-data
file_path
string (Path to write the file within /opt/opschain)
mode
string (Linux octal file mode)
format
string (How the file content is serialised (default: 'raw'))
Enum: "base64" "json" "raw"
replace_file
string (Replace the file property if it exists (default: false))
secret_path
string (Path to write the secret key into)
secret_key
string
replace_secret
string (Replace the secret vault value if it exists (default: false))
file
string <binary>

File to use. The filename is ignored.

Responses

Request samples

Content type
multipart/form-data
------------XnJLe9ZIbbGUYtzPQJ16u1
content-disposition: form-data; name="mode"

0600
------------XnJLe9ZIbbGUYtzPQJ16u1
content-disposition: form-data; name="file_path"

/opt/opschain/sample.txt
------------XnJLe9ZIbbGUYtzPQJ16u1
content-disposition: form-data; name="format"

raw
------------XnJLe9ZIbbGUYtzPQJ16u1
content-disposition: form-data; name="replace_file"

true
------------XnJLe9ZIbbGUYtzPQJ16u1
content-disposition: form-data; name="file"; filename="sample.txt"
content-type: text/plain
content-length: 21

Sample file property

------------XnJLe9ZIbbGUYtzPQJ16u1--

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e730-b023-7ebb-9633-980f9c148118",
    • "type": "properties",
    • "attributes": {
      • "data": {
        },
      • "version": 2,
      • "created_at": "2026-11-17T01:48:10.117553Z"
      },
    • "relationships": {
      • "owner": {
        }
      },
    • "links": {
      • "self": "/api/properties/01a1e730-b023-7ebb-9633-980f9c148118",
      • "current_version": "/api/properties/01a1e730-b023-7ebb-9633-980f9c148118/versions/2",
      • "versions": "/api/properties/01a1e730-b023-7ebb-9633-980f9c148118/versions"
      }
    }
}

Properties versions

Endpoints to interact with the version history for properties.

List properties versions

Lists all versions of an OpsChain properties.

path Parameters
properties_id
required
string
Example: 01a1e72a-f052-70c4-8e7b-0be691c20308

properties id

query Parameters
limit
integer [ 1 .. 10000 ]
Default: 1000
Example: limit=50

Limit the number of properties versions returned. When more records match than the limit a 206 response is returned and meta.partial_response is true.

exclude_data
boolean
Default: false
Example: exclude_data=true

Exclude the data attribute from each of the properties versions returned. Use the show endpoint to fetch the data for an individual version.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e730-b539-76e5-adaf-059ab4f51d51",
      • "type": "properties_version",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": { }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true
      },
    • "partial_response": false
    }
}

Show properties version

Shows the properties JSON for this properties version.

path Parameters
properties_id
required
string
Example: 01a1e72a-f052-70c4-8e7b-0be691c20308

properties id

version_number
required
integer
Example: 1

version number

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e730-b6de-732b-b847-792bc209e6ad",
    • "type": "properties_version",
    • "attributes": {
      • "data": {
        },
      • "version": 1,
      • "created_at": "2026-11-17T01:48:11.869247Z",
      • "owner_type": "Project"
      },
    • "relationships": {
      • "properties": {
        }
      },
    • "links": {
      • "versions": "/api/properties/01a1e730-b6d6-7c43-aef8-148b12e94509/versions",
      • "owner": "/api/projects/opc",
      • "self": "/api/properties/01a1e730-b6d6-7c43-aef8-148b12e94509/versions/1"
      },
    • "meta": { }
    }
}

Activities

Endpoints to interact with activities (changes and workflow runs combined).

List activities

Lists all activities (changes and workflow runs) accessible to the user.

query Parameters
limit
integer [ 1 .. 1000 ]
Default: 100
Example: limit=100

The maximum number of activities to return. When more records match than the limit a 206 response is returned and meta.partial_response is true.

exact_count
boolean
Example: exact_count=true

By default meta.total_matching_filter stops counting at 1000 and meta.total_matching_filter_exact reports false. Set this to count every matching activity instead - this is significantly slower on instances with a large activity history.

filter[<query/sort filter>]=
string
Example: filter[<query/sort filter>]==> filter[created_by_cont]=opschain

API filtering guide. Named filters: filter[active_over], filter[arm_taken_eq], filter[exclude_archived]. Use filter[exclude_archived]=true to leave out changes whose node, one of its ancestors or git remote is archived, and workflow runs whose workflow, workflow version or project is archived. Use filter[arm_taken_eq]=<arm name> (for example on_failure) to return only the changes and workflow runs that took that arm of a branching step.

download
string
Example: download=activities.csv

Download activities in CSV format with the specified file name. The activities will be ordered from oldest to newest when this parameter is specified, irrespective of the sort order or limit requested.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e72b-6046-7370-8c33-ef43c065ced5",
      • "type": "workflow_run",
      • "attributes": {
        },
      • "links": {
        },
      • "meta": {
        }
      },
    • {
      • "id": "01a1e72b-5f31-784c-968e-dc4e46e45d51",
      • "type": "change",
      • "attributes": {
        },
      • "links": {
        },
      • "meta": {
        }
      },
    • {
      • "id": "01a1e72b-5bb1-75a6-a03f-c3502d5ca137",
      • "type": "change",
      • "attributes": {
        },
      • "links": {
        },
      • "meta": {
        }
      },
    • {
      • "id": "01a1e72b-59a8-7d4c-8015-931109604214",
      • "type": "workflow_run",
      • "attributes": {
        },
      • "links": {
        },
      • "meta": {
        }
      },
    • {
      • "id": "01a1e72b-5719-7b82-b8c1-e10df874d5b0",
      • "type": "change",
      • "attributes": {
        },
      • "links": {
        },
      • "meta": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true
      },
    • "partial_response": false,
    • "has_any": true,
    • "total_matching_filter": 5,
    • "total_matching_filter_exact": true
    }
}

Changes

Endpoints to interact with changes.

Get a running change's latest memory snapshot

The pod's memory in use and limit, and the memory held by each of the change's processes, as the executor last sampled them. The executor refreshes the snapshot every few seconds while the change runs. data is null before its first sample and once the change has finished.

path Parameters
change_id
required
string
Example: 01a1e72a-f8ec-78fe-b4ca-5e5595b30df0

change id

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72d-4aff-7f01-916a-087dfb0ac738",
    • "type": "change_memory_snapshot",
    • "attributes": {
      • "sampled_at": "2025-11-13T02:13:20Z",
      • "used_bytes": 3221225472,
      • "limit_bytes": 4294967296,
      • "processes": [
        ]
      }
    }
}

List changes

Lists all changes.

query Parameters
filter[<query/sort filter>]=
string
Example: filter[<query/sort filter>]==> filter[environment_code_eq]=dev

API filtering guide. Named filters: filter[active], filter[active_over], filter[created_by_eq], filter[created_by_in], filter[exclude_archived], filter[finished], filter[step_action_or_name_eq], filter[step_action_or_name_in], filter[waiting_to_run]. filter[step_action_or_name_eq]=<action or step name> returns every change with a step whose action or step name matches, at any depth in the step tree, e.g. > filter[step_action_or_name_eq]=provision. The comparison ignores case. filter[step_action_or_name_in][]=<action or step name> does the same for several values, e.g. > filter[step_action_or_name_in][]=provision&filter[step_action_or_name_in][]=destroy. Use filter[exclude_archived]=true to leave out changes whose node, one of its ancestors or git remote is archived.

download
string
Example: download=changes.csv

Download changes in CSV format with the specified file name. The changes will be ordered from oldest to newest when this parameter is specified, irrespective of the sort order requested.

include
string
Example: include=steps,parents

Include the change steps and parents in the response

fields[<resource_type>]
string
Example: fields[<resource_type>]=code,status,action
limit
integer [ 1 .. 10000 ]
Default: 100
Example: limit=50

Limit the number of changes returned. When more records match than the limit a 206 response is returned and meta.partial_response is true.

include_children
boolean
Example: include_children=true

Only applies when the changes are being listed for a node - via a node path or parent_path. Include the changes of the node's descendants as well as its own.

total_count
boolean
Example: total_count=true

Report the number of changes matching the filter in meta.total_matching_filter, stopping at 1000 - meta.total_matching_filter_exact reports whether the count is exact. No count is computed unless this or exact_count is supplied.

exact_count
boolean
Example: exact_count=true

Report meta.total_matching_filter without a cap - this is significantly slower on instances with a large change history.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e72d-5124-7b62-a959-46af18af4106",
      • "type": "change",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": { }
      }
    ],
  • "included": [
    • {
      • "id": "01a1e72d-512b-7518-a02c-f83808ff8644",
      • "type": "step",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": { }
      },
    • {
      • "id": "01a1e72d-4fe1-71f7-ba5d-f31312317cb6",
      • "type": "project",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": {
        }
      },
    • {
      • "id": "01a1e72d-5092-7324-9aad-ef3843a438f8",
      • "type": "environment",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true,
      • "delete": true,
      • "execute": true
      },
    • "partial_response": false,
    • "has_any": true
    }
}

Create change

Creates a change in a specific project, environment or asset.

Notes:

  1. When creating changes via a project, environment or asset changes path (e.g. POST to /api/projects/{project_code}/changes) the parent_path request attributes must not be supplied as the parent will be derived from the path.
  2. When creating changes for assets (e.g. POST to /api/projects/{project_code}/assets/{asset_code}/changes) the git_remote_name and git_rev attributes must not be supplied as the Git remote and revision will be derived from the asset's template.
  3. Supplying the retry attribute (together with a change relationship) retries an existing change that finished in an error, cancelled or aborted state instead of creating a change from scratch. The retry creates a new change that reuses the original change's action, commit, properties and step tree; steps that already succeeded are preserved and are not run again. The original change is left untouched.
Request Body schema: application/vnd.api+json
One of
required
object

Responses

Request samples

Content type
application/vnd.api+json
Example
{
  • "data": {
    • "attributes": {
      • "metadata": {
        },
      • "scheduled_activity_id": null,
      • "build_without_cache": false,
      • "pod_per_step": true,
      • "action_path": null,
      • "static_settings": { },
      • "state_timing_summary": { },
      • "notify": { },
      • "api_key_id": null,
      • "skip_steps": [ ],
      • "auto_continue_wait_steps": false,
      • "starting_step": null,
      • "generate_actions_request_id": null,
      • "paused_at": null,
      • "executor_queue_name": null,
      • "action": "calculate",
      • "parent_path": "/projects/opc/environments/dev/assets/env_soa",
      • "template_version": "2023_Q4_2"
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72d-5dba-7084-a69b-635f74b0f457",
    • "type": "change",
    • "attributes": {
      • "created_by": "logged_in_user",
      • "created_by_name": "logged_in_user",
      • "step_name": "reboot",
      • "action": "reboot",
      • "build_without_cache": false,
      • "auto_continue_wait_steps": false,
      • "initial_step_tree": { },
      • "metadata": {
        },
      • "scheduled": false,
      • "approved_by": [ ],
      • "rejected_by": [ ],
      • "cancelled_by": null,
      • "state_timing": {
        },
      • "state_timing_summary": { },
      • "notify": { },
      • "skip_steps": [ ],
      • "starting_step": null,
      • "cluster_name": null,
      • "pause_state": "none",
      • "status_code": "initializing",
      • "paused": false,
      • "cancel_requested": false,
      • "paused_by": [ ],
      • "created_at": "2026-11-17T01:44:32.440749Z",
      • "started_at": "2026-11-17T01:44:32.378695Z",
      • "finished_at": null,
      • "updated_at": "2026-11-17T01:44:32.453312Z",
      • "paused_at": null,
      • "asset_name": null,
      • "environment_name": "Development",
      • "project_name": "OpsChain",
      • "git_remote_name": "github",
      • "git_rev": "main",
      • "commit_sha": null,
      • "requires_approval_from": null
      },
    • "relationships": {
      • "parents": {
        },
      • "root_step": {
        },
      • "steps": {
        },
      • "workflow_run": {
        },
      • "workflow": {
        },
      • "override_properties": {
        },
      • "override_settings": {
        }
      },
    • "links": {
      • "git_remote": "/api/projects/opc/git_remotes/01a1e72d-597d-797e-b183-ff62b36fd045",
      • "project": "/api/projects/opc",
      • "parent": "/api/projects/opc/environments/dev",
      • "self": "/api/projects/opc/environments/dev/changes/01a1e72d-5dba-7084-a69b-635f74b0f457",
      • "log_lines": "/api/changes/01a1e72d-5dba-7084-a69b-635f74b0f457/log_lines",
      • "pause": "/api/changes/01a1e72d-5dba-7084-a69b-635f74b0f457/pause"
      },
    • "meta": { }
    },
  • "included": [
    • {
      • "id": "01a1e72d-5dbf-7b87-b39a-9898fde68b23",
      • "type": "step",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": { }
      }
    ]
}

Show change

Shows a change, including it's parent nodes.

path Parameters
change_id
required
string
Example: 01a1e72a-f8ec-78fe-b4ca-5e5595b30df0

change id

query Parameters
include
string
Example: include=steps,parents

Include the change steps and parents in the response

fields[<resource_type>]
string
Example: fields[<resource_type>]=code,status,action

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72d-728a-7c4a-b533-67870026d5f9",
    • "type": "change",
    • "attributes": {
      • "created_by": "wilbur_schiller-1501",
      • "created_by_name": "wilbur_schiller-1501",
      • "step_name": "override",
      • "action": "override",
      • "build_without_cache": false,
      • "auto_continue_wait_steps": false,
      • "initial_step_tree": { },
      • "metadata": {
        },
      • "scheduled": false,
      • "approved_by": [ ],
      • "rejected_by": [ ],
      • "cancelled_by": null,
      • "state_timing": {
        },
      • "state_timing_summary": { },
      • "notify": { },
      • "skip_steps": [ ],
      • "starting_step": null,
      • "cluster_name": null,
      • "pause_state": "none",
      • "status_code": "success",
      • "paused": false,
      • "cancel_requested": false,
      • "paused_by": [ ],
      • "created_at": "2026-11-17T01:44:37.768748Z",
      • "started_at": "2026-11-17T01:39:11.212718Z",
      • "finished_at": "2026-11-17T01:39:25.791202Z",
      • "updated_at": "2026-11-17T01:44:37.792443Z",
      • "paused_at": null,
      • "asset_name": null,
      • "environment_name": "Development",
      • "project_name": "OpsChain",
      • "git_remote_name": "github",
      • "git_rev": "main",
      • "commit_sha": "b73d05779fbc5e604ac637e1580274498cca4b7a",
      • "requires_approval_from": null
      },
    • "relationships": {
      • "properties": {
        },
      • "parents": {
        },
      • "root_step": {
        },
      • "steps": {
        },
      • "workflow_run": {
        },
      • "workflow": {
        },
      • "override_properties": {
        },
      • "override_settings": {
        }
      },
    • "links": {
      • "git_remote": "/api/projects/opc/git_remotes/01a1e72d-71a5-7f83-9466-118a34238e83",
      • "project": "/api/projects/opc",
      • "parent": "/api/projects/opc/environments/dev",
      • "self": "/api/projects/opc/environments/dev/changes/01a1e72d-728a-7c4a-b533-67870026d5f9",
      • "log_lines": "/api/changes/01a1e72d-728a-7c4a-b533-67870026d5f9/log_lines"
      },
    • "meta": {
      • "wait_queue": [ ],
      • "blocking_queue": [ ],
      • "authorisations": {
        },
      • "comparable": true
      }
    },
  • "included": [
    • {
      • "id": "01a1e72d-7296-706b-a029-0b37999c80d7",
      • "type": "step",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": { }
      },
    • {
      • "id": "01a1e72d-6fd0-7dfc-972f-c5552d8b44ae",
      • "type": "project",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": {
        }
      },
    • {
      • "id": "01a1e72d-70ec-7fd5-8738-dff220f48615",
      • "type": "environment",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": {
        }
      }
    ]
}

Cancel change

Cancels a change.

path Parameters
change_id
required
string
Example: 01a1e72a-f8ec-78fe-b4ca-5e5595b30df0

change id

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    • {
      • "status": 403,
      • "title": "You do not have permission to cancel the change",
      • "detail": "Your authorisation rules let you view the change but not cancel it."
      }
    ]
}

Pause change

Pauses a running change. Steps already running finish, but no further steps are dispatched until the change is resumed.

path Parameters
change_id
required
string
Example: 01a1e72a-f8ec-78fe-b4ca-5e5595b30df0

change id

Request Body schema: application/vnd.api+json
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "reason": "Holding this change until the database maintenance window closes"
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72d-8f66-7019-b7f9-6e5124697521",
    • "type": "change",
    • "attributes": {
      • "created_by": "marge.walker-1535",
      • "created_by_name": "marge.walker-1535",
      • "step_name": "override",
      • "action": "override",
      • "build_without_cache": false,
      • "auto_continue_wait_steps": false,
      • "initial_step_tree": { },
      • "metadata": {
        },
      • "scheduled": false,
      • "approved_by": [ ],
      • "rejected_by": [ ],
      • "cancelled_by": null,
      • "state_timing": {
        },
      • "state_timing_summary": { },
      • "notify": { },
      • "skip_steps": [ ],
      • "starting_step": null,
      • "cluster_name": null,
      • "pause_state": "pausing",
      • "status_code": "running",
      • "paused": true,
      • "cancel_requested": false,
      • "paused_by": [
        ],
      • "created_at": "2026-11-17T01:44:45.146203Z",
      • "started_at": "2026-11-17T01:36:59.695674Z",
      • "finished_at": null,
      • "updated_at": "2026-11-17T01:44:45.194497Z",
      • "paused_at": "2026-11-17T01:44:45.782047Z",
      • "asset_name": null,
      • "environment_name": "Development",
      • "project_name": "OpsChain",
      • "git_remote_name": "github",
      • "git_rev": "main",
      • "commit_sha": "a84f89ba0fb188c7eb15cd3cf94e120165e5c044",
      • "requires_approval_from": null
      },
    • "relationships": {
      • "properties": {
        },
      • "parents": {
        },
      • "root_step": {
        },
      • "steps": {
        },
      • "workflow_run": {
        },
      • "workflow": {
        },
      • "override_properties": {
        },
      • "override_settings": {
        }
      },
    • "links": {
      • "git_remote": "/api/projects/opc/git_remotes/01a1e72d-8e4c-7aee-a1d6-d3eda60e4c94",
      • "project": "/api/projects/opc",
      • "parent": "/api/projects/opc/environments/dev",
      • "self": "/api/projects/opc/environments/dev/changes/01a1e72d-8f66-7019-b7f9-6e5124697521",
      • "log_lines": "/api/changes/01a1e72d-8f66-7019-b7f9-6e5124697521/log_lines",
      • "resume": "/api/changes/01a1e72d-8f66-7019-b7f9-6e5124697521/resume"
      },
    • "meta": { }
    }
}

Resume change

Resumes a paused change, dispatching the steps that were held while it was paused.

path Parameters
change_id
required
string
Example: 01a1e72a-f8ec-78fe-b4ca-5e5595b30df0

change id

Request Body schema: application/vnd.api+json
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "reason": "Maintenance window closed"
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72d-aac7-7c00-9d4a-90c23f7b05a4",
    • "type": "change",
    • "attributes": {
      • "created_by": "margarete_predovic-1563",
      • "created_by_name": "margarete_predovic-1563",
      • "step_name": "navigate",
      • "action": "navigate",
      • "build_without_cache": false,
      • "auto_continue_wait_steps": false,
      • "initial_step_tree": { },
      • "metadata": {
        },
      • "scheduled": false,
      • "approved_by": [ ],
      • "rejected_by": [ ],
      • "cancelled_by": null,
      • "state_timing": {
        },
      • "state_timing_summary": { },
      • "notify": { },
      • "skip_steps": [ ],
      • "starting_step": null,
      • "cluster_name": null,
      • "pause_state": "none",
      • "status_code": "running",
      • "paused": false,
      • "cancel_requested": false,
      • "paused_by": [
        ],
      • "created_at": "2026-11-17T01:44:52.148912Z",
      • "started_at": "2026-11-17T01:38:40.713372Z",
      • "finished_at": null,
      • "updated_at": "2026-11-17T01:44:52.191106Z",
      • "paused_at": null,
      • "asset_name": null,
      • "environment_name": "Development",
      • "project_name": "OpsChain",
      • "git_remote_name": "github",
      • "git_rev": "main",
      • "commit_sha": "3a446bfe44af0a1a2b071086377428040611a166",
      • "requires_approval_from": null
      },
    • "relationships": {
      • "properties": {
        },
      • "parents": {
        },
      • "root_step": {
        },
      • "steps": {
        },
      • "workflow_run": {
        },
      • "workflow": {
        },
      • "override_properties": {
        },
      • "override_settings": {
        }
      },
    • "links": {
      • "git_remote": "/api/projects/opc/git_remotes/01a1e72d-a9be-7404-82c6-eb1657691988",
      • "project": "/api/projects/opc",
      • "parent": "/api/projects/opc/environments/dev",
      • "self": "/api/projects/opc/environments/dev/changes/01a1e72d-aac7-7c00-9d4a-90c23f7b05a4",
      • "log_lines": "/api/changes/01a1e72d-aac7-7c00-9d4a-90c23f7b05a4/log_lines",
      • "pause": "/api/changes/01a1e72d-aac7-7c00-9d4a-90c23f7b05a4/pause"
      },
    • "meta": { }
    }
}

Show change settings

Show the converged settings for a change, including any change-specific setting overrides merged on top of the asset's settings hierarchy. Unless include_global=true is passed, only the values that differ from the global settings are returned: a setting whose converged value matches the global value is omitted, even when it is set directly on a node, so the response is empty when nothing differs from the global settings.

The response includes a setting_sources meta object that attributes each setting value to its originating source.

path Parameters
change_id
required
string
Example: 01a1e72a-f8ec-78fe-b4ca-5e5595b30df0

change id

query Parameters
include_global
boolean
Example: include_global=true

Also return the settings whose converged value matches the global settings

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72d-c120-7569-a94c-e3255d1067c6",
    • "type": "converged_settings",
    • "attributes": {
      • "data": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/environments/dev/converged_settings"
      },
    • "meta": {
      • "setting_sources": {
        }
      }
    }
}

Show change properties

Converge the root step properties for a change.

The optional action_stage argument can be:

  • "pre" - to converge the properties as they were supplied to the root step action before it executed
  • "post" - to converge the properties as they were at the end of the latest completed step in the change
path Parameters
change_id
required
string
Example: 01a1e72a-f8ec-78fe-b4ca-5e5595b30df0

change id

query Parameters
action_stage
string
Example: action_stage=pre

Converge the pre or post action properties

exclude_layers[]
string
Example: exclude_layers[]=template

Exclude a property layer from the converged result. Repeat the parameter to exclude several layers, e.g. > exclude_layers[]=template&exclude_layers[]=asset. Suffix a layer with _repository or _database to exclude only that half of it, e.g. > exclude_layers[]=asset_repository. The layers available for the node, and whether each one is currently included, are listed in the property_layers response meta. The template layer covers the properties files held under the <template code> folder of the template repository, as well as the template's database properties; the template_version layer covers the template version database properties only. Excluding a layer is a preview - the result is not cached and nothing is persisted.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "calculate (post)",
    • "type": "converged_properties",
    • "attributes": {
      • "data": {
        }
      },
    • "relationships": {
      • "repository_properties": {
        },
      • "properties": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/environments/dev/converged_properties"
      },
    • "meta": {
      • "property_sources": {
        },
      • "property_layers": [
        ]
      }
    },
  • "included": [
    • {
      • "id": "01a1e72d-cddd-71bb-a95e-bdba83290188",
      • "type": "properties_version",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": { }
      },
    • {
      • "id": "01a1e72d-ce84-7685-aba8-e073d9fa91ce",
      • "type": "properties_version",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": { }
      },
    • {
      • "id": "01a1e72d-cf20-7a57-90d5-a5038209af9e",
      • "type": "properties_version",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": { }
      }
    ]
}

Download a support bundle for a change

Builds a zip archive of the information LimePoint support needs to diagnose a change: the change and its steps, its logs, the properties and settings in effect, its template and MintModel, server version information, recent runs of the same action and recent events. Each item is collected using the requesting user's permissions, so anything they cannot read is omitted or redacted. Items that could not be collected are listed in the archive's manifest.json and SUMMARY.md rather than failing the request.

path Parameters
change_id
required
string
Example: 01a1e72a-f8ec-78fe-b4ca-5e5595b30df0

change id

Request Body schema: application/vnd.api+json
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "log_limit": 2000,
      • "step_logs": "failed",
      • "time_zone": "Australia/Melbourne",
      • "client": {
        }
      }
    }
}

Response samples

Content type
application/zip
<binary data>

Scheduled activities

List activities

Lists all scheduled activities.

query Parameters
filter[<query/sort filter>]=
string
Example: filter[<query/sort filter>]==> filter[project_code_eq]=opc

API filtering guide. Named filters: filter[created_by_eq], filter[created_by_in], filter[exclude_archived], filter[with_label], filter[with_setting]. Use filter[exclude_archived]=true to leave out scheduled activities whose node or one of its ancestors is archived, whose git remote is archived, or whose workflow or pinned workflow version is archived. Filter by label with filter[with_label][]=<label> - repeat it to supply several labels, and the scheduled activity must carry all of them. Use filter[with_setting]=<path> (e.g. pod_templates.step_runner.resources.limits.memory) to find the scheduled activities whose settings overrides set that setting.

include
string
Example: include=parents

Include the scheduled change parents in the response

fields[<resource_type>]
string
Example: fields[<resource_type>]=code,status
include_children
boolean
Example: include_children=true

Only applies when the scheduled activities are being listed for a node - via a node path or parent_path. Include the scheduled activities of the node's descendants as well as its own.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e72c-a55c-7176-b12f-9e1c0f99287d",
      • "type": "scheduled_change",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e72c-a935-79b4-8167-9bdffb03f98f",
      • "type": "scheduled_workflow",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      }
    ],
  • "included": [
    • {
      • "id": "01a1e72c-a472-7809-b090-cd2bab81e5fc",
      • "type": "project",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": {
        }
      },
    • {
      • "id": "01a1e72c-a4d1-7eb7-a92a-3ccb87fcbb3e",
      • "type": "environment",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true,
      • "delete": true
      },
    • "has_any": true
    }
}

Create activities

Creates a scheduled activity in a specific project, environment or asset.

Notes:

  1. When creating scheduled activities via a project, environment or asset scheduled_activities path (e.g. POST to /api/projects/{project_code}/scheduled_activities) the parent_path request attributes must not be supplied as the parent will be derived from the path.

  2. When creating scheduled activities for assets (e.g. POST to /api/projects/{project_code}/assets/{asset_code}/scheduled_activities) the git_remote_name and git_rev attributes must not be supplied as the Git remote and revision will be derived from the asset's template.

  3. See the various payload examples to understand the required fields for each possible request to this endpoint.

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
Example
{
  • "data": {
    • "attributes": {
      • "git_rev": "master",
      • "action": "install_os",
      • "cron_schedule": "31 19 14 10 *",
      • "new_commits_only": false,
      • "repeat": true,
      • "metadata": {
        },
      • "run_at": null,
      • "run_count": 0,
      • "maximum_run_count": null,
      • "end_at": null,
      • "allow_parallel_execution": false,
      • "property_overrides": {
        },
      • "settings_overrides": {
        },
      • "notify": {
        },
      • "skip_steps": [ ],
      • "auto_continue_wait_steps": false,
      • "commit_file_patterns": [ ],
      • "commit_file_pattern_match": "any",
      • "enabled": true,
      • "labels": [ ],
      • "parent_path": "/projects/opc/environments/dev",
      • "git_remote_name": "github"
      }
    }
}

Response samples

Content type
application/vnd.api+json
Example
{
  • "data": {
    • "id": "01a1e72a-fd2a-71bd-a8ab-5baf985e5539",
    • "type": "scheduled_change",
    • "attributes": {
      • "created_by": "chae.connelly-22",
      • "created_by_disabled": false,
      • "created_by_name": "chae.connelly-22",
      • "cron_schedule": "26 1 19 12 4",
      • "repeat": true,
      • "run_count": 0,
      • "maximum_run_count": null,
      • "allow_parallel_execution": false,
      • "metadata": {
        },
      • "property_overrides": {
        },
      • "notify": {
        },
      • "skip_steps": [ ],
      • "labels": [
        ],
      • "created_at": "2026-11-17T01:41:56.647797Z",
      • "updated_at": "2026-11-17T01:41:56.647797Z",
      • "next_run_at": "2026-12-02T14:26:00.000000Z",
      • "run_at": null,
      • "end_at": null,
      • "action": "navigate",
      • "new_commits_only": true,
      • "git_rev": "optical",
      • "auto_continue_wait_steps": false,
      • "commit_file_patterns": [
        ],
      • "commit_file_pattern_match": "any",
      • "enabled": true,
      • "project_name": "OpsChain",
      • "project_code": "opc",
      • "settings_overrides": {
        },
      • "asset_code": null,
      • "asset_name": null,
      • "environment_code": "dev",
      • "environment_name": "Development",
      • "git_remote_name": "github"
      },
    • "relationships": {
      • "parents": {
        }
      },
    • "links": {
      • "git_remote": "/api/projects/opc/git_remotes/01a1e72a-f0cc-7a86-9dad-3fda525db936",
      • "project": "/api/projects/opc",
      • "parent": "/api/projects/opc/environments/dev",
      • "self": "/api/scheduled_activities/01a1e72a-fd2a-71bd-a8ab-5baf985e5539"
      }
    }
}

Show activity

Shows a scheduled activity.

path Parameters
scheduled_change_id
required
string
Example: 01a1e72a-fd2a-71bd-a8ab-5baf985e5539

scheduled change id

query Parameters
include
string
Example: include=parents

Include the scheduled change parents in the response

fields[<resource_type>]
string
Example: fields[<resource_type>]=code,status

Responses

Response samples

Content type
application/vnd.api+json
Example
{
  • "data": {
    • "id": "01a1e72a-fd2a-71bd-a8ab-5baf985e5539",
    • "type": "scheduled_change",
    • "attributes": {
      • "created_by": "chae.connelly-22",
      • "created_by_disabled": false,
      • "created_by_name": "chae.connelly-22",
      • "cron_schedule": "26 1 19 12 4",
      • "repeat": true,
      • "run_count": 0,
      • "maximum_run_count": null,
      • "allow_parallel_execution": false,
      • "metadata": {
        },
      • "property_overrides": {
        },
      • "notify": {
        },
      • "skip_steps": [ ],
      • "labels": [
        ],
      • "created_at": "2026-11-17T01:41:56.647797Z",
      • "updated_at": "2026-11-17T01:41:56.647797Z",
      • "next_run_at": "2026-12-02T14:26:00.000000Z",
      • "run_at": null,
      • "end_at": null,
      • "action": "navigate",
      • "new_commits_only": true,
      • "git_rev": "optical",
      • "auto_continue_wait_steps": false,
      • "commit_file_patterns": [
        ],
      • "commit_file_pattern_match": "any",
      • "enabled": true,
      • "project_name": "OpsChain",
      • "project_code": "opc",
      • "settings_overrides": {
        },
      • "asset_code": null,
      • "asset_name": null,
      • "environment_code": "dev",
      • "environment_name": "Development",
      • "git_remote_name": "github"
      },
    • "relationships": {
      • "parents": {
        }
      },
    • "links": {
      • "git_remote": "/api/projects/opc/git_remotes/01a1e72a-f0cc-7a86-9dad-3fda525db936",
      • "project": "/api/projects/opc",
      • "parent": "/api/projects/opc/environments/dev",
      • "self": "/api/scheduled_activities/01a1e72a-fd2a-71bd-a8ab-5baf985e5539"
      }
    }
}

Update activity

Updates a scheduled activity in a specific project, environment or asset.

Notes:

  1. The project, environment or asset the activity runs against cannot be changed. The parent_path, project_code, environment_code and asset_code attributes must not be supplied - create a new scheduled activity against the required parent instead.
  2. When updating activities for assets (e.g. PATCH to /api/projects/{project_code}/assets/{asset_code}/scheduled_activities/{id}) the git_remote_name and git_rev attributes must not be supplied as the Git remote and revision will be derived from the asset's template.
  3. See the various payload examples to understand the attributes you can supply to this endpoint.
  4. The payload need only consist of the attributes you wish to modify. There is no need to supply the entire scheduled activity.
path Parameters
scheduled_change_id
required
string
Example: 01a1e72a-fd2a-71bd-a8ab-5baf985e5539

scheduled change id

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
Example
{
  • "data": {
    • "attributes": {
      • "git_rev": "master",
      • "action": "install_os",
      • "cron_schedule": "14 18 19 2 5",
      • "new_commits_only": false,
      • "repeat": true,
      • "metadata": {
        },
      • "run_at": null,
      • "run_count": 0,
      • "maximum_run_count": null,
      • "end_at": null,
      • "allow_parallel_execution": false,
      • "property_overrides": {
        },
      • "settings_overrides": {
        },
      • "notify": {
        },
      • "skip_steps": [ ],
      • "auto_continue_wait_steps": false,
      • "commit_file_patterns": [ ],
      • "commit_file_pattern_match": "any",
      • "enabled": true,
      • "labels": [ ],
      • "git_remote_name": "github"
      }
    }
}

Response samples

Content type
application/vnd.api+json
Example
{
  • "data": {
    • "id": "01a1e72a-fd2a-71bd-a8ab-5baf985e5539",
    • "type": "scheduled_change",
    • "attributes": {
      • "created_by": "chae.connelly-22",
      • "created_by_disabled": false,
      • "created_by_name": "chae.connelly-22",
      • "cron_schedule": "26 1 19 12 4",
      • "repeat": true,
      • "run_count": 0,
      • "maximum_run_count": null,
      • "allow_parallel_execution": false,
      • "metadata": {
        },
      • "property_overrides": {
        },
      • "notify": {
        },
      • "skip_steps": [ ],
      • "labels": [
        ],
      • "created_at": "2026-11-17T01:41:56.647797Z",
      • "updated_at": "2026-11-17T01:41:56.647797Z",
      • "next_run_at": "2026-12-02T14:26:00.000000Z",
      • "run_at": null,
      • "end_at": null,
      • "action": "navigate",
      • "new_commits_only": true,
      • "git_rev": "optical",
      • "auto_continue_wait_steps": false,
      • "commit_file_patterns": [
        ],
      • "commit_file_pattern_match": "any",
      • "enabled": true,
      • "project_name": "OpsChain",
      • "project_code": "opc",
      • "settings_overrides": {
        },
      • "asset_code": null,
      • "asset_name": null,
      • "environment_code": "dev",
      • "environment_name": "Development",
      • "git_remote_name": "github"
      },
    • "relationships": {
      • "parents": {
        }
      },
    • "links": {
      • "git_remote": "/api/projects/opc/git_remotes/01a1e72a-f0cc-7a86-9dad-3fda525db936",
      • "project": "/api/projects/opc",
      • "parent": "/api/projects/opc/environments/dev",
      • "self": "/api/scheduled_activities/01a1e72a-fd2a-71bd-a8ab-5baf985e5539"
      }
    }
}

Delete activity

Delete a scheduled activity.

path Parameters
scheduled_change_id
required
string
Example: 01a1e72a-fd2a-71bd-a8ab-5baf985e5539

scheduled change id

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    • {
      • "status": 403,
      • "title": "You do not have permission to delete the scheduled change",
      • "detail": "Your authorisation rules let you view the scheduled change but not delete it."
      }
    ]
}

Steps

Endpoints to interact with change steps.

List steps

Lists all steps.

query Parameters
filter[<query/sort filter>]=
string
Example: filter[<query/sort filter>]==> filter[action_eq]=provision

API filtering guide. Named filters: filter[active_over], filter[finished], filter[waiting_for_user], filter[waiting_to_run], filter[with_input_arguments], filter[without_input_arguments]. Use filter[skip_reason_eq]=not_taken (or requested) to return only the steps skipped for that reason.

limit
integer [ 1 .. 1000 ]
Default: 1000
Example: limit=50

Limit the number of steps returned

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e731-4e30-7db8-870f-4eaa4265ebd8",
      • "type": "step",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": { }
      }
    ],
  • "meta": {
    • "partial_response": false
    }
}

Show step

Shows a change step.

path Parameters
step_id
required
string
Example: 01a1e72a-f98c-73b4-93d3-76233e836c5c

step id

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e731-4fe5-70c2-8333-6aa736d0cc0c",
    • "type": "step",
    • "attributes": {
      • "approved_by": [ ],
      • "rejected_by": [ ],
      • "continued_by": [ ],
      • "requires_approval_from": null,
      • "skip_reason": null,
      • "selected_arm": null,
      • "arm_reason": null,
      • "arm": null,
      • "choices": null,
      • "default": null,
      • "branch": null,
      • "retry_from": null,
      • "recover": null,
      • "reset_on_retry": null,
      • "run_if": null,
      • "abort_on_reject": null,
      • "abort_on_cancel": null,
      • "action": "override",
      • "change_id": "01a1e731-4fe0-7bca-843c-ffcc8478f2ad",
      • "child_execution_strategy": "sequential",
      • "full_path": "override",
      • "ignore_failure": false,
      • "input_arguments": [ ],
      • "state_timing": {
        },
      • "step_sequence": 1,
      • "step_type": "standard",
      • "description": "Deploy the release to the environment",
      • "timeout": null,
      • "step_name": "override",
      • "cancel_requested": false,
      • "skip_requested": false,
      • "created_at": "2026-11-17T01:41:23.843556Z",
      • "started_at": "2026-11-17T01:42:23.843556Z",
      • "finished_at": "2026-11-17T01:45:50.083658Z",
      • "updated_at": "2026-11-17T01:48:51.113390Z",
      • "status_code": "success"
      },
    • "relationships": {
      • "properties": {
        },
      • "children": {
        },
      • "pre_properties_versions": {
        },
      • "post_properties_versions": {
        },
      • "change": {
        }
      },
    • "links": {
      • "parent": "/api/changes/01a1e731-4fe0-7bca-843c-ffcc8478f2ad",
      • "change": "/api/projects/opc/environments/dev/changes/01a1e731-4fe0-7bca-843c-ffcc8478f2ad",
      • "log_lines": "/api/steps/01a1e731-4fe5-70c2-8333-6aa736d0cc0c/log_lines",
      • "self": "/api/steps/01a1e731-4fe5-70c2-8333-6aa736d0cc0c"
      },
    • "meta": {
      • "property_sources": {
        }
      }
    },
  • "included": [
    • {
      • "id": "01a1e731-4f6e-7867-b4b9-6e2f0d4ba939",
      • "type": "properties_version",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": { }
      },
    • {
      • "id": "01a1e731-4faa-7371-bd3f-6eddb38c4c82",
      • "type": "properties_version",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": { }
      },
    • {
      • "id": "01a1e731-4ff4-779d-9690-80f81c604154",
      • "type": "properties_version",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": { }
      },
    • {
      • "id": "01a1e731-5020-7661-bb79-bed6573b1b4d",
      • "type": "properties",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      }
    ]
}

Continue step

Continues a "waiting" change step.

path Parameters
step_id
required
string
Example: 01a1e72b-17e5-7538-8a73-339322229a24

step id

Request Body schema: application/vnd.api+json
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "message": "Manually removed from load balancer.",
      • "input_arguments": {
        },
      • "choice": "promote"
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e731-539e-7cfa-92c1-553e99caf7d6",
    • "type": "step",
    • "attributes": {
      • "approved_by": [ ],
      • "rejected_by": [ ],
      • "continued_by": [ ],
      • "requires_approval_from": null,
      • "skip_reason": null,
      • "selected_arm": null,
      • "arm_reason": null,
      • "arm": null,
      • "choices": null,
      • "default": null,
      • "branch": null,
      • "retry_from": null,
      • "recover": null,
      • "reset_on_retry": null,
      • "run_if": null,
      • "abort_on_reject": null,
      • "abort_on_cancel": null,
      • "action": "opschain_wait_step_2",
      • "change_id": "01a1e731-539a-73c2-98f6-564ea50d17fb",
      • "child_execution_strategy": "sequential",
      • "full_path": "opschain_wait_step_2",
      • "ignore_failure": false,
      • "input_arguments": [ ],
      • "state_timing": {
        },
      • "step_sequence": 1,
      • "step_type": "wait_step",
      • "description": "Deploy the release to the environment",
      • "timeout": null,
      • "step_name": "opschain_wait_step_2",
      • "cancel_requested": false,
      • "skip_requested": false,
      • "created_at": "2026-11-17T01:40:57.092687Z",
      • "started_at": "2026-11-17T01:41:57.092687Z",
      • "finished_at": "2026-11-17T01:48:52.405781Z",
      • "updated_at": "2026-11-17T01:48:52.612769Z",
      • "status_code": "success"
      },
    • "relationships": {
      • "properties": {
        },
      • "children": {
        },
      • "pre_properties_versions": {
        },
      • "post_properties_versions": {
        },
      • "change": {
        }
      },
    • "links": {
      • "parent": "/api/changes/01a1e731-539a-73c2-98f6-564ea50d17fb",
      • "change": "/api/projects/opc/environments/dev/changes/01a1e731-539a-73c2-98f6-564ea50d17fb",
      • "log_lines": "/api/steps/01a1e731-539e-7cfa-92c1-553e99caf7d6/log_lines",
      • "self": "/api/steps/01a1e731-539e-7cfa-92c1-553e99caf7d6"
      },
    • "meta": { }
    }
}

Retry step

Re-runs a failed change step, and the steps below it that failed or did not run, on the existing step records while the rest of the change keeps running. Only a step that failed directly below a step that is still running can be retried, and only while the change is active and not paused. The step's retry link is present when it can be retried. Steps below it that succeeded are not re-run. The retry is logged at the start of the step's log, after the output of the failed attempt.

path Parameters
step_id
required
string
Example: 01a1e72a-f98c-73b4-93d3-76233e836c5c

step id

Request Body schema: application/vnd.api+json
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "message": "Network share restored."
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e731-62f9-7af6-bcb7-ff9875cae428",
    • "type": "step",
    • "attributes": {
      • "skip_reason": null,
      • "selected_arm": null,
      • "arm_reason": null,
      • "arm": null,
      • "choices": null,
      • "default": null,
      • "branch": null,
      • "retry_from": null,
      • "recover": null,
      • "reset_on_retry": null,
      • "run_if": null,
      • "abort_on_reject": null,
      • "abort_on_cancel": null,
      • "action": "deploy_server",
      • "change_id": "01a1e731-62a9-7ce1-a0eb-5376e005e451",
      • "child_execution_strategy": "sequential",
      • "full_path": "hack/deploy_server",
      • "ignore_failure": false,
      • "input_arguments": [ ],
      • "state_timing": {
        },
      • "step_sequence": 1,
      • "step_type": "standard",
      • "description": null,
      • "timeout": null,
      • "step_name": "deploy_server",
      • "cancel_requested": false,
      • "skip_requested": false,
      • "created_at": "2026-11-17T01:39:52.207085Z",
      • "started_at": "2026-11-17T01:40:52.207000Z",
      • "finished_at": null,
      • "updated_at": "2026-11-17T01:48:56.094415Z",
      • "status_code": "queued"
      },
    • "relationships": {
      • "properties": {
        },
      • "children": {
        },
      • "pre_properties_versions": {
        },
      • "post_properties_versions": {
        },
      • "change": {
        }
      },
    • "links": {
      • "parent": "/api/steps/01a1e731-62ae-73dc-aebd-3b4e9ea02cb0",
      • "change": "/api/projects/opc/environments/dev/changes/01a1e731-62a9-7ce1-a0eb-5376e005e451",
      • "log_lines": "/api/steps/01a1e731-62f9-7af6-bcb7-ff9875cae428/log_lines",
      • "self": "/api/steps/01a1e731-62f9-7af6-bcb7-ff9875cae428"
      },
    • "meta": {
      • "previous_run": {
        }
      }
    }
}

Approve step

Approves a change step that needs approval.

path Parameters
step_id
required
string
Example: 01a1e72b-17e5-7538-8a73-339322229a24

step id

Request Body schema: application/vnd.api+json
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "message": "As per CR 7 👍",
      • "choice": "promote"
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e731-7042-7a03-b3ca-d7dd9dc83752",
    • "type": "step",
    • "attributes": {
      • "approved_by": [ ],
      • "rejected_by": [ ],
      • "continued_by": [ ],
      • "requires_approval_from": [
        ],
      • "skip_reason": null,
      • "selected_arm": null,
      • "arm_reason": null,
      • "arm": null,
      • "choices": null,
      • "default": null,
      • "branch": null,
      • "retry_from": null,
      • "recover": null,
      • "reset_on_retry": null,
      • "run_if": null,
      • "abort_on_reject": null,
      • "abort_on_cancel": null,
      • "action": "opschain_wait_step_6",
      • "change_id": "01a1e731-703c-73d7-b64d-b82404f1f318",
      • "child_execution_strategy": "sequential",
      • "full_path": "opschain_wait_step_6",
      • "ignore_failure": false,
      • "input_arguments": [ ],
      • "state_timing": {
        },
      • "step_sequence": 1,
      • "step_type": "wait_step",
      • "description": "Deploy the release to the environment",
      • "timeout": null,
      • "step_name": "opschain_wait_step_6",
      • "cancel_requested": false,
      • "skip_requested": false,
      • "created_at": "2026-11-17T01:38:36.666587Z",
      • "started_at": "2026-11-17T01:39:36.666587Z",
      • "finished_at": null,
      • "updated_at": "2026-11-17T01:48:59.575689Z",
      • "status_code": "queued"
      },
    • "relationships": {
      • "properties": {
        },
      • "children": {
        },
      • "pre_properties_versions": {
        },
      • "post_properties_versions": {
        },
      • "change": {
        }
      },
    • "links": {
      • "parent": "/api/changes/01a1e731-703c-73d7-b64d-b82404f1f318",
      • "change": "/api/projects/opc/environments/dev/changes/01a1e731-703c-73d7-b64d-b82404f1f318",
      • "log_lines": "/api/steps/01a1e731-7042-7a03-b3ca-d7dd9dc83752/log_lines",
      • "self": "/api/steps/01a1e731-7042-7a03-b3ca-d7dd9dc83752"
      },
    • "meta": { }
    }
}

Reject step

Rejects a change step that needs approval.

path Parameters
step_id
required
string
Example: 01a1e72b-17e5-7538-8a73-339322229a24

step id

Request Body schema: application/vnd.api+json
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "message": "Failed user acceptance testing"
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e731-7f08-7de6-9847-832262216e35",
    • "type": "step",
    • "attributes": {
      • "approved_by": [ ],
      • "rejected_by": [ ],
      • "continued_by": [ ],
      • "requires_approval_from": [
        ],
      • "skip_reason": null,
      • "selected_arm": null,
      • "arm_reason": null,
      • "arm": null,
      • "choices": null,
      • "default": null,
      • "branch": null,
      • "retry_from": null,
      • "recover": null,
      • "reset_on_retry": null,
      • "run_if": null,
      • "abort_on_reject": null,
      • "abort_on_cancel": null,
      • "action": "opschain_wait_step_10",
      • "change_id": "01a1e731-7f04-7797-b76e-700b1ebb3bd6",
      • "child_execution_strategy": "sequential",
      • "full_path": "opschain_wait_step_10",
      • "ignore_failure": false,
      • "input_arguments": [ ],
      • "state_timing": {
        },
      • "step_sequence": 1,
      • "step_type": "wait_step",
      • "description": "Deploy the release to the environment",
      • "timeout": null,
      • "step_name": "opschain_wait_step_10",
      • "cancel_requested": false,
      • "skip_requested": false,
      • "created_at": "2026-11-17T01:42:18.825621Z",
      • "started_at": "2026-11-17T01:43:18.825621Z",
      • "finished_at": "2026-11-17T01:49:03.237876Z",
      • "updated_at": "2026-11-17T01:49:03.256557Z",
      • "status_code": "aborted"
      },
    • "relationships": {
      • "properties": {
        },
      • "children": {
        },
      • "pre_properties_versions": {
        },
      • "post_properties_versions": {
        },
      • "change": {
        }
      },
    • "links": {
      • "parent": "/api/changes/01a1e731-7f04-7797-b76e-700b1ebb3bd6",
      • "change": "/api/projects/opc/environments/dev/changes/01a1e731-7f04-7797-b76e-700b1ebb3bd6",
      • "log_lines": "/api/steps/01a1e731-7f08-7de6-9847-832262216e35/log_lines",
      • "self": "/api/steps/01a1e731-7f08-7de6-9847-832262216e35"
      },
    • "meta": { }
    }
}

Show step settings

Show the converged settings for the change containing this step, including any change-specific setting overrides. Unless include_global=true is passed, only the values that differ from the global settings are returned: a setting whose converged value matches the global value is omitted, even when it is set directly on a node, so the response is empty when nothing differs from the global settings.

The response includes a setting_sources meta object that attributes each setting value to its originating source.

path Parameters
step_id
required
string
Example: 01a1e72a-f98c-73b4-93d3-76233e836c5c

step id

query Parameters
include_global
boolean
Example: include_global=true

Also return the settings whose converged value matches the global settings

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e731-88da-7985-a555-93274874a196",
    • "type": "converged_settings",
    • "attributes": {
      • "data": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/environments/dev/converged_settings"
      },
    • "meta": {
      • "setting_sources": {
        }
      }
    }
}

Show step properties

Converge the properties for a step.

The optional action_stage argument can be:

  • "pre" - to converge the properties as they were supplied to the step action before it executed
  • "post" - to converge the properties as they were after the step action was complete (does not take into account any changes made by the step's children)
path Parameters
step_id
required
string
Example: 01a1e72a-f98c-73b4-93d3-76233e836c5c

step id

query Parameters
action_stage
string
Example: action_stage=pre

Converge the pre or post action properties

exclude_layers[]
string
Example: exclude_layers[]=template

Exclude a property layer from the converged result. Repeat the parameter to exclude several layers, e.g. > exclude_layers[]=template&exclude_layers[]=asset. Suffix a layer with _repository or _database to exclude only that half of it, e.g. > exclude_layers[]=asset_repository. The layers available for the node, and whether each one is currently included, are listed in the property_layers response meta. The template layer covers the properties files held under the <template code> folder of the template repository, as well as the template's database properties; the template_version layer covers the template version database properties only. Excluding a layer is a preview - the result is not cached and nothing is persisted.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "generate (post)",
    • "type": "converged_properties",
    • "attributes": {
      • "data": {
        }
      },
    • "relationships": {
      • "repository_properties": {
        },
      • "properties": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/environments/dev/converged_properties"
      },
    • "meta": {
      • "property_sources": {
        },
      • "property_layers": [
        ]
      }
    },
  • "included": [
    • {
      • "id": "01a1e731-8c5a-7511-bda9-229a25dc9547",
      • "type": "properties_version",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": { }
      },
    • {
      • "id": "01a1e731-8ca7-7ea2-a10f-a5f09ce9212c",
      • "type": "properties_version",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": { }
      },
    • {
      • "id": "01a1e731-8d04-71a3-836e-533492056d5c",
      • "type": "properties_version",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": { }
      }
    ]
}

Log lines

Endpoints to query log lines for changes and individual change steps.

List change log lines

List the log lines for a change.

path Parameters
change_id
required
string
Example: 01a1e72a-f8ec-78fe-b4ca-5e5595b30df0
query Parameters
filter[<query/sort filter>]=
string
Example: filter[<query/sort filter>]==> filter[message_cont]=dolorem
download
string
Example: download=change.log

Download the log lines wth the specified file name. The logs will be ordered from oldest to newest when this parameter is specified, irrespective of the sort order requested.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e731-46a1-77a1-bf51-2b8eac322602",
      • "type": "log_line",
      • "attributes": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true
      },
    • "partial_response": false
    }
}

List step log lines

List the log lines for a change step.

path Parameters
step_id
required
string
Example: 01a1e72a-f98c-73b4-93d3-76233e836c5c
query Parameters
include_child_steps
boolean
Example: include_child_steps=true

Whether to include logs for steps that are children of this step

filter[<query/sort filter>]=
string
Example: filter[<query/sort filter>]==> filter[message_cont]=dolorem
download
string
Example: download=step.log

Download the log lines wth the specified file name. The logs will be ordered from oldest to newest when this parameter is specified, irrespective of the sort order requested.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e731-49ab-7abf-a120-e09c07d1d527",
      • "type": "log_line",
      • "attributes": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true
      },
    • "partial_response": false
    }
}

List filtered log lines

List filtered log lines.

query Parameters
filter[<query/sort filter>]=
string
Example: filter[<query/sort filter>]==> filter[message_cont]=dolorem
limit
integer [ 1 .. 10000 ]
Default: 10000
Example: limit=50

Limit the number of log lines returned

download
string
Example: download=opschain.log

Download the filtered log lines wth the specified file name. The logs will be ordered from oldest to newest when this parameter is specified, irrespective of the sort order requested.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e731-4cff-79e8-b64b-b9f32393ec69",
      • "type": "log_line",
      • "attributes": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true
      },
    • "partial_response": false
    }
}

List workflow run log lines

List the workflow run log lines for a workflow run.

path Parameters
workflow_run_id
required
string
Example: 01a1e72b-1a64-7c6b-b8c4-3371ce2c0837
query Parameters
filter[<query/sort filter>]=
string
Example: filter[<query/sort filter>]==> filter[message_cont]=dolorem
download
string
Example: download=workflow_run.log

Download the log lines wth the specified file name. The logs will be ordered from oldest to newest when this parameter is specified, irrespective of the sort order requested.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e732-bec0-7f70-90ff-b110008661be",
      • "type": "log_line",
      • "attributes": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true
      },
    • "partial_response": false
    }
}

List workflow step log lines

List the log lines for a workflow step.

path Parameters
workflow_step_id
required
string
Example: 01a1e72b-1a7b-7e67-9b4d-e3e7057f14f7
query Parameters
include_child_steps
boolean
Example: include_child_steps=true

Whether to include logs for steps that are children of this step

filter[<query/sort filter>]=
string
Example: filter[<query/sort filter>]==> filter[message_cont]=dolorem
download
string
Example: download=workflow_step.log

Download the log lines wth the specified file name. The logs will be ordered from oldest to newest when this parameter is specified, irrespective of the sort order requested.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e732-e096-793f-9b7e-a23ee55f0255",
      • "type": "log_line",
      • "attributes": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true
      },
    • "partial_response": false
    }
}

List filtered workflow run log lines

List filtered workflow run log lines for a workflow run or workflow step.

query Parameters
workflow_run_id
string
Example: workflow_run_id=01a1e72b-1a64-7c6b-b8c4-3371ce2c0837

The workflow run to list log lines for. Required unless workflow_step_id is supplied.

workflow_step_id
string
Example: workflow_step_id=01a1e72b-1a7b-7e67-9b4d-e3e7057f14f7

The workflow step to list log lines for. Required unless workflow_run_id is supplied.

filter[<query/sort filter>]=
string
Example: filter[<query/sort filter>]==> filter[message_cont]=dolorem
limit
integer [ 1 .. 10000 ]
Default: 10000
Example: limit=50

Limit the number of workflow run log lines returned

download
string
Example: download=opschain.log

Download the filtered log lines wth the specified file name. The logs will be ordered from oldest to newest when this parameter is specified, irrespective of the sort order requested.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e732-fa91-7430-ad04-0a1ab7ce5c6b",
      • "type": "log_line",
      • "attributes": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true
      },
    • "partial_response": false
    }
}

Artifacts

Endpoints to store, list and retrieve artifacts. Every artifacts and artifact_loads path also answers on its artefacts and artefact_loads spelling, and responses always use artifacts.

List artifact loads

Lists the artifact versions loaded by a specific change (across all of its steps), newest first by default. Every load is recorded, so a version loaded more than once appears once per load. Use include=artifact to include the loaded artifact versions (include=artefact is also accepted).

path Parameters
change_id
required
string
Example: 01a1e72a-f8ec-78fe-b4ca-5e5595b30df0

change id

query Parameters
include
string
Example: include=artifact

Comma-separated relationships to include: artifact (or artefact), step.

limit
integer >= 1
Example: limit=50

Limit the number of loads returned. When more records match than the limit a 206 response is returned and meta.partial_response is true. Fetch the next page by adding a filter[created_at_lt] cursor.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e72b-9979-7406-83de-e902d2c93f6f",
      • "type": "artifact_load",
      • "attributes": {
        },
      • "relationships": {
        }
      }
    ],
  • "included": [
    • {
      • "id": "01a1e72b-9896-7154-a9aa-49723a671a50",
      • "type": "artifact",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true
      },
    • "partial_response": false
    }
}

List artifact loads

Lists the artifact versions loaded by a specific step, newest first by default. Every load is recorded, so a version loaded more than once appears once per load. Use include=artifact to include the loaded artifact versions (include=artefact is also accepted).

path Parameters
step_id
required
string
Example: 01a1e72a-f98c-73b4-93d3-76233e836c5c

step id

query Parameters
include
string
Example: include=artifact

Comma-separated relationships to include: artifact (or artefact), step.

limit
integer >= 1
Example: limit=50

Limit the number of loads returned. When more records match than the limit a 206 response is returned and meta.partial_response is true. Fetch the next page by adding a filter[created_at_lt] cursor.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e72b-9f6b-7adf-8f28-996dcdb0eec0",
      • "type": "artifact_load",
      • "attributes": {
        },
      • "relationships": {
        }
      }
    ],
  • "included": [
    • {
      • "id": "01a1e72b-9ebf-7345-a7c6-ee67d69227d3",
      • "type": "artifact",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true
      },
    • "partial_response": false
    }
}

List all artifacts

Lists the artifacts of every project, environment and asset the user can read, newest first by default. An artifact is only listed when the user can read both its project, environment or asset and that node's artifacts. meta.has_any reports whether the user can read any artifact at all, regardless of the filter. meta.total_matching_filter counts the artifacts matching the filter, stopping at 1000 (or one past the returned page, when the limit is larger) - meta.total_matching_filter_exact reports whether the count is exact.

query Parameters
filter[<query/sort filter>]=
string
Example: filter[<query/sort filter>]==> filter[parent_path_eq]=/projects/web

API filtering guide. Named filters: filter[created_by_eq], filter[created_by_in], filter[latest_per_code], filter[with_label]. Filter by location with filter[parent_path_eq]=<node path>, and include the nodes beneath it with filter[g][0][m]=or&filter[g][0][parent_path_eq]=<node path>&filter[g][0][parent_path_start]=<node path>/. Filter by code_eq, description_cont, created_by_eq, node_id_eq, step_change_id_eq, by label with filter[with_label]=<label>, by purge state with filter[purged_at_null]=true|false, and by file details with filename_cont, content_type_eq and byte_size_gt/byte_size_lt. Search by part of a label with filter[labels_text_cont]=<text>, or across the code, description, filename, labels, creator and location with filter[free_text_cont]=<text>. Use filter[latest_per_code]=true to list one row per node and code. Sort with filter[sorts]=<attribute> asc|desc, where the attribute is created_at, code, filename, content_type or byte_size.

limit
integer [ 1 .. 1000 ]
Example: limit=50

Limit the number of artifacts returned (default 100, maximum 1000). When more records match than the limit a 206 response is returned and meta.partial_response is true. Fetch the next page by adding a filter[created_at_lt] (or created_at_gt when sorting ascending) cursor.

include
string
Example: include=node

Include the project, environment or asset each artifact belongs to with include=node.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e72b-a4d8-7972-b2eb-e1b3262df080",
      • "type": "artifact",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      }
    ],
  • "included": [
    • {
      • "id": "01a1e72b-a47a-7d7e-8e32-b7ac7521b0b5",
      • "type": "asset",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true
      },
    • "partial_response": false,
    • "has_any": true,
    • "total_matching_filter": 1,
    • "total_matching_filter_exact": true
    }
}

Create artifact

Manually uploads an artifact for a specific project, environment or asset - for example, publishing a hand-built hotfix outside of a change.

Request Body schema: multipart/form-data
data
string

JSON-encoded object with code, node_id and optional labels (at most 20, each at most 100 characters and containing no commas) and description (maximum 1000 characters) attributes

file
string <binary>

the artifact file content

Responses

Request samples

Content type
multipart/form-data
------------XnJLe9ZIbbGUYtzPQJ16u1
content-disposition: form-data; name="data"

{"code":"hotfix","node_id":"01a1e72b-aa8a-7d7f-a762-13249ae392da","labels":["hotfix-2026-09-22"],"description":"Hand-built hotfix for the September release"}
------------XnJLe9ZIbbGUYtzPQJ16u1
content-disposition: form-data; name="file"; filename="sample.txt"
content-type: text/plain
content-length: 21

Sample file property

------------XnJLe9ZIbbGUYtzPQJ16u1--

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72b-abff-7902-b43b-123015d7c7d1",
    • "type": "artifact",
    • "attributes": {
      • "code": "hotfix",
      • "description": "Hand-built hotfix for the September release",
      • "labels": [
        ],
      • "created_by": "logged_in_user",
      • "created_by_name": "logged_in_user",
      • "created_at": "2026-11-17T01:42:41.406553Z",
      • "purged_at": null,
      • "byte_size": 21,
      • "content_type": "text/plain",
      • "filename": "sample.txt"
      },
    • "relationships": {
      • "node": {
        }
      },
    • "links": {
      • "self": "/api/artifacts/01a1e72b-abff-7902-b43b-123015d7c7d1"
      }
    }
}

Create artifact upload target

Creates an artifact record and returns a signed direct upload target for its content. PUT the file content to meta.upload_url, sending the meta.upload_headers, to complete the upload.

Request Body schema: application/x-www-form-urlencoded
data
string

JSON-encoded object with code, node_id, filename, byte_size, checksum and content_type attributes, and optional labels (at most 20, each at most 100 characters and containing no commas), description (maximum 1000 characters) and step_id attributes

Responses

Request samples

Content type
application/x-www-form-urlencoded
data=%7B%22code%22%3A%22hotfix%22%2C%22node_id%22%3A%2201a1e72b-adc7-77cd-b547-37bf03ef840d%22%2C%22labels%22%3A%5B%22hotfix-2026-09-22%22%5D%2C%22description%22%3A%22Hand-built+hotfix+for+the+September+release%22%2C%22filename%22%3A%22sample.txt%22%2C%22byte_size%22%3A21%2C%22checksum%22%3A%229V61v4%2FdxeJDNTy0baxWzQ%3D%3D%22%2C%22content_type%22%3A%22text%2Fplain%22%7D

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72b-aea1-7335-8866-c8fca3d3bd17",
    • "type": "artifact",
    • "attributes": {
      • "code": "hotfix",
      • "description": "Hand-built hotfix for the September release",
      • "labels": [
        ],
      • "created_by": "logged_in_user",
      • "created_by_name": "logged_in_user",
      • "created_at": "2026-11-17T01:42:42.080608Z",
      • "purged_at": null,
      • "byte_size": null,
      • "content_type": null,
      • "filename": null
      },
    • "relationships": {
      • "node": {
        }
      },
    • "links": {
      • "self": "/api/artifacts/01a1e72b-aea1-7335-8866-c8fca3d3bd17"
      }
    },
  • "meta": {
    • "signed_id": "eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBDdz09IiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--51438c092038e81de0c279216dd00b324c18699f",
    • "upload_url": "/api/artifact_direct_uploads/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaDdDam9JYTJWNVNTSWhObU5sWjNSdGFucG5kemh6YUdkellXRndiM052TVdSd1pHRTJkQVk2QmtWR09oRmpiMjUwWlc1MFgzUjVjR1ZKSWc5MFpYaDBMM0JzWVdsdUJqc0dWRG9OWTJobFkydHpkVzFKSWgwNVZqWXhkalF2WkhobFNrUk9WSGt3WW1GNFYzcFJQVDBHT3daVU9nNXlaV052Y21SZmFXUkpJaWt3TVdFeFpUY3lZaTFoWldFeExUY3pNelV0T0RnMk5pMWpPR1pqWVROa00ySmtNVGNHT3daVU9oRnpaWEoyYVdObFgyNWhiV1U2R25CdmMzUm5jbVZ6WDJ4aGNtZGxiMkpxWldOMGN3PT0iLCJleHAiOiIyMDI2LTExLTE3VDAxOjQ3OjQyLjA4N1oiLCJwdXIiOiJibG9iX3Rva2VuIn19--46284ea5264ea39773595ce346a98af99134c38b",
    • "upload_headers": {
      • "Content-Type": "text/plain"
      }
    }
}

Show artifact

Show an artifact.

path Parameters
artifact_id
required
string
Example: 01a1e72a-faae-7b91-8578-2409a095a84d

artifact id

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72b-b167-7710-9c07-d5ce653ad410",
    • "type": "artifact",
    • "attributes": {
      • "code": "war",
      • "description": "Alias et ut expedita.",
      • "labels": [
        ],
      • "created_by": "opschain",
      • "created_by_name": "opschain",
      • "created_at": "2026-11-17T01:42:42.790489Z",
      • "purged_at": null,
      • "byte_size": 24,
      • "content_type": "application/octet-stream",
      • "filename": "app.war"
      },
    • "relationships": {
      • "node": {
        }
      },
    • "links": {
      • "self": "/api/artifacts/01a1e72b-b167-7710-9c07-d5ce653ad410"
      }
    }
}

Download artifact

Streams the artifact file content.

path Parameters
artifact_id
required
string
Example: 01a1e72a-faae-7b91-8578-2409a095a84d

artifact id

Responses

Response samples

Content type
application/octet-stream
<binary data>

Get artifact download target

Returns a signed, time-limited URL to download the artifact file content from.

path Parameters
artifact_id
required
string
Example: 01a1e72a-faae-7b91-8578-2409a095a84d

artifact id

query Parameters
step_id
string

records an artifact load against this step. Only accepted when the request is authenticated with the API key of the change that owns the step

Responses

Response samples

Content type
application/vnd.api+json
{
  • "meta": {
    • "download_url": "/api/artifact_blobs/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaDdDVG9JYTJWNVNTSWhOMmRuT1hZMGFHb3hNMjFrYjNsME9ETTBPV3BpTVhOamFqbDFiZ1k2QmtWVU9oQmthWE53YjNOcGRHbHZia2tpUFdGMGRHRmphRzFsYm5RN0lHWnBiR1Z1WVcxbFBTSmhjSEF1ZDJGeUlqc2dabWxzWlc1aGJXVXFQVlZVUmkwNEp5ZGhjSEF1ZDJGeUJqc0dWRG9SWTI5dWRHVnVkRjkwZVhCbFNTSWRZWEJ3YkdsallYUnBiMjR2YjJOMFpYUXRjM1J5WldGdEJqc0dWRG9SYzJWeWRtbGpaVjl1WVcxbE9ocHdiM04wWjNKbGMxOXNZWEpuWlc5aWFtVmpkSE09IiwiZXhwIjoiMjAyNi0xMS0xN1QwMTo0Nzo0Ny44NzhaIiwicHVyIjoiYmxvYl9rZXkifX0=--96adfc87deac40ed24534670efbbfbb51a84531e/app.war",
    • "download_headers": { }
    }
}

Get latest matching artifact download target

Returns a signed, time-limited URL to download the newest complete artifact with the supplied code (and labels) from the supplied project, environment or asset.

query Parameters
node_id
string
Example: node_id=01a1e72a-f330-7343-a642-2c7505170dd4

id of the project, environment or asset the artifact belongs to

code
string
Example: code=war

artifact code

labels
string
Example: labels=v1.2.3

comma-separated labels the artifact must carry - when several are supplied, the artifact must carry all of them

step_id
string

records an artifact load against this step. Only accepted when the request is authenticated with the API key of the change that owns the step

Responses

Response samples

Content type
application/vnd.api+json
{
  • "meta": {
    • "download_url": "/api/artifact_blobs/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaDdDVG9JYTJWNVNTSWhabWRvYUdwa01tTjZjR2syZG14MGJ6RndhR3AxTkhCbk9YUnBjZ1k2QmtWVU9oQmthWE53YjNOcGRHbHZia2tpUFdGMGRHRmphRzFsYm5RN0lHWnBiR1Z1WVcxbFBTSmhjSEF1ZDJGeUlqc2dabWxzWlc1aGJXVXFQVlZVUmkwNEp5ZGhjSEF1ZDJGeUJqc0dWRG9SWTI5dWRHVnVkRjkwZVhCbFNTSWRZWEJ3YkdsallYUnBiMjR2YjJOMFpYUXRjM1J5WldGdEJqc0dWRG9SYzJWeWRtbGpaVjl1WVcxbE9ocHdiM04wWjNKbGMxOXNZWEpuWlc5aWFtVmpkSE09IiwiZXhwIjoiMjAyNi0xMS0xN1QwMTo0Nzo1MS4xMTZaIiwicHVyIjoiYmxvYl9rZXkifX0=--db4c78f0e0c65d1d90f265436cde7e44ab5ce5c4/app.war",
    • "download_headers": { }
    }
}

Download latest matching artifact

Streams the file content of the newest complete artifact with the supplied code (and labels) from the supplied project, environment or asset.

query Parameters
node_id
string
Example: node_id=01a1e72a-f330-7343-a642-2c7505170dd4

id of the project, environment or asset the artifact belongs to

code
string
Example: code=war

artifact code

labels
string
Example: labels=v1.2.3

comma-separated labels the artifact must carry - when several are supplied, the artifact must carry all of them

Responses

Response samples

Content type
application/octet-stream
<binary data>

Upload artifact content

Uploads the file content for an artifact created by POST /artifacts/upload_target. This is the meta.upload_url that endpoint returns - the signed id authorises the request, so no further authentication is required. The content must match the declared checksum.

path Parameters
signed_id
required
string

the signed id from the upload_url returned by POST /artifacts/upload_target

Request Body schema: application/octet-stream
string <binary>

Responses

Download artifact content

Streams the artifact file content. This is the meta.download_url returned by the download target endpoints - the signed id authorises the request, so no further authentication is required.

path Parameters
signed_id
required
string

the signed id from the download_url returned by a download target endpoint

filename
required
string
Example: app.war

the artifact filename

Responses

Response samples

Content type
application/octet-stream
<binary data>

List artifacts

Lists all artifacts for a specific project, environment or asset, newest first by default. Use filter[latest_per_code]=true to list one row per code (the newest complete version, falling back to the newest purged version), each carrying a versions_count attribute. meta.total_matching_filter counts the artifacts matching the filter, stopping at 1000 (or one past the returned page, when the limit is larger) - meta.total_matching_filter_exact reports whether the count is exact.

path Parameters
project_code
required
string
Example: opc

project code

asset_code
required
string
Example: prj_soa

asset code

query Parameters
filter[<query/sort filter>]=
string
Example: filter[<query/sort filter>]==> filter[code_eq]=war

API filtering guide. Named filters: filter[created_by_eq], filter[created_by_in], filter[latest_per_code], filter[with_label]. Filter by code_eq, by label with filter[with_label]=<label> (repeat it as filter[with_label][]=<label> to give several labels, all of which must match) (combined with filter[latest_per_code]=true the labels are applied before the per-code pick, so each code returns its newest version carrying them, while versions_count still counts every complete version of the code), by purge state with filter[purged_at_null]=true|false, by part of a label with filter[labels_text_cont]=<text>, across the code, description, filename, labels, creator and location with filter[free_text_cont]=<text>, and sort with filter[sorts]=created_at asc. Unlike with_label, every other filter, labels_text_cont and free_text_cont included, applies after the per-code pick, so it only matches the version that pick returns.

limit
integer >= 1
Example: limit=50

Limit the number of artifacts returned. When more records match than the limit a 206 response is returned and meta.partial_response is true. Fetch the next page by adding a filter[created_at_lt] (or created_at_gt when sorting ascending) cursor.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e72b-eaf2-7e3f-9dc2-e9dc945ed8f3",
      • "type": "artifact",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true
      },
    • "partial_response": false,
    • "total_matching_filter": 1,
    • "total_matching_filter_exact": true
    }
}

List artifacts

Lists all artifacts for a specific change (the artefacts produced by its steps), newest first by default. Use filter[latest_per_code]=true to list one row per code (the newest complete version, falling back to the newest purged version), each carrying a versions_count attribute. meta.total_matching_filter counts the artifacts matching the filter, stopping at 1000 (or one past the returned page, when the limit is larger) - meta.total_matching_filter_exact reports whether the count is exact.

path Parameters
change_id
required
string
Example: 01a1e72a-f8ec-78fe-b4ca-5e5595b30df0

change id

query Parameters
filter[<query/sort filter>]=
string
Example: filter[<query/sort filter>]==> filter[code_eq]=war

API filtering guide. Named filters: filter[created_by_eq], filter[created_by_in], filter[latest_per_code], filter[with_label]. Filter by code_eq, by label with filter[with_label]=<label> (repeat it as filter[with_label][]=<label> to give several labels, all of which must match) (combined with filter[latest_per_code]=true the labels are applied before the per-code pick, so each code returns its newest version carrying them, while versions_count still counts every complete version of the code), by purge state with filter[purged_at_null]=true|false, by part of a label with filter[labels_text_cont]=<text>, across the code, description, filename, labels, creator and location with filter[free_text_cont]=<text>, and sort with filter[sorts]=created_at asc. Unlike with_label, every other filter, labels_text_cont and free_text_cont included, applies after the per-code pick, so it only matches the version that pick returns.

limit
integer >= 1
Example: limit=50

Limit the number of artifacts returned. When more records match than the limit a 206 response is returned and meta.partial_response is true. Fetch the next page by adding a filter[created_at_lt] (or created_at_gt when sorting ascending) cursor.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e72b-f66c-7bd0-aed4-d6e2992f1642",
      • "type": "artifact",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true
      },
    • "partial_response": false,
    • "total_matching_filter": 1,
    • "total_matching_filter_exact": true
    }
}

List artifacts

Lists all artifacts for a specific step (the artefacts it produced), newest first by default. Use filter[latest_per_code]=true to list one row per code (the newest complete version, falling back to the newest purged version), each carrying a versions_count attribute. meta.total_matching_filter counts the artifacts matching the filter, stopping at 1000 (or one past the returned page, when the limit is larger) - meta.total_matching_filter_exact reports whether the count is exact.

path Parameters
step_id
required
string
Example: 01a1e72a-f98c-73b4-93d3-76233e836c5c

step id

query Parameters
filter[<query/sort filter>]=
string
Example: filter[<query/sort filter>]==> filter[code_eq]=war

API filtering guide. Named filters: filter[created_by_eq], filter[created_by_in], filter[latest_per_code], filter[with_label]. Filter by code_eq, by label with filter[with_label]=<label> (repeat it as filter[with_label][]=<label> to give several labels, all of which must match) (combined with filter[latest_per_code]=true the labels are applied before the per-code pick, so each code returns its newest version carrying them, while versions_count still counts every complete version of the code), by purge state with filter[purged_at_null]=true|false, by part of a label with filter[labels_text_cont]=<text>, across the code, description, filename, labels, creator and location with filter[free_text_cont]=<text>, and sort with filter[sorts]=created_at asc. Unlike with_label, every other filter, labels_text_cont and free_text_cont included, applies after the per-code pick, so it only matches the version that pick returns.

limit
integer >= 1
Example: limit=50

Limit the number of artifacts returned. When more records match than the limit a 206 response is returned and meta.partial_response is true. Fetch the next page by adding a filter[created_at_lt] (or created_at_gt when sorting ascending) cursor.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e72b-ffb7-7452-b757-f78772a59e5d",
      • "type": "artifact",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true
      },
    • "partial_response": false,
    • "total_matching_filter": 1,
    • "total_matching_filter_exact": true
    }
}

Workflow runs

Endpoints to interact with workflow runs

Notes:

  • The list and show endpoints are available via the following paths:
    1. /workflow_runs - will return all workflow runs accessible to the user.
    2. /project/{project_code}/workflow_runs - will return all workflow runs for all this project's workflows.
    3. /project/{project_code}/workflows/{workflow_code}/workflow_runs - will return all workflow runs this workflow.
    4. /<path/to/asset>/workflow_runs - will return all workflow runs that include a change for this asset.

List all workflow runs

Lists all workflow runs.

query Parameters
filter[<query/sort filter>]=
string
Example: filter[<query/sort filter>]==> filter[created_by_cont]=opschain

API filtering guide. Named filters: filter[active_over], filter[created_by_eq], filter[created_by_in], filter[exclude_archived]. Use filter[exclude_archived]=true to leave out workflow runs whose workflow, workflow version or project is archived.

limit
integer [ 1 .. 10000 ]
Default: 100
Example: limit=50

Limit the number of workflow runs returned. When more records match than the limit a 206 response is returned and meta.partial_response is true.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e733-07a2-70df-b475-83f3640163f1",
      • "type": "workflow_run",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": { }
      },
    • {
      • "id": "01a1e733-01e7-7be7-a6b3-1d99b2d33a38",
      • "type": "workflow_run",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": { }
      }
    ],
  • "included": [
    • {
      • "id": "01a1e733-0746-7e6a-bec1-70e050c57c10",
      • "type": "workflow_version",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e733-0152-7fbc-8e94-7b9d49144783",
      • "type": "workflow_version",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true,
      • "delete": true,
      • "execute": true
      },
    • "partial_response": false
    }
}

Run a workflow

Runs a pre-defined workflow.

Supplying the retry attribute (together with a workflow_run relationship) retries an existing workflow run that finished in an error, cancelled or aborted state instead of running a workflow from scratch. The retry creates a new workflow run; the original workflow run is left untouched.

Request Body schema: application/vnd.api+json
One of
required
object

Responses

Request samples

Content type
application/vnd.api+json
Example
{
  • "data": {
    • "attributes": {
      • "project_code": "opc",
      • "workflow_code": "assets"
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e733-1df9-77e3-bf74-0524a039cf19",
    • "type": "workflow_run",
    • "attributes": {
      • "step_tree": {
        },
      • "scheduled": false,
      • "metadata": { },
      • "created_by": "logged_in_user",
      • "created_by_name": "logged_in_user",
      • "cancelled_by": null,
      • "notify": { },
      • "skip_steps": [ ],
      • "pause_state": "none",
      • "status_code": "pending",
      • "paused": false,
      • "cancel_requested": false,
      • "paused_by": [ ],
      • "created_at": "2026-11-17T01:50:49.336372Z",
      • "started_at": null,
      • "finished_at": null,
      • "updated_at": "2026-11-17T01:50:49.361784Z",
      • "paused_at": null,
      • "project_name": "OpsChain",
      • "workflow_code": "assets"
      },
    • "relationships": {
      • "workflow_version": {
        },
      • "workflow": {
        },
      • "parent_workflow_step": {
        },
      • "root_step": {
        },
      • "steps": {
        },
      • "override_properties": {
        }
      },
    • "links": {
      • "parent": "/api/projects/opc",
      • "self": "/api/projects/opc/workflows/assets/runs/01a1e733-1df9-77e3-bf74-0524a039cf19",
      • "log_lines": "/api/workflow_runs/01a1e733-1df9-77e3-bf74-0524a039cf19/log_lines",
      • "pause": "/api/workflow_runs/01a1e733-1df9-77e3-bf74-0524a039cf19/pause"
      },
    • "meta": { }
    },
  • "included": [
    • {
      • "id": "01a1e733-0ede-7950-b80c-868330b3697d",
      • "type": "workflow_version",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e733-1e0c-75f3-89d8-ba05e95b52f0",
      • "type": "workflow_noop_step",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e733-1e1c-77ab-9606-15c01d6552e3",
      • "type": "workflow_change_step",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      }
    ]
}

Show workflow run

Shows a workflow run.

path Parameters
run_id
required
string
Example: 01a1e72b-1a64-7c6b-b8c4-3371ce2c0837

workflow run id

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e733-5891-7362-9a9f-538a6150200a",
    • "type": "workflow_run",
    • "attributes": {
      • "step_tree": {
        },
      • "scheduled": false,
      • "metadata": {
        },
      • "created_by": "waylon.daugherty-4246",
      • "created_by_name": "waylon.daugherty-4246",
      • "cancelled_by": null,
      • "notify": { },
      • "skip_steps": [ ],
      • "pause_state": "none",
      • "status_code": "success",
      • "paused": false,
      • "cancel_requested": false,
      • "paused_by": [ ],
      • "created_at": "2026-11-17T01:51:04.332051Z",
      • "started_at": "2026-11-17T01:41:17.891227Z",
      • "finished_at": "2026-11-17T01:47:16.201336Z",
      • "updated_at": "2026-11-17T01:51:04.386281Z",
      • "paused_at": null,
      • "project_name": "OpsChain",
      • "workflow_code": "assets"
      },
    • "relationships": {
      • "workflow_version": {
        },
      • "workflow": {
        },
      • "parent_workflow_step": {
        },
      • "root_step": {
        },
      • "steps": {
        },
      • "override_properties": {
        }
      },
    • "links": {
      • "parent": "/api/projects/opc",
      • "self": "/api/projects/opc/workflows/assets/runs/01a1e733-5891-7362-9a9f-538a6150200a",
      • "log_lines": "/api/workflow_runs/01a1e733-5891-7362-9a9f-538a6150200a/log_lines"
      },
    • "meta": {
      • "wait_queue": [ ],
      • "blocking_queue": [ ],
      • "authorisations": {
        }
      }
    },
  • "included": [
    • {
      • "id": "01a1e733-5758-77b5-bbfa-c6e698617a90",
      • "type": "workflow_version",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e733-58b2-70ad-be1c-813e4f0419a6",
      • "type": "workflow_noop_step",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e733-58e1-7107-a84b-1b0fa3beb575",
      • "type": "workflow_noop_step",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e733-6023-7a2e-b566-300b24e39696",
      • "type": "workflow_change_step",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e733-6040-7849-8d58-a85e7b2ed58b",
      • "type": "workflow_wait_step",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e733-616e-7b8d-a62c-512ebbe7984d",
      • "type": "workflow_workflow_step",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e733-5d65-7abc-8987-4d0841d50f5f",
      • "type": "workflow_change_step",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      }
    ]
}

Cancel workflow run

Cancels a workflow run.

path Parameters
run_id
required
string
Example: 01a1e72b-1a64-7c6b-b8c4-3371ce2c0837

workflow run id

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    • {
      • "status": 403,
      • "title": "You do not have permission to cancel the workflow run",
      • "detail": "Your authorisation rules let you view the workflow run but not cancel it."
      }
    ]
}

Pause workflow run

Pauses a running workflow run. Steps already running finish, but no further steps are dispatched until the run is resumed.

path Parameters
run_id
required
string
Example: 01a1e72b-1a64-7c6b-b8c4-3371ce2c0837

workflow run id

Request Body schema: application/vnd.api+json
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "reason": "Holding this run until the database maintenance window closes"
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e733-969b-74c1-8772-3224f75fd457",
    • "type": "workflow_run",
    • "attributes": {
      • "step_tree": {
        },
      • "scheduled": false,
      • "metadata": {
        },
      • "created_by": "numbers.spencer-4378",
      • "created_by_name": "numbers.spencer-4378",
      • "cancelled_by": null,
      • "notify": { },
      • "skip_steps": [ ],
      • "pause_state": "paused",
      • "status_code": "running",
      • "paused": true,
      • "cancel_requested": false,
      • "paused_by": [
        ],
      • "created_at": "2026-11-17T01:51:20.218105Z",
      • "started_at": "2026-11-17T01:44:09.257540Z",
      • "finished_at": null,
      • "updated_at": "2026-11-17T01:51:20.235553Z",
      • "paused_at": "2026-11-17T01:51:21.386622Z",
      • "project_name": "OpsChain",
      • "workflow_code": "assets"
      },
    • "relationships": {
      • "workflow_version": {
        },
      • "workflow": {
        },
      • "parent_workflow_step": {
        },
      • "root_step": {
        },
      • "steps": {
        },
      • "override_properties": {
        }
      },
    • "links": {
      • "parent": "/api/projects/opc",
      • "self": "/api/projects/opc/workflows/assets/runs/01a1e733-969b-74c1-8772-3224f75fd457",
      • "log_lines": "/api/workflow_runs/01a1e733-969b-74c1-8772-3224f75fd457/log_lines",
      • "resume": "/api/workflow_runs/01a1e733-969b-74c1-8772-3224f75fd457/resume"
      },
    • "meta": { }
    }
}

Resume workflow run

Resumes a paused workflow run, dispatching the steps that were held while it was paused.

path Parameters
run_id
required
string
Example: 01a1e72b-1a64-7c6b-b8c4-3371ce2c0837

workflow run id

Request Body schema: application/vnd.api+json
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "reason": "Maintenance window closed"
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e733-c7c3-7f87-b51d-27002c97fd3c",
    • "type": "workflow_run",
    • "attributes": {
      • "step_tree": {
        },
      • "scheduled": false,
      • "metadata": {
        },
      • "created_by": "kayce-4482",
      • "created_by_name": "kayce-4482",
      • "cancelled_by": null,
      • "notify": { },
      • "skip_steps": [ ],
      • "pause_state": "none",
      • "status_code": "running",
      • "paused": false,
      • "cancel_requested": false,
      • "paused_by": [
        ],
      • "created_at": "2026-11-17T01:51:32.802541Z",
      • "started_at": "2026-11-17T01:43:14.769103Z",
      • "finished_at": null,
      • "updated_at": "2026-11-17T01:51:32.820683Z",
      • "paused_at": null,
      • "project_name": "OpsChain",
      • "workflow_code": "assets"
      },
    • "relationships": {
      • "workflow_version": {
        },
      • "workflow": {
        },
      • "parent_workflow_step": {
        },
      • "root_step": {
        },
      • "steps": {
        },
      • "override_properties": {
        }
      },
    • "links": {
      • "parent": "/api/projects/opc",
      • "self": "/api/projects/opc/workflows/assets/runs/01a1e733-c7c3-7f87-b51d-27002c97fd3c",
      • "log_lines": "/api/workflow_runs/01a1e733-c7c3-7f87-b51d-27002c97fd3c/log_lines",
      • "pause": "/api/workflow_runs/01a1e733-c7c3-7f87-b51d-27002c97fd3c/pause"
      },
    • "meta": { }
    }
}

List workflow runs (workflow specific)

Lists all runs for a workflow.

path Parameters
project_code
required
string
Example: opc

project code

workflow_code
required
string
Example: assets

workflow code

query Parameters
filter[<query/sort filter>]=
string
Example: filter[<query/sort filter>]==> filter[created_by_cont]=opschain

API filtering guide. Named filters: filter[active_over], filter[created_by_eq], filter[created_by_in], filter[exclude_archived]. Use filter[exclude_archived]=true to leave out workflow runs whose workflow, workflow version or project is archived.

limit
integer [ 1 .. 10000 ]
Default: 100
Example: limit=50

Limit the number of workflow runs returned. When more records match than the limit a 206 response is returned and meta.partial_response is true.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e733-f495-7a9c-8db3-47daccb79f25",
      • "type": "workflow_run",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": { }
      }
    ],
  • "included": [
    • {
      • "id": "01a1e733-f411-7eed-ae76-258d076a583c",
      • "type": "workflow_version",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true,
      • "delete": true,
      • "execute": true
      },
    • "partial_response": false
    }
}

Run a workflow (workflow specific)

Runs a pre-defined workflow

path Parameters
project_code
required
string
Example: opc

project code

workflow_code
required
string
Example: assets

workflow code

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "version": 2,
      • "property_overrides": {
        },
      • "metadata": {
        },
      • "notify": {
        },
      • "skip_steps": [
        ]
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e734-0501-717a-864d-1f9bead08247",
    • "type": "workflow_run",
    • "attributes": {
      • "step_tree": {
        },
      • "scheduled": false,
      • "metadata": { },
      • "created_by": "logged_in_user",
      • "created_by_name": "logged_in_user",
      • "cancelled_by": null,
      • "notify": { },
      • "skip_steps": [ ],
      • "pause_state": "none",
      • "status_code": "pending",
      • "paused": false,
      • "cancel_requested": false,
      • "paused_by": [ ],
      • "created_at": "2026-11-17T01:51:48.480059Z",
      • "started_at": null,
      • "finished_at": null,
      • "updated_at": "2026-11-17T01:51:48.517075Z",
      • "paused_at": null,
      • "project_name": "OpsChain",
      • "workflow_code": "assets"
      },
    • "relationships": {
      • "workflow_version": {
        },
      • "workflow": {
        },
      • "parent_workflow_step": {
        },
      • "root_step": {
        },
      • "steps": {
        },
      • "override_properties": {
        }
      },
    • "links": {
      • "parent": "/api/projects/opc",
      • "self": "/api/projects/opc/workflows/assets/runs/01a1e734-0501-717a-864d-1f9bead08247",
      • "log_lines": "/api/workflow_runs/01a1e734-0501-717a-864d-1f9bead08247/log_lines",
      • "pause": "/api/workflow_runs/01a1e734-0501-717a-864d-1f9bead08247/pause"
      },
    • "meta": { }
    },
  • "included": [
    • {
      • "id": "01a1e733-fdab-7486-a245-97c3b590fa43",
      • "type": "workflow_version",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e734-0520-7385-9ae9-9c4aec6fab29",
      • "type": "workflow_noop_step",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e734-052b-7397-88eb-c3f82a3becf7",
      • "type": "workflow_change_step",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      }
    ]
}

Show workflow run (workflow specific)

Shows a workflow run.

path Parameters
project_code
required
string
Example: opc

project code

workflow_code
required
string
Example: assets

workflow code

run_id
required
string
Example: 01a1e72b-1a64-7c6b-b8c4-3371ce2c0837

workflow run id

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e734-2c48-7c7c-b015-e295f2ed4da8",
    • "type": "workflow_run",
    • "attributes": {
      • "step_tree": {
        },
      • "scheduled": false,
      • "metadata": {
        },
      • "created_by": "ricky-4726",
      • "created_by_name": "ricky-4726",
      • "cancelled_by": null,
      • "notify": { },
      • "skip_steps": [ ],
      • "pause_state": "none",
      • "status_code": "success",
      • "paused": false,
      • "cancel_requested": false,
      • "paused_by": [ ],
      • "created_at": "2026-11-17T01:51:58.535607Z",
      • "started_at": "2026-11-17T01:45:56.560079Z",
      • "finished_at": "2026-11-17T01:47:41.664552Z",
      • "updated_at": "2026-11-17T01:51:58.556468Z",
      • "paused_at": null,
      • "project_name": "OpsChain",
      • "workflow_code": "assets"
      },
    • "relationships": {
      • "workflow_version": {
        },
      • "workflow": {
        },
      • "parent_workflow_step": {
        },
      • "root_step": {
        },
      • "steps": {
        },
      • "override_properties": {
        }
      },
    • "links": {
      • "parent": "/api/projects/opc",
      • "self": "/api/projects/opc/workflows/assets/runs/01a1e734-2c48-7c7c-b015-e295f2ed4da8",
      • "log_lines": "/api/workflow_runs/01a1e734-2c48-7c7c-b015-e295f2ed4da8/log_lines"
      },
    • "meta": {
      • "wait_queue": [ ],
      • "blocking_queue": [ ],
      • "authorisations": {
        }
      }
    },
  • "included": [
    • {
      • "id": "01a1e734-2bdd-7909-ac77-66520c7244ed",
      • "type": "workflow_version",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e734-2c55-719e-a9cd-ec92c6d8c1db",
      • "type": "workflow_noop_step",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e734-2c65-7e27-9f34-7115aaabedbe",
      • "type": "workflow_noop_step",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e734-328c-7725-9cff-4c202108aca7",
      • "type": "workflow_change_step",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e734-32a4-7a45-b47c-fe54089df7fb",
      • "type": "workflow_wait_step",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e734-33f1-7d33-900c-0bada589d42f",
      • "type": "workflow_workflow_step",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e734-2f69-76b9-81d8-160ff893e5cf",
      • "type": "workflow_change_step",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      }
    ]
}

Cancel workflow run (workflow specific)

Cancels a workflow run.

path Parameters
project_code
required
string
Example: opc

project code

workflow_code
required
string
Example: assets

workflow code

run_id
required
string
Example: 01a1e72b-1a64-7c6b-b8c4-3371ce2c0837

workflow run id

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    • {
      • "status": 403,
      • "title": "You do not have permission to cancel the workflow run",
      • "detail": "Your authorisation rules let you view the workflow run but not cancel it."
      }
    ]
}

Workflow steps

Endpoints to interact with the steps in a workflow run

List all workflow steps

Lists all workflow steps.

query Parameters
filter[<query/sort filter>]=
string
Example: filter[<query/sort filter>]==> filter[status_code_eq]=running

API filtering guide. Named filters: filter[active_over], filter[finished], filter[waiting_for_user], filter[waiting_to_run]. Use filter[skip_reason_eq]=not_taken (or requested) to return only the steps skipped for that reason.

limit
integer [ 1 .. 1000 ]
Default: 1000
Example: limit=50

Limit the number of workflow steps returned

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e734-67a6-7dbc-bcd2-4066671aaf4e",
      • "type": "workflow_noop_step",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e734-67b7-714d-acc6-ce5a60c833b9",
      • "type": "workflow_noop_step",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e734-7100-7b60-9e51-623361c3b5fd",
      • "type": "workflow_change_step",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e734-711b-7119-ab1a-d24ee7161eba",
      • "type": "workflow_wait_step",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e734-72e7-79dc-98ee-22c2fc1d3d5f",
      • "type": "workflow_workflow_step",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e734-786c-7f9b-906e-6dfc641bec7c",
      • "type": "workflow_change_step",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e734-7890-7e73-9dd0-c699a7b49495",
      • "type": "workflow_wait_step",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e734-78bc-78cf-9312-4b725d9c8840",
      • "type": "workflow_workflow_step",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e734-6cfb-7119-bcf5-a9fb83f40740",
      • "type": "workflow_change_step",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e734-72d9-76e6-9578-bbd0a56a522a",
      • "type": "workflow_noop_step",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": false,
      • "execute": false
      },
    • "partial_response": false
    }
}

Show a workflow step

Shows a workflow step.

path Parameters
step_id
required
string
Example: 01a1e72b-23c3-731d-95eb-68f3a8a65358

workflow step id

Responses

Response samples

Content type
application/vnd.api+json
Example
{
  • "data": {
    • "id": "01a1e72b-23c3-731d-95eb-68f3a8a65358",
    • "type": "workflow_change_step",
    • "attributes": {
      • "lock_version": 1,
      • "created_by": "tandra-133",
      • "created_by_name": "tandra-133",
      • "name": "generate",
      • "step_sequence": 5,
      • "status_code": "pending",
      • "cancel_requested": false,
      • "skip_requested": false,
      • "created_at": "2026-11-17T01:42:06.528354Z",
      • "started_at": null,
      • "finished_at": null,
      • "updated_at": "2026-11-17T01:42:06.535518Z",
      • "skip_reason": null,
      • "selected_arm": null,
      • "arm_reason": null,
      • "reset_on_retry": false,
      • "arm": null,
      • "choices": null,
      • "branch": null,
      • "default": null,
      • "recover": null,
      • "retry_from": null,
      • "abort_on_reject": null,
      • "abort_on_cancel": null,
      • "when": null,
      • "ignore_failure": false,
      • "action": "generate",
      • "property_overrides": {
        }
      },
    • "relationships": {
      • "change": {
        },
      • "change_parent": {
        },
      • "action_template_version": {
        },
      • "workflow_run": {
        },
      • "children": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/workflows/assets/runs/01a1e72b-1a64-7c6b-b8c4-3371ce2c0837/steps/01a1e72b-23c3-731d-95eb-68f3a8a65358",
      • "log_lines": "/api/workflow_steps/01a1e72b-23c3-731d-95eb-68f3a8a65358/log_lines",
      • "parent": "/api/projects/opc/workflows/assets/runs/01a1e72b-1a64-7c6b-b8c4-3371ce2c0837/steps/01a1e72b-1a7b-7e67-9b4d-e3e7057f14f7",
      • "workflow_run": "/api/projects/opc/workflows/assets/runs/01a1e72b-1a64-7c6b-b8c4-3371ce2c0837"
      }
    }
}

Continue workflow step

Continues a "waiting" workflow step. To approve/reject a workflow step that needs approval see the approve workflow step API endpoint.

path Parameters
step_id
required
string
Example: 01a1e72b-2465-7836-b0ec-61772bf4f6c9

workflow step id

Request Body schema: application/vnd.api+json
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "message": "Done sanity checks. Ok to continue.",
      • "choice": "string"
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e734-bdaf-7c59-9a30-4fdf1718117d",
    • "type": "workflow_wait_step",
    • "attributes": {
      • "approved_by": [ ],
      • "rejected_by": [ ],
      • "continued_by": [
        ],
      • "requires_approval_from": null,
      • "lock_version": 3,
      • "created_by": "clyde.ziemann-4957",
      • "created_by_name": "clyde.ziemann-4957",
      • "name": "Wait",
      • "step_sequence": 8,
      • "status_code": "continued",
      • "cancel_requested": false,
      • "skip_requested": false,
      • "created_at": "2026-11-17T01:46:26.703378Z",
      • "started_at": "2026-11-17T01:47:26.703378Z",
      • "finished_at": "2026-11-17T01:52:35.880702Z",
      • "updated_at": "2026-11-17T01:52:35.938240Z",
      • "skip_reason": null,
      • "selected_arm": null,
      • "arm_reason": null,
      • "reset_on_retry": true,
      • "arm": null,
      • "choices": null,
      • "branch": null,
      • "default": null,
      • "recover": null,
      • "retry_from": null,
      • "abort_on_reject": null,
      • "abort_on_cancel": null,
      • "when": null
      },
    • "relationships": {
      • "workflow_run": {
        },
      • "children": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/workflows/assets/runs/01a1e734-acb3-7d3c-bcc3-1b49a77144fc/steps/01a1e734-bdaf-7c59-9a30-4fdf1718117d",
      • "log_lines": "/api/workflow_steps/01a1e734-bdaf-7c59-9a30-4fdf1718117d/log_lines",
      • "parent": "/api/projects/opc/workflows/assets/runs/01a1e734-acb3-7d3c-bcc3-1b49a77144fc/steps/01a1e734-acd1-7240-af37-88d5a35bf2cd",
      • "workflow_run": "/api/projects/opc/workflows/assets/runs/01a1e734-acb3-7d3c-bcc3-1b49a77144fc"
      }
    }
}

Approve workflow step

Approve a workflow step that requires approval. To continue a workflow step that does need approval see the continue workflow step API endpoint

path Parameters
step_id
required
string
Example: 01a1e72b-24b3-7c26-8bc5-aaaafac710dc

workflow step id

Request Body schema: application/vnd.api+json
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "message": "Ok to proceed.",
      • "choice": "string"
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e735-1e7a-7743-8c15-cb7e1ad2bf3c",
    • "type": "workflow_wait_step",
    • "attributes": {
      • "approved_by": [
        ],
      • "rejected_by": [ ],
      • "continued_by": [ ],
      • "requires_approval_from": {
        },
      • "lock_version": 3,
      • "created_by": "bridget_treutel-5126",
      • "created_by_name": "bridget_treutel-5126",
      • "name": "Approval",
      • "step_sequence": 8,
      • "status_code": "approved",
      • "cancel_requested": false,
      • "skip_requested": false,
      • "created_at": "2026-11-17T01:45:43.800828Z",
      • "started_at": "2026-11-17T01:46:43.800828Z",
      • "finished_at": "2026-11-17T01:53:00.572742Z",
      • "updated_at": "2026-11-17T01:53:00.602122Z",
      • "skip_reason": null,
      • "selected_arm": null,
      • "arm_reason": null,
      • "reset_on_retry": true,
      • "arm": null,
      • "choices": null,
      • "branch": null,
      • "default": null,
      • "recover": null,
      • "retry_from": null,
      • "abort_on_reject": null,
      • "abort_on_cancel": null,
      • "when": null
      },
    • "relationships": {
      • "workflow_run": {
        },
      • "children": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/workflows/assets/runs/01a1e735-125c-7548-b664-877bea912607/steps/01a1e735-1e7a-7743-8c15-cb7e1ad2bf3c",
      • "log_lines": "/api/workflow_steps/01a1e735-1e7a-7743-8c15-cb7e1ad2bf3c/log_lines",
      • "parent": "/api/projects/opc/workflows/assets/runs/01a1e735-125c-7548-b664-877bea912607/steps/01a1e735-1267-77c9-ba24-dae59790c608",
      • "workflow_run": "/api/projects/opc/workflows/assets/runs/01a1e735-125c-7548-b664-877bea912607"
      }
    }
}

Reject workflow step

Reject a workflow step that requires approval.

path Parameters
step_id
required
string
Example: 01a1e72b-23dd-762f-8a0d-a28a90ef5fc1

workflow step id

Request Body schema: application/vnd.api+json
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "message": "Ok to proceed."
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e735-7436-7c2d-98ed-6d2b82cd34f3",
    • "type": "workflow_wait_step",
    • "attributes": {
      • "approved_by": [ ],
      • "rejected_by": [
        ],
      • "continued_by": [ ],
      • "requires_approval_from": {
        },
      • "lock_version": 3,
      • "created_by": "emile-5295",
      • "created_by_name": "emile-5295",
      • "name": "Approval",
      • "step_sequence": 8,
      • "status_code": "rejected",
      • "cancel_requested": false,
      • "skip_requested": false,
      • "created_at": "2026-11-17T01:45:03.542919Z",
      • "started_at": "2026-11-17T01:46:03.542919Z",
      • "finished_at": "2026-11-17T01:53:22.534056Z",
      • "updated_at": "2026-11-17T01:53:22.547203Z",
      • "skip_reason": null,
      • "selected_arm": null,
      • "arm_reason": null,
      • "reset_on_retry": true,
      • "arm": null,
      • "choices": null,
      • "branch": null,
      • "default": null,
      • "recover": null,
      • "retry_from": null,
      • "abort_on_reject": null,
      • "abort_on_cancel": null,
      • "when": null
      },
    • "relationships": {
      • "workflow_run": {
        },
      • "children": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/workflows/assets/runs/01a1e735-64d2-7ef5-a113-066de214ce72/steps/01a1e735-7436-7c2d-98ed-6d2b82cd34f3",
      • "log_lines": "/api/workflow_steps/01a1e735-7436-7c2d-98ed-6d2b82cd34f3/log_lines",
      • "parent": "/api/projects/opc/workflows/assets/runs/01a1e735-64d2-7ef5-a113-066de214ce72/steps/01a1e735-64e1-7092-a3e1-0b902713ce7a",
      • "workflow_run": "/api/projects/opc/workflows/assets/runs/01a1e735-64d2-7ef5-a113-066de214ce72"
      }
    }
}

List workflow steps (run specific)

Lists all steps in a workflow run.

path Parameters
project_code
required
string
Example: opc

project code

workflow_code
required
string
Example: assets

workflow code

run_id
required
string
Example: 01a1e72b-1a64-7c6b-b8c4-3371ce2c0837

workflow run id

query Parameters
limit
integer [ 1 .. 1000 ]
Default: 1000
Example: limit=50

Limit the number of workflow steps returned

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e735-a79b-7d4f-a151-494b3d6953d0",
      • "type": "workflow_noop_step",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e735-a7ac-7159-99a8-2c306cde68fa",
      • "type": "workflow_noop_step",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e735-aae8-7ee8-91fc-f814bc1df71f",
      • "type": "workflow_change_step",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e735-ab1d-7be9-a892-6b71c7794e87",
      • "type": "workflow_wait_step",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e735-ad5f-7fc4-ab8a-c780d33e3a52",
      • "type": "workflow_workflow_step",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e735-af53-7ad1-95eb-dda93715e406",
      • "type": "workflow_change_step",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e735-af69-784f-8443-fb03785f0f67",
      • "type": "workflow_wait_step",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e735-af7f-7824-9e51-b62bb9cf74c8",
      • "type": "workflow_workflow_step",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e735-a94d-7bef-8d1d-3d521825da73",
      • "type": "workflow_change_step",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true,
      • "execute": true
      },
    • "partial_response": false
    }
}

Show workflow step (run specific)

Shows a step of a workflow run.

path Parameters
project_code
required
string
Example: opc

project code

workflow_code
required
string
Example: assets

workflow code

run_id
required
string
Example: 01a1e72b-1a64-7c6b-b8c4-3371ce2c0837

workflow run id

step_id
required
string
Example: 01a1e72b-23c3-731d-95eb-68f3a8a65358

workflow step id

Responses

Response samples

Content type
application/vnd.api+json
Example
{
  • "data": {
    • "id": "01a1e72b-23c3-731d-95eb-68f3a8a65358",
    • "type": "workflow_change_step",
    • "attributes": {
      • "lock_version": 1,
      • "created_by": "tandra-133",
      • "created_by_name": "tandra-133",
      • "name": "generate",
      • "step_sequence": 5,
      • "status_code": "pending",
      • "cancel_requested": false,
      • "skip_requested": false,
      • "created_at": "2026-11-17T01:42:06.528354Z",
      • "started_at": null,
      • "finished_at": null,
      • "updated_at": "2026-11-17T01:42:06.535518Z",
      • "skip_reason": null,
      • "selected_arm": null,
      • "arm_reason": null,
      • "reset_on_retry": false,
      • "arm": null,
      • "choices": null,
      • "branch": null,
      • "default": null,
      • "recover": null,
      • "retry_from": null,
      • "abort_on_reject": null,
      • "abort_on_cancel": null,
      • "when": null,
      • "ignore_failure": false,
      • "action": "generate",
      • "property_overrides": {
        }
      },
    • "relationships": {
      • "change": {
        },
      • "change_parent": {
        },
      • "action_template_version": {
        },
      • "workflow_run": {
        },
      • "children": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/workflows/assets/runs/01a1e72b-1a64-7c6b-b8c4-3371ce2c0837/steps/01a1e72b-23c3-731d-95eb-68f3a8a65358",
      • "log_lines": "/api/workflow_steps/01a1e72b-23c3-731d-95eb-68f3a8a65358/log_lines",
      • "parent": "/api/projects/opc/workflows/assets/runs/01a1e72b-1a64-7c6b-b8c4-3371ce2c0837/steps/01a1e72b-1a7b-7e67-9b4d-e3e7057f14f7",
      • "workflow_run": "/api/projects/opc/workflows/assets/runs/01a1e72b-1a64-7c6b-b8c4-3371ce2c0837"
      }
    }
}

Continue workflow step (run specific)

Continues a "waiting" workflow step. To approve/reject a workflow step that needs approval see the approve workflow step API endpoint.

path Parameters
project_code
required
string
Example: opc

project code

workflow_code
required
string
Example: assets

workflow code

run_id
required
string
Example: 01a1e72b-1a64-7c6b-b8c4-3371ce2c0837

workflow run id

step_id
required
string
Example: 01a1e72b-2465-7836-b0ec-61772bf4f6c9

workflow step id

Request Body schema: application/vnd.api+json
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "message": "Done sanity checks. Ok to continue.",
      • "choice": "string"
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e735-cba0-7e6a-a88e-ea1a41f16223",
    • "type": "workflow_wait_step",
    • "attributes": {
      • "approved_by": [ ],
      • "rejected_by": [ ],
      • "continued_by": [
        ],
      • "requires_approval_from": null,
      • "lock_version": 3,
      • "created_by": "hallie.kub-5563",
      • "created_by_name": "hallie.kub-5563",
      • "name": "Wait",
      • "step_sequence": 8,
      • "status_code": "continued",
      • "cancel_requested": false,
      • "skip_requested": false,
      • "created_at": "2026-11-17T01:42:48.154405Z",
      • "started_at": "2026-11-17T01:43:48.154405Z",
      • "finished_at": "2026-11-17T01:53:44.916645Z",
      • "updated_at": "2026-11-17T01:53:44.944989Z",
      • "skip_reason": null,
      • "selected_arm": null,
      • "arm_reason": null,
      • "reset_on_retry": true,
      • "arm": null,
      • "choices": null,
      • "branch": null,
      • "default": null,
      • "recover": null,
      • "retry_from": null,
      • "abort_on_reject": null,
      • "abort_on_cancel": null,
      • "when": null
      },
    • "relationships": {
      • "workflow_run": {
        },
      • "children": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/workflows/assets/runs/01a1e735-c616-7c5a-8c74-9cf0b59e4df5/steps/01a1e735-cba0-7e6a-a88e-ea1a41f16223",
      • "log_lines": "/api/workflow_steps/01a1e735-cba0-7e6a-a88e-ea1a41f16223/log_lines",
      • "parent": "/api/projects/opc/workflows/assets/runs/01a1e735-c616-7c5a-8c74-9cf0b59e4df5/steps/01a1e735-c61f-79c4-9254-28ea1a704134",
      • "workflow_run": "/api/projects/opc/workflows/assets/runs/01a1e735-c616-7c5a-8c74-9cf0b59e4df5"
      }
    }
}

Approve workflow step (run specific)

Approve a workflow step that requires approval. To continue a workflow step that does need approval see the continue workflow step API endpoint

path Parameters
project_code
required
string
Example: opc

project code

workflow_code
required
string
Example: assets

workflow code

run_id
required
string
Example: 01a1e72b-1a64-7c6b-b8c4-3371ce2c0837

workflow run id

step_id
required
string
Example: 01a1e72b-24b3-7c26-8bc5-aaaafac710dc

workflow step id

Request Body schema: application/vnd.api+json
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "message": "Ok to proceed.",
      • "choice": "string"
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e736-0b02-7bce-b3c4-e0891ed28db6",
    • "type": "workflow_wait_step",
    • "attributes": {
      • "approved_by": [
        ],
      • "rejected_by": [ ],
      • "continued_by": [ ],
      • "requires_approval_from": {
        },
      • "lock_version": 3,
      • "created_by": "ronny-5732",
      • "created_by_name": "ronny-5732",
      • "name": "Approval",
      • "step_sequence": 8,
      • "status_code": "approved",
      • "cancel_requested": false,
      • "skip_requested": false,
      • "created_at": "2026-11-17T01:44:00.252287Z",
      • "started_at": "2026-11-17T01:45:00.252287Z",
      • "finished_at": "2026-11-17T01:54:01.280153Z",
      • "updated_at": "2026-11-17T01:54:01.372492Z",
      • "skip_reason": null,
      • "selected_arm": null,
      • "arm_reason": null,
      • "reset_on_retry": true,
      • "arm": null,
      • "choices": null,
      • "branch": null,
      • "default": null,
      • "recover": null,
      • "retry_from": null,
      • "abort_on_reject": null,
      • "abort_on_cancel": null,
      • "when": null
      },
    • "relationships": {
      • "workflow_run": {
        },
      • "children": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/workflows/assets/runs/01a1e736-02ce-7146-ad3e-2492d0fd0891/steps/01a1e736-0b02-7bce-b3c4-e0891ed28db6",
      • "log_lines": "/api/workflow_steps/01a1e736-0b02-7bce-b3c4-e0891ed28db6/log_lines",
      • "parent": "/api/projects/opc/workflows/assets/runs/01a1e736-02ce-7146-ad3e-2492d0fd0891/steps/01a1e736-02db-7487-969f-896eef10a34c",
      • "workflow_run": "/api/projects/opc/workflows/assets/runs/01a1e736-02ce-7146-ad3e-2492d0fd0891"
      }
    }
}

Reject workflow step (run specific)

Reject a workflow step that requires approval.

path Parameters
project_code
required
string
Example: opc

project code

workflow_code
required
string
Example: assets

workflow code

run_id
required
string
Example: 01a1e72b-1a64-7c6b-b8c4-3371ce2c0837

workflow run id

step_id
required
string
Example: 01a1e72b-23dd-762f-8a0d-a28a90ef5fc1

workflow step id

Request Body schema: application/vnd.api+json
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "message": "Ok to proceed."
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e736-4312-7c42-aa3a-f6051598af6a",
    • "type": "workflow_wait_step",
    • "attributes": {
      • "approved_by": [ ],
      • "rejected_by": [
        ],
      • "continued_by": [ ],
      • "requires_approval_from": {
        },
      • "lock_version": 3,
      • "created_by": "clifton.armstrong-5901",
      • "created_by_name": "clifton.armstrong-5901",
      • "name": "Approval",
      • "step_sequence": 8,
      • "status_code": "rejected",
      • "cancel_requested": false,
      • "skip_requested": false,
      • "created_at": "2026-11-17T01:47:31.436088Z",
      • "started_at": "2026-11-17T01:48:31.436088Z",
      • "finished_at": "2026-11-17T01:54:15.503548Z",
      • "updated_at": "2026-11-17T01:54:15.514452Z",
      • "skip_reason": null,
      • "selected_arm": null,
      • "arm_reason": null,
      • "reset_on_retry": true,
      • "arm": null,
      • "choices": null,
      • "branch": null,
      • "default": null,
      • "recover": null,
      • "retry_from": null,
      • "abort_on_reject": null,
      • "abort_on_cancel": null,
      • "when": null
      },
    • "relationships": {
      • "workflow_run": {
        },
      • "children": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/workflows/assets/runs/01a1e736-3ca8-7c06-8198-e8acf2626965/steps/01a1e736-4312-7c42-aa3a-f6051598af6a",
      • "log_lines": "/api/workflow_steps/01a1e736-4312-7c42-aa3a-f6051598af6a/log_lines",
      • "parent": "/api/projects/opc/workflows/assets/runs/01a1e736-3ca8-7c06-8198-e8acf2626965/steps/01a1e736-3cb3-71fa-92e4-702a116851a3",
      • "workflow_run": "/api/projects/opc/workflows/assets/runs/01a1e736-3ca8-7c06-8198-e8acf2626965"
      }
    }
}

Events

Endpoints to interact with events.

List events

Lists all events.

query Parameters
filter[<query/sort filter>]=
string
Example: filter[<query/sort filter>]==> filter[query_param_code_eq]=opc

API filtering guide. Named filters: filter[change_action_eq], filter[change_created_by_eq], filter[change_or_step_action_eq], filter[change_or_step_created_by_eq], filter[for_change], filter[for_workflow_run], filter[for_workflow_run_nested], filter[run_or_step_workflow_eq], filter[run_workflow_eq], filter[step_action_eq], filter[step_created_by_eq], filter[step_workflow_eq]. filter[for_change]=<change id> returns every event for a change, including events on its steps regardless of tree depth, e.g. > filter[for_change]=79f7f4e2-3b1d-4b2a-9e2c-1d9c2f6a4b3e. filter[for_workflow_run]=<workflow run id> returns every event for a workflow run and its own workflow steps, e.g. > filter[for_workflow_run]=2f8b6a1c-5e4d-4a3b-8c1f-6d9e2a7b5c4d. filter[for_workflow_run_nested]=<workflow run id> does the same as for_workflow_run but additionally includes events from any changes the run spawned (e.g. via a change step) and their steps, e.g. > filter[for_workflow_run_nested]=2f8b6a1c-5e4d-4a3b-8c1f-6d9e2a7b5c4d.

limit
integer [ 1 .. 1000 ]
Default: 10
Example: limit=50

Limit the number of events returned

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e72e-baf7-7ffd-aebd-c4c7333e35c4",
      • "type": "event",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true
      },
    • "partial_response": false
    }
}

Create event

Creates an event. Attributes other than type become the event data, apart from a <source>_id or <source>_path attribute (e.g. node_path, change_id), which sets the event source instead. Supply a source object naming exactly one resource (e.g. {"node_path": "/projects/bank"}) to set the source explicitly; an unknown key is rejected. Supply a data object to store it as the event data exactly as sent, so its keys are never taken as the source.

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "type": "custom event",
      • "source": {
        },
      • "data": {
        },
      • "any_key": "with a value",
      • "another_key": "with a different value",
      • "nested": {
        }
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72e-bce9-7ca5-8bc6-04fa98dfae71",
    • "type": "event",
    • "attributes": {
      • "some": "event data",
      • "username": "logged_in_user",
      • "system": false,
      • "type": "my event",
      • "event_node_path": null,
      • "created_at": "2026-11-17T01:46:02.344664Z"
      },
    • "relationships": {
      • "source": {
        }
      },
    • "links": {
      • "self": "/api/events/01a1e72e-bce9-7ca5-8bc6-04fa98dfae71"
      }
    }
}

Show event

Shows an event.

path Parameters
event_id
required
string
Example: 01a1e72b-1197-7f8a-b85a-f40b962e12aa

event id

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72e-c2b1-7cde-8612-4bf01c27e0fe",
    • "type": "event",
    • "attributes": {
      • "nested": {
        },
      • "any_key": "with a value",
      • "another_key": "with a different value",
      • "username": "samatha",
      • "system": false,
      • "type": "my custom event",
      • "event_node_path": "/projects/opc",
      • "created_at": "2026-11-17T01:46:03.824695Z"
      },
    • "relationships": {
      • "source": {
        }
      },
    • "links": {
      • "self": "/api/events/01a1e72e-c2b1-7cde-8612-4bf01c27e0fe"
      }
    }
}

Event filters

List event filters

Lists all event filters.

query Parameters
filter[<query/sort filter>]=
string
Example: filter[<query/sort filter>]==> filter[code_eq]=changes_success

API filtering guide. Named filters: filter[created_by_eq], filter[created_by_in].

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e72e-a0a8-742d-91e6-ac423616eb2e",
      • "type": "event_filter",
      • "attributes": {
        },
      • "links": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true,
      • "delete": true
      }
    }
}

Create event filter

Create an event filter.

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "code": "change_success",
      • "description": "Filter for successful changes in dev",
      • "rules": {
        }
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72e-a272-7957-b0ab-73a6b4b3f8a2",
    • "type": "event_filter",
    • "attributes": {
      • "rules": {
        },
      • "code": "3uasb",
      • "description": "Voluptatibus ab omnis ut.",
      • "created_by": "logged_in_user",
      • "created_by_name": "logged_in_user",
      • "created_at": "2026-11-17T01:45:55.569272Z",
      • "updated_at": "2026-11-17T01:45:55.569272Z"
      },
    • "links": {
      • "self": "/api/event_filters/3uasb",
      • "subscribers": "/api/event_filters/3uasb/event_subscribers"
      }
    }
}

Show event filter

Show an event filter.

path Parameters
event_filter_code
required
string
Example: change_success

event filter code

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72e-a8e1-795a-bdc9-2b727fba5649",
    • "type": "event_filter",
    • "attributes": {
      • "rules": {
        },
      • "code": "change_success",
      • "description": "Filter for successful changes in dev",
      • "created_by": "opschain",
      • "created_by_name": "opschain",
      • "created_at": "2026-11-17T01:45:57.216585Z",
      • "updated_at": "2026-11-17T01:45:57.216585Z"
      },
    • "links": {
      • "self": "/api/event_filters/change_success",
      • "subscribers": "/api/event_filters/change_success/event_subscribers"
      }
    }
}

Update event filter

Update an event filter.

path Parameters
event_filter_code
required
string
Example: change_success

event filter code

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "rules": {
        },
      • "description": "hello world errors filter"
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72e-aba5-760c-8dbe-6e21dc63ed89",
    • "type": "event_filter",
    • "attributes": {
      • "rules": {
        },
      • "code": "change_success",
      • "description": "hello world errors filter",
      • "created_by": "opschain",
      • "created_by_name": "opschain",
      • "created_at": "2026-11-17T01:45:57.924402Z",
      • "updated_at": "2026-11-17T01:45:57.941153Z"
      },
    • "links": {
      • "self": "/api/event_filters/change_success",
      • "subscribers": "/api/event_filters/change_success/event_subscribers"
      }
    }
}

Delete event filter

Delete an event filter.

path Parameters
event_filter_code
required
string
Example: change_success

event filter code

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    • {
      • "status": 403,
      • "title": "You do not have permission to delete the event filter",
      • "detail": "Your authorisation rules let you view the event filter but not delete it."
      }
    ]
}

Event subscribers

List event subscribers

Lists all event subscribers.

query Parameters
filter[<query/sort filter>]=
string
Example: filter[<query/sort filter>]==> filter[enabled_eq]=true

API filtering guide. Named filters: filter[created_by_eq], filter[created_by_in].

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e72e-c714-7f04-a183-086b98cfba41",
      • "type": "event_subscriber",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": { }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true,
      • "delete": true
      }
    }
}

Create event subscriber

Create an event subscriber without a node in the path.

The subscriber is still attached to a node - channel_parent_path names the node owning the notification channel, and the event filter supplies the node the subscription applies to.

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "event_filter_code": "change_success",
      • "channel_parent_path": "/system_configuration",
      • "channel_code": "system_email",
      • "channel_kwargs": {
        },
      • "enabled": true
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72e-cd07-7bd6-a399-3f797b7599fe",
    • "type": "event_subscriber",
    • "attributes": {
      • "enabled": true,
      • "created_by": "logged_in_user",
      • "created_by_name": "logged_in_user",
      • "channel_kwargs": {
        },
      • "created_at": "2026-11-17T01:46:06.470460Z",
      • "updated_at": "2026-11-17T01:46:06.470460Z"
      },
    • "relationships": {
      • "event_filter": {
        },
      • "notification_channel": {
        }
      },
    • "links": {
      • "self": "/api/event_subscribers/01a1e72e-cd07-7bd6-a399-3f797b7599fe"
      },
    • "meta": { }
    }
}

List event node subscribers

List event subscribers for a specific project, environment or asset.

path Parameters
project_code
required
string
Example: opc

project code

environment_code
required
string
Example: dev

environment code

query Parameters
filter[<query/sort filter>]=
string
Example: filter[<query/sort filter>]==> filter[enabled_eq]=true

API filtering guide. Named filters: filter[created_by_eq], filter[created_by_in].

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e72e-dd7f-789c-9374-d0695b4953af",
      • "type": "event_subscriber",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": { }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true,
      • "delete": true
      }
    }
}

Create event subscriber

Create an event subscriber.

path Parameters
project_code
required
string
Example: opc

project code

environment_code
required
string
Example: dev

environment code

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "event_filter_code": "change_success",
      • "channel_parent_path": "/system_configuration",
      • "channel_code": "system_email",
      • "channel_kwargs": {
        },
      • "enabled": true
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72e-e39b-7789-8b59-ece4d04eb727",
    • "type": "event_subscriber",
    • "attributes": {
      • "enabled": true,
      • "created_by": "logged_in_user",
      • "created_by_name": "logged_in_user",
      • "channel_kwargs": {
        },
      • "created_at": "2026-11-17T01:46:12.250277Z",
      • "updated_at": "2026-11-17T01:46:12.250277Z"
      },
    • "relationships": {
      • "event_filter": {
        },
      • "notification_channel": {
        }
      },
    • "links": {
      • "self": "/api/event_subscribers/01a1e72e-e39b-7789-8b59-ece4d04eb727"
      },
    • "meta": { }
    }
}

Show event subscriber

Show an event subscriber.

path Parameters
event_subscriber_id
required
string
Example: 01a1e72b-126e-77ca-a5db-b92d9f996c5a

event subscriber id

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72e-f77b-7317-b98c-f92c10ac56e1",
    • "type": "event_subscriber",
    • "attributes": {
      • "enabled": true,
      • "created_by": "tanesha.feest-2062",
      • "created_by_name": "tanesha.feest-2062",
      • "channel_kwargs": { },
      • "created_at": "2026-11-17T01:46:17.338024Z",
      • "updated_at": "2026-11-17T01:46:17.338024Z"
      },
    • "relationships": {
      • "event_filter": {
        },
      • "notification_channel": {
        }
      },
    • "links": {
      • "self": "/api/event_subscribers/01a1e72e-f77b-7317-b98c-f92c10ac56e1"
      },
    • "meta": { }
    }
}

Update event subscriber

Update an event subscriber. A subscriber to a node event filter (a trigger) may be updated by its creator, or by anyone who can update the node.

path Parameters
event_subscriber_id
required
string
Example: 01a1e72b-126e-77ca-a5db-b92d9f996c5a

event subscriber id

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "event_filter_code": "change_success",
      • "channel_parent_path": "/projects/opc",
      • "channel_code": "project_direct",
      • "channel_kwargs": {
        },
      • "enabled": false
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72e-fb8b-7d50-877f-a7352afbf026",
    • "type": "event_subscriber",
    • "attributes": {
      • "enabled": false,
      • "created_by": "logged_in_user",
      • "created_by_name": "logged_in_user",
      • "channel_kwargs": {
        },
      • "created_at": "2026-11-17T01:46:18.378346Z",
      • "updated_at": "2026-11-17T01:46:18.437875Z"
      },
    • "relationships": {
      • "event_filter": {
        },
      • "notification_channel": {
        }
      },
    • "links": {
      • "self": "/api/event_subscribers/01a1e72e-fb8b-7d50-877f-a7352afbf026"
      },
    • "meta": { }
    }
}

Delete event subscriber

Delete an event subscriber. A subscriber to a node event filter (a trigger) may be deleted by its creator, or by anyone who can delete on the node, and its event filter is deleted too when no other subscriber uses it.

path Parameters
event_subscriber_id
required
string
Example: 01a1e72b-126e-77ca-a5db-b92d9f996c5a

event subscriber id

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    • {
      • "status": 404,
      • "title": "Record not found",
      • "meta": {
        }
      }
    ]
}

Triggers

List triggers

List the triggers that fire for events on a project, environment or asset: those created on the node and on its ancestors. Each trigger is an event subscriber, returned with its event filter and notification channel included. The response's meta.authorisations says whether the current user may update, delete and execute on this node, and each trigger's meta.authorisations.edit whether they may change what it does (its rules, channel or kwargs): only its creator or a superuser may.

path Parameters
project_code
required
string
Example: opc

project code

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e732-30e9-7403-8c6c-8f76cd90c118",
      • "type": "event_subscriber",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": {
        }
      }
    ],
  • "included": [
    • {
      • "id": "01a1e732-30e3-7b7a-a45a-b96a6cf8efef",
      • "type": "event_filter",
      • "attributes": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e732-30dd-7170-b33f-920f339188b8",
      • "type": "notification_channel",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true,
      • "delete": true,
      • "execute": true
      }
    }
}

Create trigger

Create a trigger on a project, environment or asset: an event filter and an event subscriber, in one request. The trigger fires for events on the node and the nodes below it; the filter's event_node_path rule is written from the node, replacing any supplied. The filter also gets a system rule: true when its event type is one OpsChain raises (one starting api:, audit:, error:, info:, opschain:, warn: or warning:), so an event a user posts with that type cannot fire it, and false for a custom event type. A supplied system rule that disagrees is refused, as is a type rule naming both kinds of event type. It runs as its creator, and only its creator (or a superuser) may later change what it does.

Set create_channel_for_job to create_change_job or create_workflow_run_job to run a change or a workflow. The trigger then uses OpsChain's system-wide channel for that job; no channel is created. Creating such a trigger needs execute access on its target rather than update access to the node: on the change's action (parent_path and action in channel_kwargs) or on the workflow (project_code and code). A target that uses Mustache is not checked when the trigger is created; the trigger still runs as its creator, so the change or workflow is refused when it fires if the creator cannot execute it.

Alternatively name an existing notification channel with channel_parent_path and channel_code, which needs update access to the node. A trigger sending to a webhook channel also needs execute access on that channel, because it sends event data outside OpsChain.

channel_kwargs holds the values this trigger passes to the channel's job, for example the parent_path and action of the change to run. Values may use Mustache to read the event that fired the trigger, for example {{event.event_node_path}} or {{event.type}}. A key the channel's own kwargs already set is refused, because the channel's value would win.

path Parameters
project_code
required
string
Example: opc

project code

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "code": "smoke_test_on_success",
      • "description": "Smoke test after a successful change",
      • "enabled": true,
      • "rules": {
        },
      • "channel_parent_path": "/projects/opc",
      • "channel_code": "run_change",
      • "create_channel_for_job": "create_change_job",
      • "channel_kwargs": {
        }
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e732-3293-787e-9a52-c533e441e34f",
    • "type": "event_subscriber",
    • "attributes": {
      • "enabled": true,
      • "created_by": "logged_in_user",
      • "created_by_name": "logged_in_user",
      • "channel_kwargs": {
        },
      • "created_at": "2026-11-17T01:49:49.074294Z",
      • "updated_at": "2026-11-17T01:49:49.074294Z"
      },
    • "relationships": {
      • "event_filter": {
        },
      • "notification_channel": {
        }
      },
    • "links": {
      • "self": "/api/event_subscribers/01a1e732-3293-787e-9a52-c533e441e34f"
      },
    • "meta": { }
    },
  • "included": [
    • {
      • "id": "01a1e732-3289-7883-a42c-4327277346fa",
      • "type": "event_filter",
      • "attributes": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e732-31d8-79be-90c0-3b75e1f70982",
      • "type": "notification_channel",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      }
    ]
}

Show trigger

Show a trigger created on this node, with its event filter and notification channel included. The response's meta.authorisations says whether the current user may update, delete and execute on this node, and the trigger's own meta.authorisations.edit whether they may change what it does (its rules, channel or kwargs): only its creator or a superuser may.

path Parameters
project_code
required
string
Example: opc

project code

trigger_id
required
string
Example: 019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b

trigger (event subscriber) id

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e732-4c89-7bf0-b829-c362784758db",
    • "type": "event_subscriber",
    • "attributes": {
      • "enabled": true,
      • "created_by": "logged_in_user",
      • "created_by_name": "logged_in_user",
      • "channel_kwargs": {
        },
      • "created_at": "2026-11-17T01:49:55.720400Z",
      • "updated_at": "2026-11-17T01:49:55.720400Z"
      },
    • "relationships": {
      • "event_filter": {
        },
      • "notification_channel": {
        }
      },
    • "links": {
      • "self": "/api/event_subscribers/01a1e732-4c89-7bf0-b829-c362784758db"
      },
    • "meta": {
      • "authorisations": {
        }
      }
    },
  • "meta": {
    • "authorisations": {
      • "update": true,
      • "delete": true,
      • "execute": true
      }
    },
  • "included": [
    • {
      • "id": "01a1e732-4c85-70b2-8bef-3c2b52c3bbc4",
      • "type": "event_filter",
      • "attributes": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e732-4c7e-7119-8686-bafac755758f",
      • "type": "notification_channel",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      }
    ]
}

Update trigger

Update a trigger created on this node. The filter keeps its event_node_path rule, Leave out the system rule; OpsChain sets it from the event types. A supplied one that disagrees is refused. Anyone other than its creator needs update access to the node to change it in any way; its creator may enable or disable it without that access. Only its creator (or a superuser) may change its rules, channel or kwargs. For a trigger that runs a change or a workflow, that change needs the creator's execute access on the target instead of update access to the node, unless the target uses Mustache; for any other trigger it needs update access to the node. Re-enabling a trigger that runs a change or a workflow needs its creator to still have execute access on the target, unless it uses Mustache; re-enabling a webhook trigger needs its creator to still have execute access on the channel.

channel_kwargs holds the values this trigger passes to the channel's job, for example the parent_path and action of the change to run. Values may use Mustache to read the event that fired the trigger, for example {{event.event_node_path}} or {{event.type}}. A key the channel's own kwargs already set is refused, because the channel's value would win.

path Parameters
project_code
required
string
Example: opc

project code

trigger_id
required
string
Example: 019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b

trigger (event subscriber) id

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "description": "Run the full test after a successful change",
      • "enabled": false,
      • "rules": {
        },
      • "channel_parent_path": "/projects/opc",
      • "channel_code": "run_change",
      • "create_channel_for_job": "create_change_job",
      • "channel_kwargs": {
        }
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e732-527b-7547-b587-31689f6058da",
    • "type": "event_subscriber",
    • "attributes": {
      • "enabled": true,
      • "created_by": "logged_in_user",
      • "created_by_name": "logged_in_user",
      • "channel_kwargs": {
        },
      • "created_at": "2026-11-17T01:49:57.242008Z",
      • "updated_at": "2026-11-17T01:49:57.274642Z"
      },
    • "relationships": {
      • "event_filter": {
        },
      • "notification_channel": {
        }
      },
    • "links": {
      • "self": "/api/event_subscribers/01a1e732-527b-7547-b587-31689f6058da"
      },
    • "meta": { }
    },
  • "included": [
    • {
      • "id": "01a1e732-5276-7fe8-9689-dd68067f6b35",
      • "type": "event_filter",
      • "attributes": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e732-5270-7e0c-a627-5dcc6b1b76c1",
      • "type": "notification_channel",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      }
    ]
}

Delete trigger

Delete a trigger created on this node, and its event filter when no other subscriber uses it. Its notification channel is kept. Its creator, or anyone who can delete on the node, may delete it.

path Parameters
project_code
required
string
Example: opc

project code

trigger_id
required
string
Example: 019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b

trigger (event subscriber) id

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    • {
      • "status": 404,
      • "title": "Record not found",
      • "meta": {
        }
      }
    ]
}

Global notification channels

List notification channels

Lists all global notification channels.

query Parameters
filter[<query/sort filter>]=
string
Example: filter[<query/sort filter>]==> filter[code_eq]=slack

API filtering guide. Named filters: filter[created_by_eq], filter[created_by_in].

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e730-10eb-77ca-977c-28c0d97bb447",
      • "type": "notification_channel",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true,
      • "delete": true
      }
    }
}

Create notification channel

Create a global notification channel, available to every node in the instance.

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "code": "ops_team_slack",
      • "notification_job_code": "direct_job",
      • "format": "slack",
      • "default_channel": false,
      • "enabled": true,
      • "description": "Slack channel for the operations team"
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e730-130a-7634-b1d1-47571ff95e91",
    • "type": "notification_channel",
    • "attributes": {
      • "format": "slack",
      • "code": "ops_team_slack",
      • "description": "Slack channel for the operations team",
      • "default_channel": false,
      • "internal": false,
      • "enabled": true,
      • "created_by": "logged_in_user",
      • "created_by_name": "logged_in_user",
      • "created_at": "2026-11-17T01:47:29.929297Z",
      • "updated_at": "2026-11-17T01:47:29.929297Z",
      • "kwargs": {
        },
      • "job_code": "direct_job"
      },
    • "relationships": {
      • "notification_job": {
        }
      },
    • "links": {
      • "self": "/api/system_configuration/notification_channels/ops_team_slack",
      • "parent": "/api/system_configuration"
      }
    }
}

Test notification channel

Sends a test notification through the channel and returns what the notification job reported.

The supplied attributes are merged over the channel's stored kwargs for this send only - nothing is saved - and supply whatever the job needs but the channel does not store, such as the to address of an email channel. The subject and body are always the test message, so subject and body attributes are ignored. Testing a channel requires permission to update it. Only email and direct message channels can be tested, and a disabled channel is rejected.

path Parameters
notification_channel_code
required
string
Example: system_email

notification channel code

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "to": "ops-team@example.com"
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e730-175b-70a4-ab23-34a111f5f63d",
    • "type": "notification_channel_test",
    • "attributes": {
      • "result": [
        ]
      }
    }
}

Show notification channel

Show a global notification channel.

path Parameters
notification_channel_code
required
string
Example: system_email

notification channel code

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e730-1aba-7c7a-8e3a-00eeb6470602",
    • "type": "notification_channel",
    • "attributes": {
      • "format": "html",
      • "code": "system_email",
      • "description": "System channel for email notifications",
      • "default_channel": true,
      • "internal": false,
      • "enabled": true,
      • "created_by": "dallas-2668",
      • "created_by_name": "dallas-2668",
      • "created_at": "2026-11-17T01:47:31.897560Z",
      • "updated_at": "2026-11-17T01:47:31.897560Z",
      • "kwargs": {
        },
      • "job_code": "email_job"
      },
    • "relationships": {
      • "notification_job": {
        }
      },
    • "links": {
      • "self": "/api/system_configuration/notification_channels/system_email",
      • "parent": "/api/system_configuration"
      }
    }
}

Update notification channel

Update a global notification channel.

path Parameters
notification_channel_code
required
string
Example: system_email

notification channel code

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "notification_job_code": "direct_job",
      • "format": "slack",
      • "default_channel": false,
      • "enabled": false,
      • "kwargs": {},
      • "description": "New channel description"
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e730-1cfb-7750-a346-d2ae0bcb21ec",
    • "type": "notification_channel",
    • "attributes": {
      • "format": "slack",
      • "code": "system_email",
      • "description": "New channel description",
      • "default_channel": false,
      • "internal": false,
      • "enabled": false,
      • "created_by": "jonie_schmeler-2670",
      • "created_by_name": "jonie_schmeler-2670",
      • "created_at": "2026-11-17T01:47:32.473841Z",
      • "updated_at": "2026-11-17T01:47:32.583006Z",
      • "kwargs": {
        },
      • "job_code": "direct_job"
      },
    • "relationships": {
      • "notification_job": {
        }
      },
    • "links": {
      • "self": "/api/system_configuration/notification_channels/system_email",
      • "parent": "/api/system_configuration"
      }
    }
}

Delete notification channel

Delete a global notification channel.

path Parameters
notification_channel_code
required
string
Example: system_email

notification channel code

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    • {
      • "status": 403,
      • "title": "You do not have permission to delete the notification channel",
      • "detail": "Your authorisation rules let you view the notification channel but not delete it."
      }
    ]
}

Notification channels

List notification channels

List notification channels for a specific project, environment or asset.

path Parameters
project_code
required
string
Example: opc

project code

query Parameters
filter[<query/sort filter>]=
string
Example: filter[<query/sort filter>]==> filter[code_eq]=slack

API filtering guide. Named filters: filter[created_by_eq], filter[created_by_in].

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e730-2c7c-7289-b6f0-270951389723",
      • "type": "notification_channel",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true,
      • "delete": true
      }
    }
}

Show a notification channel

Show a notification channel for a specific project, environment or asset..

path Parameters
project_code
required
string
Example: opc

project code

notification_channel_code
required
string
Example: system_email

notification channel code

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e730-2eda-71be-86a2-f67369d85747",
    • "type": "notification_channel",
    • "attributes": {
      • "format": "slack",
      • "code": "project_direct",
      • "description": "Project specific channel for slack notifications",
      • "default_channel": true,
      • "internal": false,
      • "enabled": true,
      • "created_by": "rashida_rippin-2692",
      • "created_by_name": "rashida_rippin-2692",
      • "created_at": "2026-11-17T01:47:37.047598Z",
      • "updated_at": "2026-11-17T01:47:37.047598Z",
      • "kwargs": {
        },
      • "job_code": "direct_job"
      },
    • "relationships": {
      • "notification_job": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/notification_channels/project_direct",
      • "parent": "/api/projects/opc"
      }
    }
}

Update notification channel

Update a notification channel for a specific project, environment or asset.

path Parameters
project_code
required
string
Example: opc

project code

notification_channel_code
required
string
Example: system_email

notification channel code

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "notification_job_code": "direct_job",
      • "format": "slack",
      • "default_channel": false,
      • "enabled": false,
      • "kwargs": {},
      • "description": "New channel description"
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e730-33c9-7e25-8c08-02e6083a2a0e",
    • "type": "notification_channel",
    • "attributes": {
      • "format": "slack",
      • "code": "project_direct",
      • "description": "New channel description",
      • "default_channel": false,
      • "internal": false,
      • "enabled": false,
      • "created_by": "arturo.sawayn-2700",
      • "created_by_name": "arturo.sawayn-2700",
      • "created_at": "2026-11-17T01:47:38.312781Z",
      • "updated_at": "2026-11-17T01:47:38.338223Z",
      • "kwargs": {
        },
      • "job_code": "direct_job"
      },
    • "relationships": {
      • "notification_job": {
        }
      },
    • "links": {
      • "self": "/api/projects/opc/notification_channels/project_direct",
      • "parent": "/api/projects/opc"
      }
    }
}

Delete notification channel

Delete a notification channel for a specific project, environment or asset..

path Parameters
project_code
required
string
Example: opc

project code

notification_channel_code
required
string
Example: system_email

notification channel code

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    • {
      • "status": 403,
      • "title": "You do not have permission to delete the notification channel",
      • "detail": "Your authorisation rules let you view the notification channel but not delete it."
      }
    ]
}

Notification jobs

List notification jobs

Lists all notification jobs.

kwargs_schema groups the keyword arguments a channel or trigger can pass to the job: required must all be given, optional may be given, and each entry of one_of needs at least one of its members, where a member that is itself a list is satisfied by any of its names.

query Parameters
filter[<query/sort filter>]=
string
Example: filter[<query/sort filter>]==> filter[code_eq]=notify_targets

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e730-3d4b-7c26-9ca4-79a3b43d0060",
      • "type": "notification_job",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true
      }
    }
}

Show notification job

Show a notification job.

kwargs_schema groups the keyword arguments a channel or trigger can pass to the job: required must all be given, optional may be given, and each entry of one_of needs at least one of its members, where a member that is itself a list is satisfied by any of its names.

path Parameters
notification_job_code
required
string
Example: email_job

notification job code

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e730-3e28-7825-9cfd-4175a4a53d07",
    • "type": "notification_job",
    • "attributes": {
      • "job_class": "Notifications::SendEmailJob",
      • "target_type": "smtp",
      • "valid_formats": [
        ],
      • "code": "email_job",
      • "description": "Send an email to the target user(s)",
      • "created_at": "2026-11-17T01:47:40.965136Z",
      • "updated_at": "2026-11-17T01:47:40.965136Z",
      • "all_kwargs": [
        ],
      • "kwargs_schema": {
        }
      },
    • "relationships": {
      • "notification_channels": {
        }
      },
    • "links": {
      • "self": "/api/notification_jobs/email_job"
      }
    }
}

Jobs

Endpoint to fetch information about the jobs processed by the OpsChain.

Get information about the jobs that are being processed by the OpsChain

Returns information about the jobs that are being processed by the OpsChain.

query Parameters
filter[<query/sort filter>]=
string
Example: filter[<query/sort filter>]==> filter[status_eq]=finished
limit
integer [ 1 .. 1000 ]
Default: 100
Example: limit=50

Limit the number of jobs returned

cursor
string
Example: cursor=2026-11-10T01:02:03.456789Z,12345

Returns the jobs after this one. Jobs are always returned newest first, so the filter cannot include sorts. Use the next_cursor value from the previous page's meta

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "257556",
      • "type": "job",
      • "attributes": {
        }
      },
    • {
      • "id": "720074",
      • "type": "job",
      • "attributes": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true
      },
    • "partial_response": false,
    • "has_any": true,
    • "total_matching_filter": 2,
    • "total_matching_filter_exact": true,
    • "next_cursor": null
    }
}

Settings

Endpoints to interact with settings.

Search settings

Lists the settings that set a setting, ordered by id, with the value each one sets.

Notes:

  • Only the settings the user is authorised to read are returned.
  • A setting is set when its value is not null. A setting whose value is an empty object is not set, but false, "" and [] are.
  • An intermediate path matches every settings that sets a setting beneath it, e.g. vault matches settings that set vault.mount_path.
  • Settings within arrays cannot be searched for - search for the array's path instead.
  • Include the owner to identify the project, environment, asset, template, template version, change or system configuration whose settings they are.
  • Use the filter[with_setting] filter on the list scheduled activities endpoint to find the scheduled activities whose settings overrides set it.
query Parameters
required
object

Use filter[with_setting] to give the dot separated path of the setting to search for.

limit
integer [ 1 .. 10000 ]
Default: 100
Example: limit=100

The maximum number of settings to return. A 206 response is returned when more settings set the setting than the limit.

include
string
Example: include=owner

Include the settings owners in the response

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e731-3175-7691-8a73-89b95b7c5039",
      • "type": "settings",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      }
    ],
  • "included": [
    • {
      • "id": "01a1e731-315c-715e-9456-7a4f3fcd77e9",
      • "type": "project",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true
      },
    • "partial_response": false
    }
}

Show settings

Shows the current settings.

path Parameters
settings_id
required
string
Example: 01a1e72a-f096-7a8b-8e2d-53d5ebc265fd

settings id

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e731-3491-7f54-957c-8481e520a688",
    • "type": "settings",
    • "attributes": {
      • "data": {
        },
      • "version": 1,
      • "created_at": "2026-11-17T01:48:44.048921Z"
      },
    • "relationships": {
      • "owner": {
        }
      },
    • "links": {
      • "self": "/api/settings/01a1e731-3491-7f54-957c-8481e520a688",
      • "current_version": "/api/settings/01a1e731-3491-7f54-957c-8481e520a688/versions/1",
      • "versions": "/api/settings/01a1e731-3491-7f54-957c-8481e520a688/versions"
      }
    }
}

Update settings

Updates a settings JSON if the included version matches the current settings version.

path Parameters
id_to_update
required
string
Example: 01a1e72a-f096-7a8b-8e2d-53d5ebc265fd

settings id

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "data": {
        },
      • "version": 1
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e731-37ff-7172-a5a4-53ae254d1654",
    • "type": "settings",
    • "attributes": {
      • "data": {
        },
      • "version": 1,
      • "created_at": "2026-11-17T01:48:44.925865Z"
      },
    • "relationships": {
      • "owner": {
        }
      },
    • "links": {
      • "self": "/api/settings/01a1e731-37ff-7172-a5a4-53ae254d1654",
      • "current_version": "/api/settings/01a1e731-37ff-7172-a5a4-53ae254d1654/versions/1",
      • "versions": "/api/settings/01a1e731-37ff-7172-a5a4-53ae254d1654/versions"
      }
    }
}

Update settings (unsafe)

Updates a settings JSON, without any version checking (always updates).

path Parameters
id_to_set
required
string
Example: 01a1e72a-f096-7a8b-8e2d-53d5ebc265fd

settings id

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "data": {
        }
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e731-3ddd-79fa-af79-6acac05e2d79",
    • "type": "settings",
    • "attributes": {
      • "data": {
        },
      • "version": 1,
      • "created_at": "2026-11-17T01:48:46.428405Z"
      },
    • "relationships": {
      • "owner": {
        }
      },
    • "links": {
      • "self": "/api/settings/01a1e731-3ddd-79fa-af79-6acac05e2d79",
      • "current_version": "/api/settings/01a1e731-3ddd-79fa-af79-6acac05e2d79/versions/1",
      • "versions": "/api/settings/01a1e731-3ddd-79fa-af79-6acac05e2d79/versions"
      }
    }
}

Settings versions

Endpoints to interact with the version history for settings.

List settings versions

Lists all versions of an OpsChain settings.

path Parameters
settings_id
required
string
Example: 01a1e72a-f096-7a8b-8e2d-53d5ebc265fd

settings id

query Parameters
limit
integer [ 1 .. 10000 ]
Default: 1000
Example: limit=50

Limit the number of settings versions returned. When more records match than the limit a 206 response is returned and meta.partial_response is true.

exclude_data
boolean
Default: false
Example: exclude_data=true

Exclude the data attribute from each of the settings versions returned. Use the show endpoint to fetch the data for an individual version.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e731-4274-7234-b7ee-685b20b02337",
      • "type": "settings_version",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true
      },
    • "partial_response": false
    }
}

Show settings version

Shows the settings values for this settings version.

path Parameters
settings_id
required
string
Example: 01a1e72a-f096-7a8b-8e2d-53d5ebc265fd

settings id

version_number
required
integer
Example: 1

version number

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e731-447a-70c1-a320-c06a82f34977",
    • "type": "settings_version",
    • "attributes": {
      • "data": {
        },
      • "version": 1,
      • "created_at": "2026-11-17T01:48:48.121227Z"
      },
    • "relationships": {
      • "settings": {
        }
      },
    • "links": {
      • "versions": "/api/settings/01a1e731-4476-74a7-b5c3-0b570c0ff4b7/versions",
      • "owner": "/api/projects/opc",
      • "self": "/api/settings/01a1e731-4476-74a7-b5c3-0b570c0ff4b7/versions/1"
      }
    }
}

Authorisation rules

Endpoints to interact with authorisation rules.

List rules

Lists all authorisation rules.

query Parameters
filter[<query/sort filter>]=
string
Example: filter[<query/sort filter>]==> filter[name]=rule_name

API filtering guide. Named filters: filter[created_by_eq], filter[created_by_in].

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e72c-6df6-7c67-af3f-a121d03c9b83",
      • "type": "authorisation_rule",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e72c-6fe4-770c-b081-dcc0b9c1848c",
      • "type": "authorisation_rule",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e72c-6ff3-7dcc-b64d-06e66eb9b6b1",
      • "type": "authorisation_rule",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e72c-7047-785e-9ebd-a8464efd4ed1",
      • "type": "authorisation_rule",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true,
      • "delete": true
      }
    }
}

Create rule

Create an authorisation rule.

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "path": "^/projects/opc/assets/prj_soa",
      • "readable": false,
      • "updatable": false,
      • "deletable": false,
      • "executable": false,
      • "name": "Deny access to Project asset"
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72c-7376-7f9c-a9f5-d0eed9af4e6b",
    • "type": "authorisation_rule",
    • "attributes": {
      • "name": "bypass",
      • "path": "^/projects/lteky/environments/ktqke",
      • "readable": false,
      • "updatable": false,
      • "deletable": false,
      • "executable": false,
      • "created_by": "logged_in_user",
      • "created_by_name": "logged_in_user",
      • "created_at": "2026-11-17T01:43:32.470044Z",
      • "updated_at": "2026-11-17T01:43:32.470044Z"
      },
    • "relationships": {
      • "authorisation_policies": {
        }
      },
    • "links": {
      • "self": "/api/authorisation_rules/01a1e72c-7376-7f9c-a9f5-d0eed9af4e6b"
      }
    }
}

Show rule

Shows an authorisation rule.

path Parameters
authorisation_rule_id
required
string
Example: 01a1e72a-fb65-7b98-8083-be35a51ab1a1

authorisation rule id

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72c-7bff-7de4-9a78-8f28e2a0123b",
    • "type": "authorisation_rule",
    • "attributes": {
      • "name": "Deny access to Project asset",
      • "path": "^/projects/opc/assets/prj_soa",
      • "readable": false,
      • "updatable": false,
      • "deletable": false,
      • "executable": false,
      • "created_by": "opschain",
      • "created_by_name": "opschain",
      • "created_at": "2026-11-17T01:43:34.654563Z",
      • "updated_at": "2026-11-17T01:43:34.654563Z"
      },
    • "relationships": {
      • "authorisation_policies": {
        }
      },
    • "links": {
      • "self": "/api/authorisation_rules/01a1e72c-7bff-7de4-9a78-8f28e2a0123b"
      }
    }
}

Update authorisation rule

Update an authorisation rule.

path Parameters
authorisation_rule_id
required
string
Example: 01a1e72a-fb65-7b98-8083-be35a51ab1a1

authorisation rule id

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "path": "/projects/demo/environments/dev",
      • "readable": false,
      • "updatable": false,
      • "deletable": false,
      • "executable": false,
      • "name": "Deny all on dev environment"
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72c-87e4-7373-b4a3-593945bc0f81",
    • "type": "authorisation_rule",
    • "attributes": {
      • "name": "Deny all on dev environment",
      • "path": "^/projects/demo/environments/dev",
      • "readable": false,
      • "updatable": false,
      • "deletable": false,
      • "executable": false,
      • "created_by": "logged_in_user",
      • "created_by_name": "logged_in_user",
      • "created_at": "2026-11-17T01:43:37.698912Z",
      • "updated_at": "2026-11-17T01:43:37.950479Z"
      },
    • "relationships": {
      • "authorisation_policies": {
        }
      },
    • "links": {
      • "self": "/api/authorisation_rules/01a1e72c-87e4-7373-b4a3-593945bc0f81"
      }
    }
}

Delete rule

Delete an authorisation rule.

path Parameters
authorisation_rule_id
required
string
Example: 01a1e72a-fb65-7b98-8083-be35a51ab1a1

authorisation rule id

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    • {
      • "status": 403,
      • "title": "You do not have permission to delete the authorisation rule",
      • "detail": "Your authorisation rules let you view the authorisation rule but not delete it."
      }
    ]
}

Authorisation policies

Endpoints to interact with authorisation policies.

List policies

Lists all authorisation policies.

query Parameters
filter[<query/sort filter>]=
string
Example: filter[<query/sort filter>]==> filter[name_eq]=secure

API filtering guide. Named filters: filter[created_by_eq], filter[created_by_in].

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e72c-2c9c-78b7-9f68-0a40b2e37cdf",
      • "type": "authorisation_policy",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e72c-312b-7d44-baad-246e77f25e12",
      • "type": "authorisation_policy",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true,
      • "delete": true
      }
    }
}

Create policy

Create an authorisation policy with a list of authorisation rules.

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
Example
{
  • "data": {
    • "attributes": {
      • "name": "sana",
      • "description": "Sed et hic dolor.",
      • "authorisation_rules": [
        ]
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72c-3827-79d6-85a3-5889b047d476",
    • "type": "authorisation_policy",
    • "attributes": {
      • "name": "rupert_wisozk",
      • "description": "Hic voluptatem autem sequi.",
      • "system": false,
      • "created_by": "logged_in_user",
      • "created_by_name": "logged_in_user",
      • "created_at": "2026-11-17T01:43:17.286530Z",
      • "updated_at": "2026-11-17T01:43:17.286530Z"
      },
    • "relationships": {
      • "policy_rules": {
        },
      • "policy_assignments": {
        },
      • "authorisation_rules": {
        }
      },
    • "links": {
      • "self": "/api/authorisation_policies/01a1e72c-3827-79d6-85a3-5889b047d476",
      • "policy_rules": "/api/authorisation_policies/01a1e72c-3827-79d6-85a3-5889b047d476/rules",
      • "policy_assignments": "/api/authorisation_policies/01a1e72c-3827-79d6-85a3-5889b047d476/assignments"
      }
    }
}

Show policy

Shows an authorisation policy.

path Parameters
authorisation_policy_id
required
string
Example: 01a1e72a-fbb2-71fd-9ca1-41726d0f81a6

authorisation policy id

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72c-4d82-79ea-9746-d0c7ae9170a7",
    • "type": "authorisation_policy",
    • "attributes": {
      • "name": "New users policy",
      • "description": "Access for all incoming users",
      • "system": false,
      • "created_by": "mayme-767",
      • "created_by_name": "mayme-767",
      • "created_at": "2026-11-17T01:43:22.753699Z",
      • "updated_at": "2026-11-17T01:43:22.753699Z"
      },
    • "relationships": {
      • "policy_rules": {
        },
      • "policy_assignments": {
        },
      • "authorisation_rules": {
        }
      },
    • "links": {
      • "self": "/api/authorisation_policies/01a1e72c-4d82-79ea-9746-d0c7ae9170a7",
      • "policy_rules": "/api/authorisation_policies/01a1e72c-4d82-79ea-9746-d0c7ae9170a7/rules",
      • "policy_assignments": "/api/authorisation_policies/01a1e72c-4d82-79ea-9746-d0c7ae9170a7/assignments"
      }
    }
}

Update authorisation policy and its rules

Update an authorisation policy and its authorisation rules. If no authorisation rules are provided, all associated rules will be removed from the policy.

path Parameters
authorisation_policy_id
required
string
Example: 01a1e72a-fbb2-71fd-9ca1-41726d0f81a6

authorisation policy id

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
Example
{
  • "data": {
    • "attributes": {
      • "name": "jenelle",
      • "description": "Voluptatem et rerum dignissimos.",
      • "authorisation_rules": [
        ]
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72c-542e-7e50-9f8a-1956c23e4968",
    • "type": "authorisation_policy",
    • "attributes": {
      • "name": "Updated policy name",
      • "description": "Access for all incoming users",
      • "system": false,
      • "created_by": "jennifer_osinski-795",
      • "created_by_name": "jennifer_osinski-795",
      • "created_at": "2026-11-17T01:43:24.462021Z",
      • "updated_at": "2026-11-17T01:43:24.570547Z"
      },
    • "relationships": {
      • "policy_rules": {
        },
      • "policy_assignments": {
        },
      • "authorisation_rules": {
        }
      },
    • "links": {
      • "self": "/api/authorisation_policies/01a1e72c-542e-7e50-9f8a-1956c23e4968",
      • "policy_rules": "/api/authorisation_policies/01a1e72c-542e-7e50-9f8a-1956c23e4968/rules",
      • "policy_assignments": "/api/authorisation_policies/01a1e72c-542e-7e50-9f8a-1956c23e4968/assignments"
      }
    }
}

Delete policy

Delete an authorisation policy.

path Parameters
authorisation_policy_id
required
string
Example: 01a1e72a-fbb2-71fd-9ca1-41726d0f81a6

authorisation policy id

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    • {
      • "status": 403,
      • "title": "You do not have permission to delete the authorisation policy",
      • "detail": "Your authorisation rules let you view the authorisation policy but not delete it."
      }
    ]
}

Authorisation policy assignments

Endpoints to interact with authorisation policy assignments.

List policy assignments

Lists all policy assignments for a specific authorisation policy.

path Parameters
authorisation_policy_id
required
string
Example: 01a1e72a-fbb2-71fd-9ca1-41726d0f81a6

authorisation policy id

query Parameters
filter[<query/sort filter>]=
string
Example: filter[<query/sort filter>]==> filter[username_eq]=opschain

API filtering guide. Named filters: filter[created_by_eq], filter[created_by_in].

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e730-5948-7f13-92e9-f0023c030df3",
      • "type": "policy_assignment",
      • "attributes": {
        },
      • "links": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true,
      • "delete": true
      }
    }
}

Assign a policy to users or groups

Assign an authorisation policy to one or more users and/or groups.

path Parameters
authorisation_policy_id
required
string
Example: 01a1e72a-fbb2-71fd-9ca1-41726d0f81a6

authorisation policy id

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
Example
{
  • "data": {
    • "attributes": {
      • "user_id": null,
      • "assignments": [
        ]
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e730-5cc5-7779-891a-7c1e0a9537dc",
      • "type": "policy_assignment",
      • "attributes": {
        },
      • "links": {
        }
      }
    ]
}

Show assignment

Show a policy assignment for a specific authorisation policy.

path Parameters
authorisation_policy_id
required
string
Example: 01a1e72a-fbb2-71fd-9ca1-41726d0f81a6

authorisation policy id

policy_assignment_id
required
string
Example: 01a1e72a-fc04-7d46-8436-72fc3db07170

policy assignment id

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e730-67fa-7c6b-8aab-1a92455527e1",
    • "type": "policy_assignment",
    • "attributes": {
      • "username": "opschain",
      • "display_name": "opschain",
      • "auth_provider": "local",
      • "groupname": "ldap-group",
      • "created_by": "maria_armstrong-2868",
      • "created_by_name": "maria_armstrong-2868",
      • "created_at": "2026-11-17T01:47:51.673875Z",
      • "updated_at": "2026-11-17T01:47:51.673875Z"
      },
    • "links": {
      • "self": "/api/authorisation_policies/01a1e730-67e4-72fb-81d3-4fa97c2433e7/assignments/01a1e730-67fa-7c6b-8aab-1a92455527e1"
      }
    }
}

Authorisation policy rules

Endpoints to interact with authorisation policy rules.

List policy rules

Lists all policy rules for a specific authorisation policy.

path Parameters
authorisation_policy_id
required
string
Example: 01a1e72a-fbb2-71fd-9ca1-41726d0f81a6

authorisation policy id

query Parameters
filter[<query/sort filter>]=
string
Example: filter[<query/sort filter>]==> filter[username_eq]=opschain

API filtering guide. Named filters: filter[created_by_eq], filter[created_by_in].

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e730-6e55-76aa-838f-0bcf76b7de36",
      • "type": "policy_rule",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e730-6e64-77d4-8afc-fce2a3ae6482",
      • "type": "policy_rule",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true,
      • "delete": true
      }
    }
}

Create policy rule(s)

Add one or more authorisation rules to a specific authorisation policy.

path Parameters
authorisation_policy_id
required
string
Example: 01a1e72a-fbb2-71fd-9ca1-41726d0f81a6

authorisation policy id

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
Example
{
  • "data": {
    • "attributes": {
      • "authorisation_rule_id": "01a1e72a-fb65-7b98-8083-be35a51ab1a1"
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e730-7572-7edd-8070-8ae3626499ba",
      • "type": "policy_rule",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      }
    ]
}

Delete a policy rule

Remove an authorisation rule from a specific authorisation policy.

path Parameters
authorisation_policy_id
required
string
Example: 01a1e72a-fbb2-71fd-9ca1-41726d0f81a6

authorisation policy id

policy_rule_id
required
string
Example: 01a1e72a-fbd3-7d97-8abe-02d12808c0cd

policy rule id

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    • {
      • "status": 403,
      • "title": "You do not have permission to update the authorisation policy",
      • "detail": "Your authorisation rules let you view the authorisation policy but not update it."
      }
    ]
}

Tokens

List tokens

List all authorisation tokens.

query Parameters
filter[<query/sort filter>]=
string
Example: filter[<query/sort filter>]==> filter[description_cont]=automation

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e72c-1ab6-7bbd-9bf3-b4309cc5f146",
      • "type": "authentication_token",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      },
    • {
      • "id": "01a1e72c-1a4e-7822-8a4f-c9ea20db186f",
      • "type": "authentication_token",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true
      }
    }
}

Create access token

Creates an access token for the current user.

Notes:

  • When the token.enable_cookies setting is true (default) a new refresh_token cookie is set in the response and the supplied refresh token is rotated (destroyed and replaced). The response body contains only the access token.
  • When the token.enable_cookies setting is false and the refresh token is supplied to authenticate the request a new refresh token is included in the response meta and the supplied refresh token is rotated (destroyed and replaced). The new refresh token JWT is available in data.meta.refresh_token.
  • When an LDAP user of the bundled secret vault signs in with their password, OpsChain also obtains a secret vault token for them, giving the session secret vault access, and renews it each time the access token is refreshed. If the vault token cannot be obtained or renewed the access token is still created, and the reason is returned in meta.warnings.secret_vault_session.
  • If the vault refuses to renew the token - because the user's secret vault policies changed, or the user was blocked - OpsChain discards it, and the refresh response's meta.warnings.secret_vault_session is "Your secret vault session has ended - sign in again with your password to restore secret vault access".
Authorizations:
cookieAuthbearerAuthbasicAuthNone
Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "username": "username",
      • "password": "password"
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72c-1c63-7cc9-94d8-d9f30647494c",
    • "type": "authentication_token",
    • "attributes": {
      • "type": "AccessToken",
      • "expires_at": "2026-11-17T05:43:10.000000Z",
      • "created_at": "2026-11-17T01:43:10.030259Z",
      • "updated_at": "2026-11-17T01:43:10.030259Z"
      },
    • "relationships": {
      • "owner": {
        }
      },
    • "links": {
      • "self": "/api/tokens/01a1e72c-1c63-7cc9-94d8-d9f30647494c"
      },
    • "meta": {
      • "bearer_token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIwMWExZTcyYy0xYzYzLTdjYzktOTRkOC1kOWYzMDY0NzQ5NGMiLCJpc3MiOiJPcHNDaGFpbiIsImF1ZCI6Im9wc2NoYWluX2FwaSIsImV4cCI6MTc5NDg5NDE5MCwiaWF0IjoxNzk0ODc5NzkwfQ.oQFQs35KVs9mZ4Rj1ih9DdM3bLigkdDD6Qw-ObaLzD0"
      }
    }
}

Create API key token

Creates an API key token for the current user.

Notes:

  • LDAP or local login credentials, or an access token are required to use this endpoint.
  • An API key generated without a password does not have secret vault access: it cannot decrypt or store secret vault values through the API. To give an API key secret vault access, supply your password when creating it - with basic auth, in the request body, or in the request body alongside an access token. An incorrect password supplied with an access token is rejected with a 401 response.
  • An API key created with your password uses your registered secret vault credentials (see /api/user_system_credentials), resolved afresh on every request, so registering, replacing or deleting a credential changes the key's access at once. Its registered_vault_credentials attribute is true. API keys created before this attribute existed must be recreated with your password to gain it.
  • For an LDAP user of the bundled secret vault, the password also obtains the API key its own bundled secret vault token. The secret_vault_access attribute shows whether the key holds one. The key keeps it for as long as the key is valid, and loses it if the owner's secret vault policies change or the owner is blocked - create a new API key with the password to restore it.
  • If the secret vault token cannot be obtained the API key is still created, without the token, and the reason is returned in meta.warnings.secret_vault_session. If the key also has no registered secret vault credential to use, meta.warnings.secret_vault_credential says so.
Authorizations:
bearerAuthbasicAuth
header Parameters
Authorization
string

an access token, as Bearer <token>, when not signing in with basic auth or the request body

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "username": "username",
      • "password": "password",
      • "description": "CI token for API access",
      • "expiry_date": "2027-05-17T01:41:56.153923Z"
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72c-1e59-750b-97a2-a49f224ac0ec",
    • "type": "authentication_token",
    • "attributes": {
      • "type": "ApiKeyToken",
      • "description": "Dolor et fugiat voluptatum.",
      • "registered_vault_credentials": true,
      • "secret_vault_access": false,
      • "expires_at": "2026-12-01T23:59:59.999999Z",
      • "created_at": "2026-11-17T01:43:10.680254Z",
      • "updated_at": "2026-11-17T01:43:10.680254Z"
      },
    • "relationships": {
      • "owner": {
        }
      },
    • "links": {
      • "self": "/api/tokens/01a1e72c-1e59-750b-97a2-a49f224ac0ec"
      },
    • "meta": {
      • "bearer_token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIwMWExZTcyYy0xZTU5LTc1MGItOTdhMi1hNDlmMjI0YWMwZWMiLCJpc3MiOiJPcHNDaGFpbiIsImF1ZCI6Im9wc2NoYWluX2FwaSIsImV4cCI6MTc5NjE2OTU5OSwiaWF0IjoxNzk0ODc5NzkwfQ.ZslVQ8W3zWPgldzz-9CxWMxQfn-bWxLIIs0HMVe8B6Y"
      }
    },
  • "meta": {
    • "warnings": {
      • "secret_vault_credential": "This API key uses your registered secret vault credentials, but you have none registered - register one using /api/user_system_credentials to give it secret vault access"
      }
    }
}

Create download token

Returns a URL that downloads the supplied API URL without an Authorization header, for use as a browser link.

Notes:

  • The url must be a relative API URL that includes the download query parameter.
  • The returned URL appends a download_token query parameter that is valid for 60 seconds, for that exact URL and only for as long as the access token used to create it remains valid.
  • Only a request authenticated with an access token can create a download token.
Authorizations:
bearerAuth
header Parameters
Authorization
required
string

access token bearer authorisation

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "url": "/api/activities?download=activities.csv"
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "meta": {
    • "download_url": "/api/activities?download=activities.csv&download_token=eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW5faWQiOiIwMWExZTcyYy0yMTIwLTc3MzItYjM5Mi0zNDUxODExZWU1MTMiLCJhdWQiOiJvcHNjaGFpbl9kb3dubG9hZCIsImV4cCI6MTc5NDg3OTg1MSwiaWF0IjoxNzk0ODc5NzkxLCJyZXEiOiI0NDkxY2EwZjFiMjZkMzBmZjIxZWIzYmYzYzQ0ZGFhNzE0N2NmNWFhYmJjYzg1MzJhNDE3YWU1N2Q5MjU0YzNiIn0.h4D-1z5-Tm3DRpZ1oyREivcuVvIvNYFIMNFQ-_Ib6Rc"
    }
}

Show token

Show an authorisation token.

path Parameters
token_id
required
string
Example: 01a1e72a-fb38-7267-84a4-cd7daeb9c791

authorisation token id

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72c-26ee-7e6c-b515-2b4b4ce2f120",
    • "type": "authentication_token",
    • "attributes": {
      • "type": "ApiKeyToken",
      • "description": "CI token for API access",
      • "registered_vault_credentials": false,
      • "secret_vault_access": false,
      • "expires_at": "2027-05-17T01:43:12.870857Z",
      • "created_at": "2026-11-17T01:43:12.876158Z",
      • "updated_at": "2026-11-17T01:43:12.876158Z"
      },
    • "relationships": {
      • "owner": {
        }
      },
    • "links": {
      • "self": "/api/tokens/01a1e72c-26ee-7e6c-b515-2b4b4ce2f120"
      }
    }
}

Delete token

Delete an authorisation token if it exists.

path Parameters
token_id
required
string
Example: 01a1e72a-fb38-7267-84a4-cd7daeb9c791

authorisation token id

Responses

Show access token

Shows the access token used to authenticate the request. When the request authenticates with a username and password instead of a token, returns an array of all the current user's access tokens.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e72c-2aed-7346-b578-d3a4b4153b42",
      • "type": "authentication_token",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      }
    ]
}

Delete access token

Deletes the access token used to authenticate the request and revokes the user's secret vault session token. When the request authenticates with a username and password instead, deletes all of the user's access tokens.

Responses

Users

Endpoints to interact with the users in the system.

List users

Lists users in the system

query Parameters
filter[<query/sort filter>]=
string
Example: filter[<query/sort filter>]==> filter[username_eq]=opschain

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e732-79d8-75d4-817c-38fe678c32bf",
      • "type": "user",
      • "attributes": {
        },
      • "meta": { },
      • "links": {
        }
      }
    ]
}

Show user

Show a user.

path Parameters
user_id
required
string
Example: 01a1e72a-ed50-7440-a463-7b36d183d36e

user id

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e732-7cf1-7b7e-a12e-21c807eed973",
    • "type": "user",
    • "attributes": {
      • "username": "logged_in_user",
      • "groupnames": [
        ],
      • "auth_provider": "ldap",
      • "email_address": "logged_in_user@limepoint.com",
      • "display_name": null,
      • "first_name": null,
      • "last_name": null,
      • "default_notification_methods": [
        ],
      • "direct_message_ids": {
        },
      • "created_at": "2026-11-17T01:50:08.109015Z",
      • "updated_at": "2026-11-17T01:50:08.109015Z",
      • "disabled_at": null
      },
    • "meta": {
      • "superuser": true
      },
    • "links": {
      • "self": "/api/users/01a1e732-7cf1-7b7e-a12e-21c807eed973"
      }
    }
}

Update user

Update a user's notification preferences, and a local user's names.

path Parameters
user_id
required
string
Example: 01a1e72a-ed50-7440-a463-7b36d183d36e

user id

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "email_address": "user@limepoint.com",
      • "display_name": "Jane Citizen",
      • "first_name": "Jane",
      • "last_name": "Citizen",
      • "default_notification_methods": [
        ],
      • "direct_message_ids": {
        }
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e732-85f1-7341-baf9-ae7d87591c15",
    • "type": "user",
    • "attributes": {
      • "username": "logged_in_user",
      • "groupnames": [
        ],
      • "auth_provider": "ldap",
      • "email_address": "logged_in_user@limepoint.com",
      • "display_name": null,
      • "first_name": null,
      • "last_name": null,
      • "default_notification_methods": [
        ],
      • "direct_message_ids": {
        },
      • "created_at": "2026-11-17T01:50:10.415083Z",
      • "updated_at": "2026-11-17T01:50:10.587058Z",
      • "disabled_at": null
      },
    • "meta": { },
    • "links": {
      • "self": "/api/users/01a1e732-85f1-7341-baf9-ae7d87591c15"
      }
    }
}

Show current user

Show the currently logged in user.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e732-8c67-719d-bbbb-04834979439d",
    • "type": "user",
    • "attributes": {
      • "username": "logged_in_user",
      • "groupnames": [
        ],
      • "auth_provider": "ldap",
      • "email_address": "logged_in_user@limepoint.com",
      • "display_name": null,
      • "first_name": null,
      • "last_name": null,
      • "default_notification_methods": [
        ],
      • "direct_message_ids": {
        },
      • "created_at": "2026-11-17T01:50:12.069773Z",
      • "updated_at": "2026-11-17T01:50:12.069773Z",
      • "disabled_at": null
      },
    • "meta": {
      • "superuser": true
      },
    • "links": {
      • "self": "/api/users/01a1e732-8c67-719d-bbbb-04834979439d"
      }
    }
}

User system credentials

Endpoints to manage your own credentials for external systems such as the secret vault. OpsChain uses them to act as you, instead of with the system-wide credentials, when you store a value in the secret vault or retrieve one outside a change. A credential applies to the node path it is registered against and every node below it. Credential values are never returned, and only their owner can see or change them.

Create user system credential

Register one of your own tokens for an external system. For the secret vault, log in to the vault yourself and create a token there under the policies your vault administrators gave you; OpsChain never sees your password. external_vault_code names the vault the token is for - bundled (the default) for the secret vault bundled with OpsChain, or the code of a registered external vault (see /api/external_vaults). A credential is used wherever the settings assign its vault, whatever the mount path. You may hold one credential per system per vault. OpsChain checks the token with that vault before storing it, and rejects a token the vault does not accept.

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "target_system": "secret_vault",
      • "external_vault_code": "team_vault",
      • "token": "hvs.CAESIJ"
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e732-906c-7065-afc1-14b8bc3d29a8",
    • "type": "user_system_credential",
    • "attributes": {
      • "target_system": "secret_vault",
      • "vault": {
        },
      • "managed": false,
      • "created_at": "2026-11-17T01:50:13.093793Z",
      • "updated_at": "2026-11-17T01:50:13.093793Z"
      },
    • "links": {
      • "self": "/api/user_system_credentials/01a1e732-906c-7065-afc1-14b8bc3d29a8"
      }
    }
}

List user system credentials

Lists your own system credentials. Tokens are never returned.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e732-9625-7a8d-95f5-fe16844ab3a2",
      • "type": "user_system_credential",
      • "attributes": {
        },
      • "links": {
        }
      }
    ]
}

Show user system credential

Show one of your own system credentials.

path Parameters
credential_id
required
string

user system credential id

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e732-96c7-7748-82d5-bc2397ce3dbb",
    • "type": "user_system_credential",
    • "attributes": {
      • "target_system": "secret_vault",
      • "vault": {
        },
      • "managed": false,
      • "created_at": "2026-11-17T01:50:14.726397Z",
      • "updated_at": "2026-11-17T01:50:14.726397Z"
      },
    • "links": {
      • "self": "/api/user_system_credentials/01a1e732-96c7-7748-82d5-bc2397ce3dbb"
      }
    }
}

Update user system credential

Replace the token of one of your own system credentials. A managed credential - the secret vault token OpsChain keeps for your session - cannot be updated, and is reported as not found. A new token is checked with the secret vault before it is stored.

path Parameters
credential_id
required
string

user system credential id

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "token": "hvs.CAESIJ"
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e732-9881-77d1-9a0d-fe3538ab5c64",
    • "type": "user_system_credential",
    • "attributes": {
      • "target_system": "secret_vault",
      • "vault": {
        },
      • "managed": false,
      • "created_at": "2026-11-17T01:50:15.168249Z",
      • "updated_at": "2026-11-17T01:50:15.329355Z"
      },
    • "links": {
      • "self": "/api/user_system_credentials/01a1e732-9881-77d1-9a0d-fe3538ab5c64"
      }
    }
}

Delete user system credential

Delete one of your own system credentials. A managed credential - the secret vault token OpsChain keeps for your session - cannot be deleted, and is reported as not found; sign out to revoke it.

path Parameters
credential_id
required
string

user system credential id

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    • {
      • "status": 404,
      • "title": "Record not found",
      • "meta": {
        }
      }
    ]
}

User notifications

Endpoints to interact with a users notification settings.

List notifications

Lists notifications the user has configured for a specific project, environment or asset (that do not reference a specific action or workflow).

path Parameters
project_code
required
string
Example: opc

project code

asset_code
required
string
Example: prj_soa

asset code

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e730-4034-7d57-b99f-6ca36495a41f",
      • "type": "change_notifications",
      • "attributes": {
        }
      },
    • {
      • "id": "01a1e730-4034-7d57-b99f-6ca36495a41f",
      • "type": "settings_notifications",
      • "attributes": {
        }
      },
    • {
      • "id": "01a1e730-4034-7d57-b99f-6ca36495a41f",
      • "type": "properties_notifications",
      • "attributes": {
        }
      }
    ]
}

List change notifications

Lists all change specific notifications the user has configured for a specific project, environment or asset.

path Parameters
project_code
required
string
Example: opc

project code

asset_code
required
string
Example: prj_soa

asset code

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e730-47a0-7c56-b4ee-3dd4935ad63b",
    • "type": "action_notifications",
    • "attributes": {
      • "custom_proj_action": {
        },
      • "proj_action_1": {
        },
      • "proj_action_2": {
        },
      • "provision": {
        }
      }
    }
}

List workflow notifications

Lists the events the user is notified of for each of the project's workflows, keyed by workflow code.

Workflow notifications belong to the project. An environment or asset path returns an empty set and cannot be updated.

path Parameters
project_code
required
string
Example: opc

project code

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e730-4bb4-7e33-9676-45f9488dfbd3",
    • "type": "workflow_run_notifications",
    • "attributes": {
      • "assets": [ ],
      • "custom_workflow": [
        ],
      • "workflow_2": [
        ]
      }
    }
}

List all user notifications

Lists every notification the user has configured, across every node, keyed by node path.

A user may only list their own notifications - the id in the path must be the authenticated user's own.

path Parameters
user_id
required
string
Example: 01a1e72a-ed50-7440-a463-7b36d183d36e

user id

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e730-4f62-7217-9716-c89a5c7f31a2",
    • "type": "all_user_notifications",
    • "attributes": {
      • "/projects/opc/assets/prj_soa": {
        },
      • "/projects/opc/environments/dev/assets/env_soa": {
        },
      • "/projects/opc": {
        }
      }
    }
}

Groups

Endpoints to interact with the user LDAP groups.

Secrets

Endpoints to interact with secrets from the vault or decrypting AES encrypted strings.

List the secret vaults to choose from

Lists the secret vaults a setting can assign through vault.code, and that a user can register a credential for: the bundled secret vault first, then every external vault in name order. Only the code and name of each vault are returned.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "bundled",
      • "type": "external_vault_picker",
      • "attributes": {
        }
      },
    • {
      • "id": "team_vault",
      • "type": "external_vault_picker",
      • "attributes": {
        }
      }
    ]
}

Resolve secrets

Returns the decrypted values of the supplied secrets

Notes:

  • Each value that cannot be resolved is left out of results and reported instead as an error whose meta.source is the value as supplied. If some values resolve the response is a partial content (206) response containing both the data and the errors; if none resolve it is an unprocessable content (422) response containing only the errors.
  • A value that needs a secret vault credential you have not registered is reported as an error whose meta.secret_vault_credential_required lists the vault it needs one for. In a partial content response the same list is also returned in meta.secret_vault_credential_required.
  • Resolving secrets without permission to resolve them fails with a single unprocessable content error.
Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "owner_type": "settings",
      • "owner_id": "01a1e72a-f81a-78b4-be41-e2dfc1c97d81",
      • "source": "settings",
      • "mintmodel_owner_path": "/projects/opc/assets/prj_soa",
      • "converge_date": "2026-11-17T01:42:03.286711Z",
      • "values_to_decrypt": [
        ],
      • "key_paths": [
        ]
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "secrets",
    • "type": "secrets",
    • "attributes": {
      • "results": [
        ]
      }
    }
}

Resolve a global secret

Returns the decrypted value of a secret resolved directly from the secret vault

Notes:

  • A secret that cannot be resolved, or whose stored value does not match expected_vault_value, fails with an unprocessable content error.
  • A secret that needs a secret vault credential you have not registered fails with an unprocessable content error whose meta.secret_vault_credential_required lists the vault it needs one for.
Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "vault_owner_id": "01a1e72a-f7f1-7858-95ce-493be7ec5234",
      • "vault_path": "secret-vault://path/to/vault/vault_key",
      • "expected_vault_value": "{AES2}TdxBDw3KtDj+FKKckKeF5A=={/IV}Ud/ubLWIwhpCwkgBa6DSd5A=="
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "secrets",
    • "type": "secrets",
    • "attributes": {
      • "results": [
        ]
      }
    }
}

Encrypt a value

Returns the OpsChain-encrypted form of the supplied value

Notes:

  • Encrypting a value without updatable permission on /secrets fails with an unprocessable content error.
Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "value_to_encrypt": "the value to encrypt"
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "secrets",
    • "type": "secrets",
    • "attributes": {
      • "results": [
        ]
      }
    }
}

Store a secret

Creates a secret value in the secret vault at the supplied path

Notes:

  • The vault_path must start with secret-vault:// and include a path and a key, otherwise the request fails with an unprocessable content error.
  • Storing a secret without updatable permission on the owning node's secrets path (or /secrets) fails with an unprocessable content error. A template or template version is authorised as its project.
  • Storing a secret in a vault you have not registered a secret vault credential for fails with an unprocessable content error, whose meta.secret_vault_credential_required lists the vault it needs one for.
Request Body schema: application/vnd.api+json
required
object
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "vault_owner_id": "01a1e72a-f7f1-7858-95ce-493be7ec5234",
      • "vault_owner_type": "node",
      • "vault_path": "secret-vault://path/to/vault/vault_key",
      • "vault_value": "the value to store"
      }
    },
  • "meta": {
    • "replace_secret": false
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "secrets",
    • "type": "secrets",
    • "attributes": {
      • "results": [
        ]
      }
    }
}

Store a secret file

Uploads a file and stores its contents in the secret vault at the supplied path

Notes:

  • The vault_path must start with secret-vault:// and include a path and a key, otherwise the request fails with an unprocessable content error.
  • Storing a secret without updatable permission on the owning node's secrets path (or /secrets) fails with an unprocessable content error. A template or template version is authorised as its project.
  • Storing a secret in a vault you have not registered a secret vault credential for fails with an unprocessable content error, whose meta.secret_vault_credential_required lists the vault it needs one for.
Request Body schema: multipart/form-data
vault_owner_id
string (Node, template or template version whose vault configuration is used to store the secret)
vault_owner_type
string (default: node)
Enum: "node" "template" "template_version"

Whether the vault_owner_id identifies a node, a template or a template version

vault_path
string
replace_secret
string (Replace the secret vault value if it exists (default: false))
file
string <binary>

The file whose contents are stored in the secret vault (binary content is base64 encoded automatically). The filename is ignored.

Responses

Request samples

Content type
multipart/form-data
------------XnJLe9ZIbbGUYtzPQJ16u1
content-disposition: form-data; name="vault_owner_id"

01a1e731-2e9a-7624-9932-54780803698c
------------XnJLe9ZIbbGUYtzPQJ16u1
content-disposition: form-data; name="vault_path"

secret-vault://path/to/vault/vault_key
------------XnJLe9ZIbbGUYtzPQJ16u1
content-disposition: form-data; name="file"; filename="sample.txt"
content-type: text/plain
content-length: 21

Sample file property

------------XnJLe9ZIbbGUYtzPQJ16u1--

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "secrets",
    • "type": "secrets",
    • "attributes": {
      • "results": [
        ]
      }
    }
}

Info

Get version and other information about the running OpsChain instance.

Get OpsChain server info

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "0",
    • "type": "info",
    • "attributes": {
      • "cluster_name": "opschain-db",
      • "version": "edge",
      • "runner_image": "limepoint/opschain-runner-enterprise:edge",
      • "db_version": "17.2",
      • "api_version": "7.1.5.1",
      • "ldap_available?": true,
      • "banners": [ ],
      • "instance_info": { },
      • "licence_info": {
        },
      • "maintenance_mode": false,
      • "maintenance_mode_exempts_superusers": false
      },
    • "links": {
      • "self": "/api/info"
      },
    • "meta": {
      • "authorisations": {
        },
      • "secret_vault": {
        },
      • "service_credential_settings_paths": [
        ]
      }
    }
}

Get whether maintenance mode is active

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "0",
    • "type": "maintenance_mode_status",
    • "attributes": {
      • "active": false,
      • "exempts_superusers": false,
      • "resuming_until": null
      },
    • "links": {
      • "self": "/api/maintenance_mode"
      }
    }
}

Trust store

Endpoint to manage the trust store and certificates.

List certificates

Lists certificates in the trust store.

query Parameters
filter[<query/sort filter>]=
string
Example: filter[<query/sort filter>]==> filter[filename_cont]=root

API filtering guide. Named filters: filter[created_by_eq], filter[created_by_in].

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "ca_self.pem",
      • "type": "certificate",
      • "attributes": {
        },
      • "links": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true,
      • "delete": true
      }
    }
}

Create certificate

Creates a certificate in the trust store.

Request Body schema: multipart/form-data
description
string or null
file
string <binary>

certificate file, the uploaded file's filename is used to name the new certificate

Responses

Request samples

Content type
multipart/form-data
------------XnJLe9ZIbbGUYtzPQJ16u1
content-disposition: form-data; name="description"

New certificate description
------------XnJLe9ZIbbGUYtzPQJ16u1
content-disposition: form-data; name="file"; filename="remote_system.crt"
content-type: application/x-x509-ca-cert
content-length: 1887

-----BEGIN CERTIFICATE-----
MIIFQzCCAyugAwIBAgIUeNS0f9lqaJhC2apc91FbPRBVPNwwDQYJKoZIhvcNAQEL
BQAwMTEQMA4GA1UEAwwHUm9vdCBDQTEdMBsGA1UECgwUTGltZVBvaW50RW5naW5l
ZXJpbmcwHhcNMjUwNDI5MDA0NzAxWhcNMzAwNDI5MDA0NzAxWjAxMRAwDgYDVQQD
DAdSb290IENBMR0wGwYDVQQKDBRMaW1lUG9pbnRFbmdpbmVlcmluZzCCAiIwDQYJ
KoZIhvcNAQEBBQADggIPADCCAgoCggIBAJoUxJkyK3VKbBhVwQPRmA9MqUOocn16
SOZm5KVPVyR2F9OZ4xIyZTkUalUFGrguoDAyvKAI+AgGRhNJG+kKQ7PLAAEbSWBE
gdXNNtSAj4Yvo0Bw3XbxqZM7kBO7GfysKMjqKsEeR0wiwshAQPsBjAYa78ayDRC5
RqN1jR9al65UdLcE5yDbbpMd7GwR3b9ythahsox8PfHL60sZf7NfI4q+SkgbOVzt
dxppCZqwZRuMVWdvvQk069UkOYoRXniQEIFU6Ugd8FWIIzleHyKEodTsRhhXUjBS
GbA3v+x66mS87r6bE6ffFwLO0reFgfx4a7dMmhd5djrOfZtZ0L8zizXwsyee5j6v
iNokciyLHgRfWYHsYZ3OgHC8p7i02Xd9vcCsaPuoGopo0G/+wog289ObTqGbxu28
X8Bk5/kIVkn79LDA4zWz7VwYY0uoK0TxWpdMg2yuvE5nH94qGlnJisopxVhrZ7qH
E+QEqUYhelJNCi62Z8gmT0z3d7lmsq9gH23o1Zngdhnygdrm3rh404bjK/xFL6Hf
0YmiYhQw8ydHKGWY8rfhjL8eXl1gURZTqLTZC6J3sF3SAS1hj2nrePsPGt7S1OqI
djd/vGLSLz/SGyE9d5sOeTvza9pmKKXKqcvPFbwgF496dZmAu6xtVC+6pa8hOXJW
YlC0xn/xXnTFAgMBAAGjUzBRMB0GA1UdDgQWBBRdN8nNGCxpxe0zHXz3BrrtlYvV
LjAfBgNVHSMEGDAWgBRdN8nNGCxpxe0zHXz3BrrtlYvVLjAPBgNVHRMBAf8EBTAD
AQH/MA0GCSqGSIb3DQEBCwUAA4ICAQB6jtlLzWd6yjbye2SsB04ns6B6WskdOAkk
pjGz7MyARCEvgfHh5HtMzBi9l5mxXjMfYuQx3ag75lTSaA/OUgGCQOQygwD6qUXX
QKslqCh1EEbNfDUuBt31OhAFECkKl194euhuIjUugyL+D07Oscg+k77WDEesBif0
R8ei+j+AX/sK4RFacFMgAAWHaI3chGu2qrnFHoKEB/R9OUieEb6c8CbVEXyOzCbW
xerP1sxPBuqvw5/UMwdafXlVmPfC/7C1dJzdw5/yAE6gwEB0ztaaEMsA22smd8dk
NDugbmY9yTLRWFN2XIs9jgCaDM0hZOFDPbxkX7oD30z3FVkbuSII3EK0GAqHYy15
ZLD5xaxolyKOvQwXYoHVJD95KX1OVuNcILsd2iVGAKpI8IWOu2A1Kvq/Kr5qtxRW
hcP+nL5XVu/mGP/GABI/zggORdjfAezb9mWi2ozfmSHyJsN8qfVOvK4urDj2YdbR
tMybK+X7KpN947oZQwJ8WgfO3mTt4jkYPEFgUyVDFRuMcx25ewxy/5+HcpZvgmKd
esPTYnR/q+kdQ+IO2OrOoBGUJ8F7bmiAKVThBWZKUn9jGAym+A4CEMrklCYwqZT5
AuA0rI1AjitrP74YqylXtmP2IUJkxCOXBthnlt1oC2UPYXyACPdp5K4+KZbK/63B
WbrO/ELdag==
-----END CERTIFICATE-----

------------XnJLe9ZIbbGUYtzPQJ16u1--

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "remote_system.crt",
    • "type": "certificate",
    • "attributes": {
      • "filename": "remote_system.crt",
      • "content": "-----BEGIN CERTIFICATE-----\nMIIFQzCCAyugAwIBAgIUeNS0f9lqaJhC2apc91FbPRBVPNwwDQYJKoZIhvcNAQEL\nBQAwMTEQMA4GA1UEAwwHUm9vdCBDQTEdMBsGA1UECgwUTGltZVBvaW50RW5naW5l\nZXJpbmcwHhcNMjUwNDI5MDA0NzAxWhcNMzAwNDI5MDA0NzAxWjAxMRAwDgYDVQQD\nDAdSb290IENBMR0wGwYDVQQKDBRMaW1lUG9pbnRFbmdpbmVlcmluZzCCAiIwDQYJ\nKoZIhvcNAQEBBQADggIPADCCAgoCggIBAJoUxJkyK3VKbBhVwQPRmA9MqUOocn16\nSOZm5KVPVyR2F9OZ4xIyZTkUalUFGrguoDAyvKAI+AgGRhNJG+kKQ7PLAAEbSWBE\ngdXNNtSAj4Yvo0Bw3XbxqZM7kBO7GfysKMjqKsEeR0wiwshAQPsBjAYa78ayDRC5\nRqN1jR9al65UdLcE5yDbbpMd7GwR3b9ythahsox8PfHL60sZf7NfI4q+SkgbOVzt\ndxppCZqwZRuMVWdvvQk069UkOYoRXniQEIFU6Ugd8FWIIzleHyKEodTsRhhXUjBS\nGbA3v+x66mS87r6bE6ffFwLO0reFgfx4a7dMmhd5djrOfZtZ0L8zizXwsyee5j6v\niNokciyLHgRfWYHsYZ3OgHC8p7i02Xd9vcCsaPuoGopo0G/+wog289ObTqGbxu28\nX8Bk5/kIVkn79LDA4zWz7VwYY0uoK0TxWpdMg2yuvE5nH94qGlnJisopxVhrZ7qH\nE+QEqUYhelJNCi62Z8gmT0z3d7lmsq9gH23o1Zngdhnygdrm3rh404bjK/xFL6Hf\n0YmiYhQw8ydHKGWY8rfhjL8eXl1gURZTqLTZC6J3sF3SAS1hj2nrePsPGt7S1OqI\ndjd/vGLSLz/SGyE9d5sOeTvza9pmKKXKqcvPFbwgF496dZmAu6xtVC+6pa8hOXJW\nYlC0xn/xXnTFAgMBAAGjUzBRMB0GA1UdDgQWBBRdN8nNGCxpxe0zHXz3BrrtlYvV\nLjAfBgNVHSMEGDAWgBRdN8nNGCxpxe0zHXz3BrrtlYvVLjAPBgNVHRMBAf8EBTAD\nAQH/MA0GCSqGSIb3DQEBCwUAA4ICAQB6jtlLzWd6yjbye2SsB04ns6B6WskdOAkk\npjGz7MyARCEvgfHh5HtMzBi9l5mxXjMfYuQx3ag75lTSaA/OUgGCQOQygwD6qUXX\nQKslqCh1EEbNfDUuBt31OhAFECkKl194euhuIjUugyL+D07Oscg+k77WDEesBif0\nR8ei+j+AX/sK4RFacFMgAAWHaI3chGu2qrnFHoKEB/R9OUieEb6c8CbVEXyOzCbW\nxerP1sxPBuqvw5/UMwdafXlVmPfC/7C1dJzdw5/yAE6gwEB0ztaaEMsA22smd8dk\nNDugbmY9yTLRWFN2XIs9jgCaDM0hZOFDPbxkX7oD30z3FVkbuSII3EK0GAqHYy15\nZLD5xaxolyKOvQwXYoHVJD95KX1OVuNcILsd2iVGAKpI8IWOu2A1Kvq/Kr5qtxRW\nhcP+nL5XVu/mGP/GABI/zggORdjfAezb9mWi2ozfmSHyJsN8qfVOvK4urDj2YdbR\ntMybK+X7KpN947oZQwJ8WgfO3mTt4jkYPEFgUyVDFRuMcx25ewxy/5+HcpZvgmKd\nesPTYnR/q+kdQ+IO2OrOoBGUJ8F7bmiAKVThBWZKUn9jGAym+A4CEMrklCYwqZT5\nAuA0rI1AjitrP74YqylXtmP2IUJkxCOXBthnlt1oC2UPYXyACPdp5K4+KZbK/63B\nWbrO/ELdag==\n-----END CERTIFICATE-----\n",
      • "description": "New certificate description",
      • "created_at": "2026-11-17T01:50:02.763598Z",
      • "updated_at": "2026-11-17T01:50:02.763598Z"
      },
    • "links": {
      • "self": "/api/trust_store/remote_system.crt"
      }
    }
}

Show certificate

Shows a certificate from the trust store.

path Parameters
certificate_filename
required
string
Example: ca_self.pem

certificate filename

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "ca_self.pem",
    • "type": "certificate",
    • "attributes": {
      • "filename": "ca_self.pem",
      • "content": "-----BEGIN CERTIFICATE-----\nMIIFQzCCAyugAwIBAgIUeNS0f9lqaJhC2apc91FbPRBVPNwwDQYJKoZIhvcNAQEL\nBQAwMTEQMA4GA1UEAwwHUm9vdCBDQTEdMBsGA1UECgwUTGltZVBvaW50RW5naW5l\nZXJpbmcwHhcNMjUwNDI5MDA0NzAxWhcNMzAwNDI5MDA0NzAxWjAxMRAwDgYDVQQD\nDAdSb290IENBMR0wGwYDVQQKDBRMaW1lUG9pbnRFbmdpbmVlcmluZzCCAiIwDQYJ\nKoZIhvcNAQEBBQADggIPADCCAgoCggIBAJoUxJkyK3VKbBhVwQPRmA9MqUOocn16\nSOZm5KVPVyR2F9OZ4xIyZTkUalUFGrguoDAyvKAI+AgGRhNJG+kKQ7PLAAEbSWBE\ngdXNNtSAj4Yvo0Bw3XbxqZM7kBO7GfysKMjqKsEeR0wiwshAQPsBjAYa78ayDRC5\nRqN1jR9al65UdLcE5yDbbpMd7GwR3b9ythahsox8PfHL60sZf7NfI4q+SkgbOVzt\ndxppCZqwZRuMVWdvvQk069UkOYoRXniQEIFU6Ugd8FWIIzleHyKEodTsRhhXUjBS\nGbA3v+x66mS87r6bE6ffFwLO0reFgfx4a7dMmhd5djrOfZtZ0L8zizXwsyee5j6v\niNokciyLHgRfWYHsYZ3OgHC8p7i02Xd9vcCsaPuoGopo0G/+wog289ObTqGbxu28\nX8Bk5/kIVkn79LDA4zWz7VwYY0uoK0TxWpdMg2yuvE5nH94qGlnJisopxVhrZ7qH\nE+QEqUYhelJNCi62Z8gmT0z3d7lmsq9gH23o1Zngdhnygdrm3rh404bjK/xFL6Hf\n0YmiYhQw8ydHKGWY8rfhjL8eXl1gURZTqLTZC6J3sF3SAS1hj2nrePsPGt7S1OqI\ndjd/vGLSLz/SGyE9d5sOeTvza9pmKKXKqcvPFbwgF496dZmAu6xtVC+6pa8hOXJW\nYlC0xn/xXnTFAgMBAAGjUzBRMB0GA1UdDgQWBBRdN8nNGCxpxe0zHXz3BrrtlYvV\nLjAfBgNVHSMEGDAWgBRdN8nNGCxpxe0zHXz3BrrtlYvVLjAPBgNVHRMBAf8EBTAD\nAQH/MA0GCSqGSIb3DQEBCwUAA4ICAQB6jtlLzWd6yjbye2SsB04ns6B6WskdOAkk\npjGz7MyARCEvgfHh5HtMzBi9l5mxXjMfYuQx3ag75lTSaA/OUgGCQOQygwD6qUXX\nQKslqCh1EEbNfDUuBt31OhAFECkKl194euhuIjUugyL+D07Oscg+k77WDEesBif0\nR8ei+j+AX/sK4RFacFMgAAWHaI3chGu2qrnFHoKEB/R9OUieEb6c8CbVEXyOzCbW\nxerP1sxPBuqvw5/UMwdafXlVmPfC/7C1dJzdw5/yAE6gwEB0ztaaEMsA22smd8dk\nNDugbmY9yTLRWFN2XIs9jgCaDM0hZOFDPbxkX7oD30z3FVkbuSII3EK0GAqHYy15\nZLD5xaxolyKOvQwXYoHVJD95KX1OVuNcILsd2iVGAKpI8IWOu2A1Kvq/Kr5qtxRW\nhcP+nL5XVu/mGP/GABI/zggORdjfAezb9mWi2ozfmSHyJsN8qfVOvK4urDj2YdbR\ntMybK+X7KpN947oZQwJ8WgfO3mTt4jkYPEFgUyVDFRuMcx25ewxy/5+HcpZvgmKd\nesPTYnR/q+kdQ+IO2OrOoBGUJ8F7bmiAKVThBWZKUn9jGAym+A4CEMrklCYwqZT5\nAuA0rI1AjitrP74YqylXtmP2IUJkxCOXBthnlt1oC2UPYXyACPdp5K4+KZbK/63B\nWbrO/ELdag==\n-----END CERTIFICATE-----\n",
      • "description": "Main CA cert.",
      • "created_at": "2026-11-17T01:50:03.587984Z",
      • "updated_at": "2026-11-17T01:50:03.587984Z"
      },
    • "links": {
      • "self": "/api/trust_store/ca_self.pem"
      }
    }
}

Delete certificate

Delete certificate from the trust store.

path Parameters
certificate_filename
required
string
Example: ca_self.pem

certificate filename

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    • {
      • "status": 403,
      • "title": "You do not have permission to delete the certificate",
      • "detail": "Your authorisation rules let you view the certificate but not delete it."
      }
    ]
}

Update certificate

Updates a certificate in the trust store.

path Parameters
certificate_filename
required
string
Example: ca_self.pem

certificate filename

Request Body schema: multipart/form-data
description
string or null
file
string <binary>

certificate file (the filename is ignored)

Responses

Request samples

Content type
multipart/form-data
------------XnJLe9ZIbbGUYtzPQJ16u1
content-disposition: form-data; name="description"

Updated certificate description
------------XnJLe9ZIbbGUYtzPQJ16u1
content-disposition: form-data; name="file"; filename="remote_system.crt"
content-type: application/x-x509-ca-cert
content-length: 1887

-----BEGIN CERTIFICATE-----
MIIFQzCCAyugAwIBAgIUeNS0f9lqaJhC2apc91FbPRBVPNwwDQYJKoZIhvcNAQEL
BQAwMTEQMA4GA1UEAwwHUm9vdCBDQTEdMBsGA1UECgwUTGltZVBvaW50RW5naW5l
ZXJpbmcwHhcNMjUwNDI5MDA0NzAxWhcNMzAwNDI5MDA0NzAxWjAxMRAwDgYDVQQD
DAdSb290IENBMR0wGwYDVQQKDBRMaW1lUG9pbnRFbmdpbmVlcmluZzCCAiIwDQYJ
KoZIhvcNAQEBBQADggIPADCCAgoCggIBAJoUxJkyK3VKbBhVwQPRmA9MqUOocn16
SOZm5KVPVyR2F9OZ4xIyZTkUalUFGrguoDAyvKAI+AgGRhNJG+kKQ7PLAAEbSWBE
gdXNNtSAj4Yvo0Bw3XbxqZM7kBO7GfysKMjqKsEeR0wiwshAQPsBjAYa78ayDRC5
RqN1jR9al65UdLcE5yDbbpMd7GwR3b9ythahsox8PfHL60sZf7NfI4q+SkgbOVzt
dxppCZqwZRuMVWdvvQk069UkOYoRXniQEIFU6Ugd8FWIIzleHyKEodTsRhhXUjBS
GbA3v+x66mS87r6bE6ffFwLO0reFgfx4a7dMmhd5djrOfZtZ0L8zizXwsyee5j6v
iNokciyLHgRfWYHsYZ3OgHC8p7i02Xd9vcCsaPuoGopo0G/+wog289ObTqGbxu28
X8Bk5/kIVkn79LDA4zWz7VwYY0uoK0TxWpdMg2yuvE5nH94qGlnJisopxVhrZ7qH
E+QEqUYhelJNCi62Z8gmT0z3d7lmsq9gH23o1Zngdhnygdrm3rh404bjK/xFL6Hf
0YmiYhQw8ydHKGWY8rfhjL8eXl1gURZTqLTZC6J3sF3SAS1hj2nrePsPGt7S1OqI
djd/vGLSLz/SGyE9d5sOeTvza9pmKKXKqcvPFbwgF496dZmAu6xtVC+6pa8hOXJW
YlC0xn/xXnTFAgMBAAGjUzBRMB0GA1UdDgQWBBRdN8nNGCxpxe0zHXz3BrrtlYvV
LjAfBgNVHSMEGDAWgBRdN8nNGCxpxe0zHXz3BrrtlYvVLjAPBgNVHRMBAf8EBTAD
AQH/MA0GCSqGSIb3DQEBCwUAA4ICAQB6jtlLzWd6yjbye2SsB04ns6B6WskdOAkk
pjGz7MyARCEvgfHh5HtMzBi9l5mxXjMfYuQx3ag75lTSaA/OUgGCQOQygwD6qUXX
QKslqCh1EEbNfDUuBt31OhAFECkKl194euhuIjUugyL+D07Oscg+k77WDEesBif0
R8ei+j+AX/sK4RFacFMgAAWHaI3chGu2qrnFHoKEB/R9OUieEb6c8CbVEXyOzCbW
xerP1sxPBuqvw5/UMwdafXlVmPfC/7C1dJzdw5/yAE6gwEB0ztaaEMsA22smd8dk
NDugbmY9yTLRWFN2XIs9jgCaDM0hZOFDPbxkX7oD30z3FVkbuSII3EK0GAqHYy15
ZLD5xaxolyKOvQwXYoHVJD95KX1OVuNcILsd2iVGAKpI8IWOu2A1Kvq/Kr5qtxRW
hcP+nL5XVu/mGP/GABI/zggORdjfAezb9mWi2ozfmSHyJsN8qfVOvK4urDj2YdbR
tMybK+X7KpN947oZQwJ8WgfO3mTt4jkYPEFgUyVDFRuMcx25ewxy/5+HcpZvgmKd
esPTYnR/q+kdQ+IO2OrOoBGUJ8F7bmiAKVThBWZKUn9jGAym+A4CEMrklCYwqZT5
AuA0rI1AjitrP74YqylXtmP2IUJkxCOXBthnlt1oC2UPYXyACPdp5K4+KZbK/63B
WbrO/ELdag==
-----END CERTIFICATE-----

------------XnJLe9ZIbbGUYtzPQJ16u1--

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "remote_system.crt",
    • "type": "certificate",
    • "attributes": {
      • "filename": "remote_system.crt",
      • "content": "-----BEGIN CERTIFICATE-----\nMIIFQzCCAyugAwIBAgIUeNS0f9lqaJhC2apc91FbPRBVPNwwDQYJKoZIhvcNAQEL\nBQAwMTEQMA4GA1UEAwwHUm9vdCBDQTEdMBsGA1UECgwUTGltZVBvaW50RW5naW5l\nZXJpbmcwHhcNMjUwNDI5MDA0NzAxWhcNMzAwNDI5MDA0NzAxWjAxMRAwDgYDVQQD\nDAdSb290IENBMR0wGwYDVQQKDBRMaW1lUG9pbnRFbmdpbmVlcmluZzCCAiIwDQYJ\nKoZIhvcNAQEBBQADggIPADCCAgoCggIBAJoUxJkyK3VKbBhVwQPRmA9MqUOocn16\nSOZm5KVPVyR2F9OZ4xIyZTkUalUFGrguoDAyvKAI+AgGRhNJG+kKQ7PLAAEbSWBE\ngdXNNtSAj4Yvo0Bw3XbxqZM7kBO7GfysKMjqKsEeR0wiwshAQPsBjAYa78ayDRC5\nRqN1jR9al65UdLcE5yDbbpMd7GwR3b9ythahsox8PfHL60sZf7NfI4q+SkgbOVzt\ndxppCZqwZRuMVWdvvQk069UkOYoRXniQEIFU6Ugd8FWIIzleHyKEodTsRhhXUjBS\nGbA3v+x66mS87r6bE6ffFwLO0reFgfx4a7dMmhd5djrOfZtZ0L8zizXwsyee5j6v\niNokciyLHgRfWYHsYZ3OgHC8p7i02Xd9vcCsaPuoGopo0G/+wog289ObTqGbxu28\nX8Bk5/kIVkn79LDA4zWz7VwYY0uoK0TxWpdMg2yuvE5nH94qGlnJisopxVhrZ7qH\nE+QEqUYhelJNCi62Z8gmT0z3d7lmsq9gH23o1Zngdhnygdrm3rh404bjK/xFL6Hf\n0YmiYhQw8ydHKGWY8rfhjL8eXl1gURZTqLTZC6J3sF3SAS1hj2nrePsPGt7S1OqI\ndjd/vGLSLz/SGyE9d5sOeTvza9pmKKXKqcvPFbwgF496dZmAu6xtVC+6pa8hOXJW\nYlC0xn/xXnTFAgMBAAGjUzBRMB0GA1UdDgQWBBRdN8nNGCxpxe0zHXz3BrrtlYvV\nLjAfBgNVHSMEGDAWgBRdN8nNGCxpxe0zHXz3BrrtlYvVLjAPBgNVHRMBAf8EBTAD\nAQH/MA0GCSqGSIb3DQEBCwUAA4ICAQB6jtlLzWd6yjbye2SsB04ns6B6WskdOAkk\npjGz7MyARCEvgfHh5HtMzBi9l5mxXjMfYuQx3ag75lTSaA/OUgGCQOQygwD6qUXX\nQKslqCh1EEbNfDUuBt31OhAFECkKl194euhuIjUugyL+D07Oscg+k77WDEesBif0\nR8ei+j+AX/sK4RFacFMgAAWHaI3chGu2qrnFHoKEB/R9OUieEb6c8CbVEXyOzCbW\nxerP1sxPBuqvw5/UMwdafXlVmPfC/7C1dJzdw5/yAE6gwEB0ztaaEMsA22smd8dk\nNDugbmY9yTLRWFN2XIs9jgCaDM0hZOFDPbxkX7oD30z3FVkbuSII3EK0GAqHYy15\nZLD5xaxolyKOvQwXYoHVJD95KX1OVuNcILsd2iVGAKpI8IWOu2A1Kvq/Kr5qtxRW\nhcP+nL5XVu/mGP/GABI/zggORdjfAezb9mWi2ozfmSHyJsN8qfVOvK4urDj2YdbR\ntMybK+X7KpN947oZQwJ8WgfO3mTt4jkYPEFgUyVDFRuMcx25ewxy/5+HcpZvgmKd\nesPTYnR/q+kdQ+IO2OrOoBGUJ8F7bmiAKVThBWZKUn9jGAym+A4CEMrklCYwqZT5\nAuA0rI1AjitrP74YqylXtmP2IUJkxCOXBthnlt1oC2UPYXyACPdp5K4+KZbK/63B\nWbrO/ELdag==\n-----END CERTIFICATE-----\n",
      • "description": "Updated certificate description",
      • "created_at": "2026-11-17T01:50:05.859191Z",
      • "updated_at": "2026-11-17T01:50:05.859191Z"
      },
    • "links": {
      • "self": "/api/trust_store/remote_system.crt"
      }
    }
}

System configuration

Endpoint to fetch the current system configuration.

Update licence

Updates the system licence.

Request Body schema: multipart/form-data
licence
string

Responses

Request samples

Content type
multipart/form-data
------------XnJLe9ZIbbGUYtzPQJ16u1
content-disposition: form-data; name="licence"; filename="expired_opschain.licence"
content-type: application/json
content-length: 924

{"data":{"license_issuer":"LimePoint Pty Ltd","license_issuer_contact":"support@limepoint.com","license_version":"1","customer_identifier":"Engineering","start_date":"2023-11-14T00:00:00Z","end_date":"2024-02-14T00:00:00Z"},"signature":"m/hevqjjrYYjOS8ZtgVGGerm028UpKWw/I1cGB4vcJCwI805OtAo1PmszCxWQGOXilgAqyLERLluimRBckFYVL8yx7+rTFxF4D13FqwbwRL5HcKKkV1wwGgzuMpaGE8JGpAq/CkBq6l3xL+jPv/CSYaEyE55+20UdmkZdkvR2vKoJtqDzA1q/4T9tiPA0YIKDjjxSasLBpqokl0iUuaDWksaIhXjdsKmj0FSPfVD2VyPyrBSc1sv0pR+qz98Ny9ef7t6/pIaphLo8Yaa2dnJykeXtAWiaLe+25/OWxEHZoZBvKjentD5dzvqiA8Xo1qhm/tMurTQq4BGJvWYK70LQY9EXlxd+1XLbFX0qdNBNFnzf+rjbGfrLIMw2NFhsODDordSh5P3xNGGG4JyXrwXVRPUaw30celB+uYK3vvDzis0DSBXSA+D9JV3E9YxbI4xuT9Kf+bl0+cr/BajEBhuzATk30a8y5Zqn2MfCBmMb1iLkoFWWvFA+cfUsKsWk3O4YDmR3paOz+HVrSA5HlwaOMOU/P15/q5YFfN6ZEz4DW28I+lfFE3PtgkCsjcPCd99Ca4ZSmiok/l55zRxxrYl6Xc1TNOuq58yp05U798VaEEvmCaVvp5Fk/+TrbGMWKUlPPvc86RzsOlI8Qkdn75SJM3WMEl931m4A52g6jF6+T0="}

------------XnJLe9ZIbbGUYtzPQJ16u1--

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "expired_opschain.licence",
    • "type": "licence",
    • "attributes": {
      • "licence": "licence data"
      }
    }
}

Get OpsChain system configuration

Shows the current system configuration node.

query Parameters
include
string
Example: include=settings

Include the settings in the response

fields[<resource_type>]
string
Example: fields[<resource_type>]=code,name

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e731-afa7-79fa-8ac8-b9bb73d693db",
    • "type": "system_configuration",
    • "attributes": {
      • "code": "system",
      • "name": "System Configuration",
      • "description": "System configuration node"
      },
    • "relationships": {
      • "settings": {
        },
      • "properties": {
        }
      },
    • "links": {
      • "self": "/api/system_configuration",
      • "settings": "/api/settings/01a1e731-afc8-7479-9dc9-15917fa57b00",
      • "properties": "/api/properties/01a1e731-afaf-73b5-a121-1686e9458d3a"
      },
    • "meta": {
      • "can_have_changes": false,
      • "can_have_children": false,
      • "can_have_properties": true,
      • "can_have_settings": true,
      • "can_have_templates": false,
      • "requires_template": false,
      • "child_node_types": [ ],
      • "can_have_workflows": false,
      • "can_have_actions": false,
      • "authorisations": {
        },
      • "secret_vault": {
        }
      }
    },
  • "included": [
    • {
      • "id": "01a1e731-afc8-7479-9dc9-15917fa57b00",
      • "type": "settings",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        }
      }
    ]
}

Admin operations

Endpoints to monitor the status of your OpsChain instance.

Get the clusters in the OpsChain topology

Returns every database cluster that has registered itself, whether its workers are currently running work and how its copy of the database is keeping up. The replication status is either primary, streaming (up to date), lagging (behind and still catching up), disconnected (a replication slot exists but nothing is attached to it) or lost (too far behind to catch up, so its copy has to be rebuilt). It is only reported for what the primary database can see, so it is absent for a database cluster that streams from another replica rather than from the primary.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "opschain-db",
      • "type": "cluster",
      • "attributes": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "cordon": true
      }
    }
}

Cordon or uncordon a site

Cordons a site so it takes no new work, or uncordons it so it takes work again. Work already running in a cordoned site carries on there until it finishes, including its running agents, and is reported in each site's work_in_progress. A site cannot be cordoned while no other site is taking work.

path Parameters
name
required
string

The name of the site (its database cluster)

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "cordoned": true,
      • "cordon_reason": "Disaster recovery test"
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "opschain-db",
    • "type": "cluster",
    • "attributes": {
      • "name": "opschain-db",
      • "role": "primary",
      • "cordon_reason": "Disaster recovery test",
      • "consuming_work": true,
      • "cordoned": true,
      • "cordoned_by": "logged_in_user",
      • "cordoned_by_name": "logged_in_user",
      • "replication_status": "primary",
      • "replication_lag_seconds": null,
      • "work_in_progress": {
        },
      • "last_worker_seen_at": "2026-11-17T01:42:23.187665Z",
      • "api_started_at": "2026-11-17T01:42:23.186340Z",
      • "cordoned_at": "2026-11-17T01:42:23.224158Z"
      }
    }
}

Get status information about the OpsChain database

Returns status information about the OpsChain database.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "0",
      • "type": "database_status",
      • "attributes": {
        },
      • "links": {
        }
      }
    ]
}

Get whether OpsChain is currently drained of in-flight work

Returns whether the OpsChain instance is currently drained (no active changes, workflow runs, or node background tasks), along with the active count for each. Intended to be checked before proceeding with a maintenance-mode upgrade window, to confirm nothing is still in-flight.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "0",
      • "type": "drain_status",
      • "attributes": {
        },
      • "links": {
        }
      }
    ]
}

Get currently active OpsChain background tasks

Returns every node background task (generate actions requests, MintModel concretise tasks, agent image builds, agent start/stop tasks) that has not yet finished, across all nodes.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [ ]
}

Get the status of the OpsChain nodes

Returns the status of all the OpsChain nodes.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "opschain.limepoint.engineering",
      • "type": "node_status",
      • "attributes": {
        }
      }
    ]
}

Get the status of the OpsChain queues

Returns the status of the OpsChain queues and details about their jobs. This covers the shared default queue and the per cluster queues, one for each cluster in the topology.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "default",
      • "type": "queue_status",
      • "attributes": {
        }
      }
    ]
}

Get the status of the OpsChain resource slot pools

Returns the status of the actions_refresh, runner, mintmodel_concretise, and image_build slot pools, including per-slot occupancy.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "runner",
      • "type": "resource_slot_pool",
      • "attributes": {
        }
      }
    ]
}

Get the status of the OpsChain API workers

Returns the status of all the OpsChain API workers in the configured namespace.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "opschain-api-worker-1",
      • "type": "worker",
      • "attributes": {
        },
      • "links": {
        }
      }
    ]
}

List the deployments in the OpsChain namespace

Returns every deployment in the OpsChain Kubernetes namespace, including its replica counts, rollout status and the time it was last restarted.

Notes:

  • Each deployment reports the highest number of replicas OpsChain will run it at as meta.max_replicas.
  • A deployment that can be scaled - one whose meta.max_replicas is greater than 1 - carries a scale link. A client should use the presence of the link to decide whether to offer scaling, rather than matching on the deployment name.
  • Each container reports its live resources (requests and limits). The MintModel API deployment also reports its live meta.concurrency, meta.transformer_heap and meta.transformer_spares, and the smallest memory limit they need as meta.minimum_memory_limit, so a client can show the current sizing before changing it. These are read from the running deployment, so they include any change made through the resources endpoint.
  • A deployment that can be resized carries a resources link. As with scaling, a client should use the presence of the link rather than the deployment name.
  • meta.authorisations.resources, meta.authorisations.restart and meta.authorisations.scale report whether the user may perform those operations, allowing a client to hide the controls it cannot use.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "opschain-api",
      • "type": "deployment",
      • "attributes": {
        },
      • "links": { },
      • "meta": {
        }
      },
    • {
      • "id": "opschain-api-worker",
      • "type": "deployment",
      • "attributes": {
        },
      • "links": {
        },
      • "meta": {
        }
      },
    • {
      • "id": "opschain-mintmodel-api",
      • "type": "deployment",
      • "attributes": {
        },
      • "links": {
        },
      • "meta": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "resources": true,
      • "restart": true,
      • "scale": true
      }
    }
}

Restart a deployment

Performs a rolling restart of a deployment in the OpsChain Kubernetes namespace, replacing each of its pods without changing the deployment configuration.

Notes:

  • Restarting a deployment requires the updatable permission on the /admin/deployments/restart authorisation path. A rule on a parent path (e.g. /admin) grants it, and a rule on the restart path itself overrides that parent rule.
  • The restart is performed asynchronously by Kubernetes - the response reports the deployment as it was accepted for restart, not the completed rollout.
  • Restarting the OpsChain API deployment terminates the pod serving the request.
path Parameters
name
required
string
Example: opschain-api

deployment name

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "opschain-api",
    • "type": "deployment",
    • "attributes": {
      • "namespace": "opschain",
      • "uid": "c3d4e5f6-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
      • "creation_timestamp": "2021-01-01T00:00:00Z",
      • "generation": 3,
      • "replicas": 2,
      • "strategy": "RollingUpdate",
      • "current_replicas": 2,
      • "ready_replicas": 2,
      • "available_replicas": 2,
      • "updated_replicas": 2,
      • "observed_generation": 3,
      • "revision": "2",
      • "restarted_at": "2021-01-02T00:00:00.000Z",
      • "labels": {
        },
      • "selector": {
        },
      • "containers": [
        ],
      • "conditions": [
        ]
      },
    • "links": { },
    • "meta": {
      • "max_replicas": 1
      }
    }
}

Scale a deployment

Sets the number of replicas of a deployment in the OpsChain Kubernetes namespace.

Notes:

  • Scaling a deployment requires the updatable permission on the /admin/deployments/scale authorisation path. A rule on a parent path (e.g. /admin) grants it, and a rule on the scale path itself overrides that parent rule.
  • Only the opschain-api-worker, opschain-mintmodel-api deployments can be scaled - every other deployment runs at a single replica and scaling it is rejected.
  • replicas must be a whole number between 0 and the deployment's own maximum, which the list and scale responses report as meta.max_replicas.
  • The scaling is performed asynchronously by Kubernetes - the response reports the deployment as it was accepted for scaling, not the completed rollout.
  • Scaling the MintModel API changes how many MintModel renders this site runs at once (its replicas multiplied by its concurrency), and OpsChain admits renders against the new capacity straight away. Renders that arrive while new pods are starting are retried.
  • Scaling down does not stop the surplus workers immediately - they keep running until they have finished their in-progress jobs, for up to the deployment's termination grace period (1 hour by default).
  • The replica count is not written back to the OpsChain Helm values, so the next Helm upgrade returns the deployment to its configured replica count.
path Parameters
name
required
string
Example: opschain-api-worker

deployment name

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "replicas": 3
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "opschain-api-worker",
    • "type": "deployment",
    • "attributes": {
      • "namespace": "opschain",
      • "uid": "c3d4e5f6-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
      • "creation_timestamp": "2021-01-01T00:00:00Z",
      • "generation": 3,
      • "replicas": 3,
      • "strategy": "RollingUpdate",
      • "current_replicas": 2,
      • "ready_replicas": 2,
      • "available_replicas": 2,
      • "updated_replicas": 2,
      • "observed_generation": 3,
      • "revision": "2",
      • "restarted_at": "2021-01-02T00:00:00.000Z",
      • "labels": {
        },
      • "selector": {
        },
      • "containers": [
        ],
      • "conditions": [
        ]
      },
    • "links": {
      • "scale": "/api/admin/deployments/opschain-api-worker/scale"
      },
    • "meta": {
      • "max_replicas": 10
      }
    }
}

Resize a deployment

Changes the memory and CPU requests and limits of a deployment in the OpsChain Kubernetes namespace, and for the MintModel API the number of renders each replica runs at once and the heap of each transformer JVM. This changes at runtime what mintModelApi.resources, mintModelApi.concurrency and mintModelApi.transformer.heap set in values.yaml.

Notes:

  • Resizing a deployment requires the updatable permission on the /admin/deployments/resources authorisation path. A rule on a parent path (e.g. /admin) grants it, and a rule on the resources path itself overrides that parent rule.
  • Only the opschain-mintmodel-api deployment can be resized.
  • Supply any of resources, concurrency and transformer_heap; what is left out keeps its current value. Within resources, only the quantities supplied change, and a quantity set to null is removed. The current values are reported by the deployments list.
  • concurrency must be a whole number of at least 1, and no lower than the spare transformers the deployment keeps (meta.transformer_spares, set by mintModelApi.transformer.spares in values.yaml). transformer_heap is a JVM size such as 1536m or 2g.
  • The memory limit must cover what the concurrency and heap need, as the Helm chart requires: 100Mi for the server, 320Mi per concurrent render, and one more transformer JVM than the concurrency, each of the heap plus 320Mi. The deployments list reports this as meta.minimum_memory_limit, and a smaller limit is rejected. The same rule is applied by the chart, so a change to it there must be made here too.
  • Changing the replicas or concurrency changes how many MintModel renders this site runs at once, and OpsChain admits renders against the new capacity straight away. Renders that arrive while the new pods are starting are retried.
  • No upper limit is applied beyond those Kubernetes enforces. A pod that asks for more than any node can give stays pending, and the existing pods keep serving until it starts.
  • The change is performed asynchronously by Kubernetes as a rolling update - the response reports the deployment as it was accepted, not the completed rollout. Renders in progress finish before a replaced pod stops, up to the deployment's termination grace period.
  • The change applies to this site only. In a multi-site installation, resize each site's deployment separately.
  • The change is not written back to the OpsChain Helm values, so a Helm upgrade that changes mintModelApi.resources, mintModelApi.concurrency or mintModelApi.transformer.heap returns the deployment to its configured values. To change the number of spare transformers, set mintModelApi.transformer.spares in values.yaml and redeploy.
  • The audit event recorded for the change includes the deployment's sizing before it, as previous.
path Parameters
name
required
string
Example: opschain-mintmodel-api

deployment name

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "resources": {
        },
      • "concurrency": 2,
      • "transformer_heap": "2g"
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "opschain-mintmodel-api",
    • "type": "deployment",
    • "attributes": {
      • "namespace": "opschain",
      • "uid": "c3d4e5f6-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
      • "creation_timestamp": "2021-01-01T00:00:00Z",
      • "generation": 3,
      • "replicas": 2,
      • "strategy": "RollingUpdate",
      • "current_replicas": 2,
      • "ready_replicas": 2,
      • "available_replicas": 2,
      • "updated_replicas": 2,
      • "observed_generation": 3,
      • "revision": "2",
      • "restarted_at": "2021-01-02T00:00:00.000Z",
      • "labels": {
        },
      • "selector": {
        },
      • "containers": [
        ],
      • "conditions": [
        ]
      },
    • "links": {
      • "scale": "/api/admin/deployments/opschain-mintmodel-api/scale",
      • "resources": "/api/admin/deployments/opschain-mintmodel-api/resources"
      },
    • "meta": {
      • "max_replicas": 5,
      • "concurrency": 2,
      • "transformer_heap": "1536m",
      • "transformer_spares": 1,
      • "minimum_memory_limit": "6308Mi"
      }
    }
}

List the external vaults

Lists the external secret vaults, in code order. A setting assigns one to a project, environment, asset, template or template version through vault.code. The service credentials are never returned.

Notes:

  • Managing external vaults requires superuser access. No authorisation rule grants it.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e72f-06ae-74bb-8f1e-48f766484d62",
      • "type": "external_vault",
      • "attributes": {
        }
      }
    ]
}

Create an external vault

Registers an external secret vault. OpsChain logs in to the vault with the service credentials before saving it, and saves nothing when the vault cannot be reached or does not accept them.

Notes:

  • Managing external vaults requires superuser access. No authorisation rule grants it.
  • The code cannot be bundled, which assigns the bundled secret vault, and cannot be changed later.
  • Only one external vault may use an address and namespace, so each vault server has one set of service credentials.
  • The credentials must be the values themselves. A secret-vault:// reference is rejected.
Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "code": "team_vault",
      • "name": "Team vault",
      • "auth_method": "token",
      • "client_options": {
        },
      • "token": "hvs.service-token",
      • "username": "opschain",
      • "password": "service-password"
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72f-0763-7cea-a449-6c41c35a2b2a",
    • "type": "external_vault",
    • "attributes": {
      • "code": "new_vault",
      • "name": "New vault",
      • "auth_method": "token",
      • "client_options": { },
      • "token_configured": true,
      • "username_configured": false,
      • "password_configured": false,
      • "created_at": "2026-11-17T01:46:21.410388Z",
      • "updated_at": "2026-11-17T01:46:21.410388Z"
      }
    }
}

Show an external vault

Shows an external secret vault. The service credentials are never returned.

Notes:

  • Managing external vaults requires superuser access. No authorisation rule grants it.
path Parameters
id
required
string

external vault id

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72f-09c2-7aaa-9f30-26d5289cdaa9",
    • "type": "external_vault",
    • "attributes": {
      • "code": "team_vault",
      • "name": "Team vault",
      • "auth_method": "token",
      • "client_options": {
        },
      • "token_configured": true,
      • "username_configured": false,
      • "password_configured": false,
      • "created_at": "2026-11-17T01:46:22.017478Z",
      • "updated_at": "2026-11-17T01:46:22.017478Z"
      }
    }
}

Update an external vault

Updates an external secret vault. A credential left blank keeps the stored value. OpsChain logs in to the vault with the resulting credentials before saving, and saves nothing when the vault cannot be reached or does not accept them.

Notes:

  • Managing external vaults requires superuser access. No authorisation rule grants it.
  • The code cannot be changed.
path Parameters
id
required
string

external vault id

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "name": "Team vault",
      • "auth_method": "token",
      • "client_options": {
        },
      • "token": "hvs.service-token",
      • "username": "opschain",
      • "password": "service-password"
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72f-0be0-7ba1-91b8-2196d2814a59",
    • "type": "external_vault",
    • "attributes": {
      • "code": "team_vault",
      • "name": "Renamed vault",
      • "auth_method": "token",
      • "client_options": {
        },
      • "token_configured": true,
      • "username_configured": false,
      • "password_configured": false,
      • "created_at": "2026-11-17T01:46:22.559501Z",
      • "updated_at": "2026-11-17T01:46:22.575588Z"
      }
    }
}

Delete an external vault

Deletes an external secret vault.

Notes:

  • Managing external vaults requires superuser access. No authorisation rule grants it.
path Parameters
id
required
string

external vault id

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    • {
      • "status": 404,
      • "title": "Record not found",
      • "meta": {
        }
      }
    ]
}

List the pods in the OpsChain namespace

Returns every pod in the OpsChain Kubernetes namespace, including the runner, MintModel and OpsChain API worker pods.

Notes:

  • meta.authorisations.read_logs reports whether the user may fetch the pod logs, allowing a client to hide the logs links it cannot follow.
  • meta.authorisations.delete reports whether the user may delete pods, allowing a client to hide the delete control it cannot use.
  • controlled_by names the Kubernetes controller managing the pod (e.g. ReplicaSet/opschain-api) and is null for the pods OpsChain creates itself.
  • A delete link is only present on the pods that can be deleted - see the delete pod endpoint.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "change-3ecf1a2b-4d5e-4f60-8a71-92b3c4d5e6f7",
      • "type": "pod",
      • "attributes": {
        },
      • "links": {
        }
      },
    • {
      • "id": "opschain-api-worker-1",
      • "type": "pod",
      • "attributes": {
        },
      • "links": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "delete": true,
      • "read_logs": true
      }
    }
}

Get a pod's log

Returns the log for a pod in the OpsChain Kubernetes namespace.

Notes:

  • Fetching a pod log requires the readable permission on the /admin/pods/logs authorisation path. A rule on a parent path (e.g. /admin) grants it, and a rule on the logs path itself overrides that parent rule.
  • Pod logs are only retained by Kubernetes while the pod exists - use the OpsChain change / workflow run log lines to review the output of a completed change.
  • At most 100MB of the pod log is read from the Kubernetes API per request. Log output beyond that limit is not returned.
path Parameters
name
required
string
Example: change-3ecf1a2b-4d5e-4f60-8a71-92b3c4d5e6f7

pod name

query Parameters
container
string
Example: container=opschain-runner

The container to fetch the log for. Defaults to the pod's first container. The valid values for a pod are listed in the containers attribute of the list pods response.

limit
integer [ 1 .. 10000 ]
Default: 1000
Example: limit=1000

The maximum number of log lines to return. A 206 response and a more link are returned when the pod log has more lines than the limit.

filter[logged_at_gt]
string
Example: filter[logged_at_gt]=2021-01-01T00:00:01.123456Z-0

Only return log lines logged after this cursor. Supply the id of the last log line received to fetch the next page of log lines - supplying a bare timestamp instead excludes every log line sharing that timestamp.

download
string
Example: download=pod.log

Download the entire pod log with the specified file name. The limit and filter[logged_at_gt] parameters are ignored when downloading.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "2021-01-01T00:00:01.123456Z-0",
      • "type": "log_line",
      • "attributes": {
        }
      },
    • {
      • "id": "2021-01-01T00:00:02.234567Z-0",
      • "type": "log_line",
      • "attributes": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true
      },
    • "partial_response": false
    }
}

Force delete a pod

Force deletes a pod in the OpsChain Kubernetes namespace, without waiting out its termination grace period.

Notes:

  • Deleting a pod requires superuser access. No authorisation rule grants it.
  • Only the pods OpsChain creates to do its own processing can be deleted - the change worker, step runner, agent, generate actions and MintModel generation pods. The pods belonging to the OpsChain deployments and stateful sets are refused, as are any other pods sharing the namespace.
  • The delete link on a pod in the list pods response identifies the pods this endpoint accepts, so a client does not need its own copy of that rule.
  • Kubernetes removes the pod asynchronously - the response reports the pod as it was accepted for deletion.
  • Deleting a pod that OpsChain is still waiting on fails the step or task it was running. Use it to recover from a pod that is stuck, not to stop work in progress - cancel the change or workflow run instead.
path Parameters
name
required
string
Example: change-3ecf1a2b-4d5e-4f60-8a71-92b3c4d5e6f7

pod name

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "change-3ecf1a2b-4d5e-4f60-8a71-92b3c4d5e6f7",
    • "type": "pod",
    • "attributes": {
      • "namespace": "opschain",
      • "node": "node-1",
      • "host_ip": "192.168.1.1",
      • "pod_ip": "10.42.0.17",
      • "start_time": "2021-01-01T00:00:00Z",
      • "state": "Running",
      • "image": "opschain-runner-image",
      • "restart_count": 0,
      • "uid": "a1b2c3d4-5e6f-4a8b-9c0d-1e2f3a4b5c6d",
      • "containers": [
        ],
      • "controlled_by": null,
      • "labels": {
        }
      },
    • "links": {
      • "logs": "/api/admin/pods/change-3ecf1a2b-4d5e-4f60-8a71-92b3c4d5e6f7/logs",
      • "delete": "/api/admin/pods/change-3ecf1a2b-4d5e-4f60-8a71-92b3c4d5e6f7"
      }
    }
}

List the secret vault policies assigned to LDAP users

Lists the LDAP users that hold at least one vault policy in the bundled secret vault, with the policies assigned to each.

Notes:

  • Listing vault policy assignments requires superuser access. No authorisation rule grants it.
  • The policies OpsChain owns (those starting with opschain-) and the default and root policies are not listed.
  • Only available when OpsChain uses the bundled secret vault with LDAP authentication.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "alice",
      • "type": "secret_vault_ldap_user",
      • "attributes": {
        }
      }
    ]
}

Show the secret vault policies assigned to an LDAP user

Shows the vault policies assigned to an LDAP user in the bundled secret vault.

Notes:

  • Viewing vault policy assignments requires superuser access. No authorisation rule grants it.
  • The user must exist in the LDAP directory.
  • The policies OpsChain owns (those starting with opschain-) and the default and root policies are not shown.
  • Only available when OpsChain uses the bundled secret vault with LDAP authentication.
path Parameters
name
required
string
Example: alice

LDAP user name

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "alice",
    • "type": "secret_vault_ldap_user",
    • "attributes": {
      • "name": "alice",
      • "policies": [
        ]
      }
    }
}

Assign secret vault policies to an LDAP user

Sets the vault policies assigned to an LDAP user in the bundled secret vault. The policies supplied replace those currently assigned - send an empty list to remove them all.

Notes:

  • Assigning vault policies requires superuser access. No authorisation rule grants it.
  • The user must exist in the LDAP directory, and every policy must already exist in the vault.
  • The policies OpsChain owns (those starting with opschain-) and the default and root policies cannot be assigned. Any OpsChain policy the user already holds is kept.
  • Only available when OpsChain uses the bundled secret vault with LDAP authentication.
path Parameters
name
required
string
Example: alice

LDAP user name

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "policies": [
        ]
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "alice",
    • "type": "secret_vault_ldap_user",
    • "attributes": {
      • "name": "alice",
      • "policies": [
        ]
      }
    }
}

List the secret vault policies assigned to LDAP groups

Lists the LDAP groups that hold at least one vault policy in the bundled secret vault, with the policies assigned to each.

Notes:

  • Listing vault policy assignments requires superuser access. No authorisation rule grants it.
  • The policies OpsChain owns (those starting with opschain-) and the default and root policies are not listed.
  • Only available when OpsChain uses the bundled secret vault with LDAP authentication.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "alice",
      • "type": "secret_vault_ldap_group",
      • "attributes": {
        }
      }
    ]
}

Show the secret vault policies assigned to an LDAP group

Shows the vault policies assigned to an LDAP group in the bundled secret vault.

Notes:

  • Viewing vault policy assignments requires superuser access. No authorisation rule grants it.
  • The group must exist in the LDAP directory.
  • The policies OpsChain owns (those starting with opschain-) and the default and root policies are not shown.
  • Only available when OpsChain uses the bundled secret vault with LDAP authentication.
path Parameters
name
required
string
Example: alice

LDAP group name

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "alice",
    • "type": "secret_vault_ldap_group",
    • "attributes": {
      • "name": "alice",
      • "policies": [
        ]
      }
    }
}

Assign secret vault policies to an LDAP group

Sets the vault policies assigned to an LDAP group in the bundled secret vault. The policies supplied replace those currently assigned - send an empty list to remove them all.

Notes:

  • Assigning vault policies requires superuser access. No authorisation rule grants it.
  • The group must exist in the LDAP directory, and every policy must already exist in the vault.
  • The policies OpsChain owns (those starting with opschain-) and the default and root policies cannot be assigned. Any OpsChain policy the group already holds is kept.
  • Only available when OpsChain uses the bundled secret vault with LDAP authentication.
path Parameters
name
required
string
Example: alice

LDAP group name

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "policies": [
        ]
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "alice",
    • "type": "secret_vault_ldap_group",
    • "attributes": {
      • "name": "alice",
      • "policies": [
        ]
      }
    }
}

List the secret vault key value mounts

Lists the key value mounts of the bundled secret vault, in path order. These are the mounts a secret vault policy rule may use - every rule path must be one of these paths, or a path below one.

Notes:

  • Listing the vault mounts requires superuser access. No authorisation rule grants it.
  • Only available when OpsChain uses the bundled secret vault with LDAP authentication.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "secrets",
      • "type": "secret_vault_mount",
      • "attributes": {
        }
      },
    • {
      • "id": "team-a",
      • "type": "secret_vault_mount",
      • "attributes": {
        }
      }
    ]
}

List the secret vault policies

Lists the ACL policies in the bundled secret vault that OpsChain can manage, in name order. Each policy's document is the policy as the vault stores it, converted to JSON when it is written in HCL, and original_document then holds the HCL as the vault stores it; rules holds its rules when the document is in the format OpsChain writes, and is null for a policy with settings OpsChain does not manage.

Notes:

  • Listing vault policies requires superuser access. No authorisation rule grants it.
  • The default and root policies, and the policies OpsChain owns (those starting with opschain-), are not listed.
  • Only available when OpsChain uses the bundled secret vault with LDAP authentication.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "team-a-readers",
      • "type": "secret_vault_policy",
      • "attributes": {
        }
      }
    ]
}

Create a secret vault policy

Creates an ACL policy in the bundled secret vault from the rules in the document. Assign it to LDAP users and groups through the secret_vault_ldap_users and secret_vault_ldap_groups admin endpoints.

Notes:

  • Creating a vault policy requires superuser access. No authorisation rule grants it.
  • The name must not already be used by a vault policy - use the update endpoint to change an existing policy's rules.
  • Every rule path must be a key value mount, or a path below one, and may only use the create, read, update, patch, delete, list, sudo, deny capabilities.
  • A rule may also set allowed_parameters, denied_parameters, required_parameters, min_wrapping_ttl and max_wrapping_ttl, as in a vault policy.
  • Vault admins cannot write policies in the vault directly - a policy written there could grant access to the vault's own configuration, so OpsChain writes them on their behalf and only accepts rules that stay within the vault's key value mounts.
  • The default and root policies, and the policies OpsChain owns (those starting with opschain-), cannot be created.
  • Only available when OpsChain uses the bundled secret vault with LDAP authentication.
Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "name": "team-a-readers",
      • "document": "{\"path\":{\"secrets/team-a/*\":{\"capabilities\":[\"read\",\"list\"]}}}"
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "team-a-readers",
    • "type": "secret_vault_policy",
    • "attributes": {
      • "name": "team-a-readers",
      • "rules": [
        ],
      • "document": "{\"path\":{\"secrets/team-a/*\":{\"capabilities\":[\"read\",\"list\"]}}}",
      • "format": "json",
      • "original_document": null,
      • "modified": null,
      • "version": null
      }
    }
}

Show a secret vault policy

Shows an ACL policy in the bundled secret vault. The document is the policy as the vault stores it, converted to JSON when it is written in HCL, and original_document then holds the HCL as the vault stores it; rules holds its rules when the document is in the format OpsChain writes, and is null for a policy with settings OpsChain does not manage.

Notes:

  • Viewing a vault policy requires superuser access. No authorisation rule grants it.
  • The default and root policies, and the policies OpsChain owns (those starting with opschain-), cannot be viewed.
  • Only available when OpsChain uses the bundled secret vault with LDAP authentication.
path Parameters
name
required
string
Example: team-a-readers

vault policy name

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "team-a-readers",
    • "type": "secret_vault_policy",
    • "attributes": {
      • "name": "team-a-readers",
      • "rules": [
        ],
      • "document": "{\"path\":{\"secrets/team-a/*\":{\"capabilities\":[\"read\",\"list\"]}}}",
      • "format": "json",
      • "original_document": null,
      • "modified": "2026-10-26T10:36:19.734221565Z",
      • "version": 1
      }
    }
}

Update a secret vault policy

Replaces the rules of an existing ACL policy in the bundled secret vault with those in the document.

Notes:

  • Updating a vault policy requires superuser access. No authorisation rule grants it.
  • Every rule path must be a key value mount, or a path below one, and may only use the create, read, update, patch, delete, list, sudo, deny capabilities.
  • A rule may also set allowed_parameters, denied_parameters, required_parameters, min_wrapping_ttl and max_wrapping_ttl, as in a vault policy.
  • The default and root policies, and the policies OpsChain owns (those starting with opschain-), cannot be updated.
  • Only available when OpsChain uses the bundled secret vault with LDAP authentication.
path Parameters
name
required
string
Example: team-a-readers

vault policy name

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "document": "{\"path\":{\"secrets/team-a/*\":{\"capabilities\":[\"read\",\"list\"]}}}"
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "team-a-readers",
    • "type": "secret_vault_policy",
    • "attributes": {
      • "name": "team-a-readers",
      • "rules": [
        ],
      • "document": "{\"path\":{\"secrets/team-a/*\":{\"capabilities\":[\"read\",\"list\"]}}}",
      • "format": "json",
      • "original_document": null,
      • "modified": null,
      • "version": null
      }
    }
}

Delete a secret vault policy

Deletes an ACL policy from the bundled secret vault.

Notes:

  • Deleting a vault policy requires superuser access. No authorisation rule grants it.
  • The default and root policies, and the policies OpsChain owns (those starting with opschain-), cannot be deleted.
  • Only available when OpsChain uses the bundled secret vault with LDAP authentication.
path Parameters
name
required
string
Example: team-a-readers

vault policy name

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    • {
      • "status": 404,
      • "title": "Record not found",
      • "meta": {
        }
      }
    ]
}

List the saved versions of a secret vault policy

Lists the documents OpsChain has saved for an ACL policy in the bundled secret vault, newest first, with who saved each one and when. The list goes back to when the policy was last created - the versions of a deleted policy that had the same name are not included.

Notes:

  • Viewing a vault policy's versions requires superuser access. No authorisation rule grants it.
  • The versions come from the events OpsChain records when a policy is created or updated, so purging those events removes them. A policy changed in the vault without OpsChain has more vault versions than are listed.
  • The default and root policies, and the policies OpsChain owns (those starting with opschain-), cannot be viewed.
  • Only available when OpsChain uses the bundled secret vault with LDAP authentication.
path Parameters
name
required
string
Example: team-a-readers

vault policy name

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e731-1854-749d-aee5-aac603198a7d",
      • "type": "secret_vault_policy_version",
      • "attributes": {
        }
      }
    ]
}

Show the token signing key status

Shows when the key that signs access tokens, refresh tokens and API keys was last rotated, and how many previous keys OpsChain still accepts tokens from. The keys themselves are never returned.

Notes:

  • Requires superuser access. No authorisation rule grants it.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "0",
    • "type": "token_signing_key",
    • "attributes": {
      • "agents_on_previous_secret": 0,
      • "previous_key_count": 0,
      • "rotated_at": null,
      • "steps_on_previous_secret": 0
      },
    • "links": {
      • "self": "/api/admin/token_signing_key"
      }
    }
}

Rotate the token signing key

Replaces the key that signs access tokens, refresh tokens and API keys with a new random key. New tokens are signed with the new key straight away, on every site.

With compromised set to false, tokens signed with the previous key keep working until they expire, and OpsChain stops accepting the previous key once every token issued before the rotation has expired. Remote runner daemons are offered a new API key on their next poll.

With compromised set to true, OpsChain stops accepting every previous key at once. Every user is signed out, every API key stops working, running changes can no longer report their progress, and every remote runner target must be registered again.

Notes:

  • Requires superuser access. No authorisation rule grants it.
Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "compromised": false
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "0",
    • "type": "token_signing_key",
    • "attributes": {
      • "agents_on_previous_secret": 0,
      • "previous_key_count": 1,
      • "rotated_at": "2026-11-17T01:49:47.956Z",
      • "steps_on_previous_secret": 0
      },
    • "links": {
      • "self": "/api/admin/token_signing_key"
      }
    }
}

List the runner credentials

Lists the runner credentials, in code order. Filter by vault with filter[external_vault_code_eq]. The credentials themselves are never returned.

Notes:

  • Managing runner credentials requires superuser access. No authorisation rule grants it.
  • A node can carry one runner credential per vault. A change under a tagged node uses the credential of the deepest tag for the vault its settings assign, and is rejected when no tag above it has a credential for that vault. Secret references the system configuration supplies keep using the default runner account.
query Parameters
filter[external_vault_code_eq]
string

Only the credentials for the external vault with this code

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e732-9f66-783e-bee0-159085e4d1fd",
      • "type": "vault_runner_credential",
      • "attributes": {
        },
      • "meta": {
        }
      }
    ]
}

Create a runner credential

Creates a runner credential and tags it on nodes. A supplied credential holds a token, or a username and password, for the vault; OpsChain logs in to the vault with it before saving, and saves nothing when the vault cannot be reached or does not accept it. A managed credential (managed: true, bundled vault only) takes mount_paths instead: OpsChain writes a vault policy reaching those mounts and mints and renews the token itself.

Notes:

  • Managing runner credentials requires superuser access. No authorisation rule grants it.

  • A node can carry one runner credential per vault. A change under a tagged node uses the credential of the deepest tag for the vault its settings assign, and is rejected when no tag above it has a credential for that vault. Secret references the system configuration supplies keep using the default runner account.

  • The code, vault and managed cannot be changed later. Leave vault_code blank, or set it to bundled, for the bundled secret vault.

  • The credentials must be the values themselves. A secret-vault:// reference is rejected.

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "code": "team_runner",
      • "vault_code": "team_vault",
      • "managed": false,
      • "name": "Team runner",
      • "auth_method": "token",
      • "token": "hvs.runner-token",
      • "username": "runner",
      • "password": "runner-password",
      • "mount_paths": [
        ],
      • "node_paths": [
        ]
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e732-a0f7-7e61-8cc8-f4d5405e9d09",
    • "type": "vault_runner_credential",
    • "attributes": {
      • "code": "other_runner",
      • "name": "Other runner",
      • "vault_code": "team_vault",
      • "managed": false,
      • "auth_method": "token",
      • "mount_paths": [ ],
      • "node_paths": [
        ],
      • "token_configured": true,
      • "username_configured": false,
      • "password_configured": false,
      • "created_at": "2026-11-17T01:50:17.334642Z",
      • "updated_at": "2026-11-17T01:50:17.334642Z"
      },
    • "meta": {
      • "uncovered_vaults": [
        ]
      }
    }
}

Show a runner credential

Shows a runner credential. The credentials themselves are never returned.

Notes:

  • Managing runner credentials requires superuser access. No authorisation rule grants it.
  • A node can carry one runner credential per vault. A change under a tagged node uses the credential of the deepest tag for the vault its settings assign, and is rejected when no tag above it has a credential for that vault. Secret references the system configuration supplies keep using the default runner account.
path Parameters
id
required
string

runner credential id

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e732-a7fe-756a-ad68-9993e099d5a6",
    • "type": "vault_runner_credential",
    • "attributes": {
      • "code": "team_runner",
      • "name": "Team runner",
      • "vault_code": "team_vault",
      • "managed": false,
      • "auth_method": "token",
      • "mount_paths": [ ],
      • "node_paths": [
        ],
      • "token_configured": true,
      • "username_configured": false,
      • "password_configured": false,
      • "created_at": "2026-11-17T01:50:19.125150Z",
      • "updated_at": "2026-11-17T01:50:19.125150Z"
      },
    • "meta": {
      • "uncovered_vaults": [
        ]
      }
    }
}

Update a runner credential

Updates a runner credential. A credential left blank keeps the stored value, and node_paths, when given, replaces the tags. OpsChain logs in to the vault with the resulting credentials of a supplied credential before saving, and rewrites the vault policy of a managed one.

Notes:

  • Managing runner credentials requires superuser access. No authorisation rule grants it.

  • A node can carry one runner credential per vault. A change under a tagged node uses the credential of the deepest tag for the vault its settings assign, and is rejected when no tag above it has a credential for that vault. Secret references the system configuration supplies keep using the default runner account.

  • The code, vault and managed cannot be changed.

path Parameters
id
required
string

runner credential id

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "name": "Team runner",
      • "auth_method": "token",
      • "token": "hvs.runner-token",
      • "username": "runner",
      • "password": "runner-password",
      • "mount_paths": [
        ],
      • "node_paths": [
        ]
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e732-ad19-7e9b-b1ce-38b70e70b423",
    • "type": "vault_runner_credential",
    • "attributes": {
      • "code": "team_runner",
      • "name": "Renamed runner",
      • "vault_code": "team_vault",
      • "managed": false,
      • "auth_method": "token",
      • "mount_paths": [ ],
      • "node_paths": [
        ],
      • "token_configured": true,
      • "username_configured": false,
      • "password_configured": false,
      • "created_at": "2026-11-17T01:50:20.440460Z",
      • "updated_at": "2026-11-17T01:50:20.460248Z"
      },
    • "meta": {
      • "uncovered_vaults": [
        ]
      }
    }
}

Delete a runner credential

Deletes a runner credential and its tags. OpsChain revokes the token of a managed credential.

Notes:

  • Managing runner credentials requires superuser access. No authorisation rule grants it.
  • A node can carry one runner credential per vault. A change under a tagged node uses the credential of the deepest tag for the vault its settings assign, and is rejected when no tag above it has a credential for that vault. Secret references the system configuration supplies keep using the default runner account.
path Parameters
id
required
string

runner credential id

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    • {
      • "status": 404,
      • "title": "Record not found",
      • "meta": {
        }
      }
    ]
}

Data cleanup definitions

Endpoints to interact with data cleanup definitions.

List data cleanup definitions

Lists all data cleanup definitions.

query Parameters
filter[<query/sort filter>]=
string
Example: filter[<query/sort filter>]==> filter[name_eq]=test

API filtering guide. Named filters: filter[created_by_eq], filter[created_by_in].

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e72e-15af-7c06-9aec-207c1caba168",
      • "type": "data_cleanup_definition",
      • "attributes": {
        },
      • "links": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true,
      • "delete": true
      },
    • "has_any": true
    }
}

Create data cleanup definition

Notes:

  1. See the various payload examples to understand the required fields for each possible request to this endpoint.
  2. Exactly one of the cron_schedule or run_at fields must be provided.
  3. The keys accepted for the filters field are changes, events, audit_events, jobs, workflow_runs, node_background_tasks, template_versions, and artifacts. The agent image cleanup job accepts template_version_history and build_agent_image_tasks. Each of these can have ransack filters for the specific type they refer to, except artifacts, whose size_tiers shape is documented separately below. IMPORTANT: If no filters are provided for a data type, the cleanup will remove all data that matches the node paths.
  4. The node_paths field is an array of strings. Each string is a path to a node. The path must start with /projects and only contain forward slashes, lowercase letters, numbers and underscores, and optionally a single "%" at the end. Use the % wildcard to include all nodes under a specific node or node-type, note that this will apply the cleanup to all nodes that are yet to be created, as long as they match the path.
  5. The purge_node_background_tasks field removes finished node background tasks, along with their log lines and run API key tokens, once a newer task of the same type exists for the template version history. The latest successful and latest non cancelled generate actions requests, a mintmodel concretise task referenced by any generate actions request, tasks referenced by a change or an agent status, and build agent image tasks whose image has not yet been purged are always retained.
  6. The purge_artifacts field removes old artifact versions once they exceed a size-tiered retention policy, given via filters.artifacts.size_tiers: an array of { up_to, keep_versions, keep_days } objects, ordered by increasing size. up_to is a Kubernetes-style quantity string (e.g. "10Mi") giving the tier's inclusive upper size bound, or null for the catch-all tier covering anything larger. An artifact version is purged only once it both exceeds its own tier's keep_versions (ranked newest-first per node/code) and is older than its tier's keep_days. When purge_artifacts is true, filters.artifacts.size_tiers must contain at least one tier, otherwise the request is rejected with a 422 error on filters; it is optional when purge_artifacts is false. purge_artefacts and filters.artefacts are still accepted as aliases of purge_artifacts and filters.artifacts; when both spellings are supplied, the artifact one is used.
  7. The purge_system_data field removes the history of jobs that belong to no node, and the events that belong to no node or to the system configuration, using the jobs and events filters. Audit events are never removed. It ignores node_paths, and only a superuser can set it.
  8. The purge_audit_events field removes the audit events of the matching nodes, using the audit_events filters. No other purge removes audit events, so this one can keep them for longer than the other events. Only a superuser can set it.
  9. The archive_template_versions field archives the template versions of the matching nodes' templates that have been unused for filters.template_versions.unused_for_days days: not created, used by a change or assigned to an asset in that time. A version is never archived while an asset points at it (archived assets included), an unfinished change uses it, it is locked, or an unarchived version of an unarchived workflow names a template version with the same name. Archived versions keep their name reserved. filters.template_versions.unused_for_days is required and must be a whole number of days from 1 to 365, otherwise the request is rejected with a 422 error on filters. filters.template_versions.keep_latest keeps the newest N versions of each template by creation date, counting versions in use, and the other template_versions keys are ransack filters. Use the template_versions_preview endpoint to list the versions a definition would archive.
  10. The analyze_statistics field refreshes the PostgreSQL planner statistics of any table whose statistics are stale, after the purges have run. It applies to the whole database, so the node_paths and filters fields are ignored for it.
Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
Example
{
  • "data": {
    • "attributes": {
      • "name": "feed",
      • "enabled": true,
      • "node_paths": [ ],
      • "filters": { },
      • "purge_activities": false,
      • "purge_events": true,
      • "purge_jobs": false,
      • "cron_schedule": "0 0 * * *",
      • "run_at": null,
      • "end_at": null,
      • "maximum_run_count": null,
      • "repeat": true,
      • "purge_agent_images": true,
      • "purge_node_background_tasks": false,
      • "analyze_statistics": true,
      • "purge_system_data": false,
      • "purge_audit_events": false,
      • "archive_template_versions": false,
      • "purge_artifacts": false
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72e-4bc7-7b98-b522-660264db9801",
    • "type": "data_cleanup_definition",
    • "attributes": {
      • "name": "circuit",
      • "enabled": true,
      • "created_by": "logged_in_user",
      • "created_by_name": "logged_in_user",
      • "cron_schedule": "0 2 * * *",
      • "repeat": true,
      • "maximum_run_count": null,
      • "purge_activities": true,
      • "purge_events": true,
      • "purge_jobs": true,
      • "purge_agent_images": false,
      • "purge_node_background_tasks": false,
      • "purge_artifacts": false,
      • "purge_system_data": false,
      • "purge_audit_events": false,
      • "archive_template_versions": false,
      • "analyze_statistics": true,
      • "filters": {
        },
      • "node_paths": [ ],
      • "run_count": 0,
      • "created_at": "2026-11-17T01:45:33.382477Z",
      • "updated_at": "2026-11-17T01:45:33.382477Z",
      • "next_run_at": "2026-11-17T15:00:00.000000Z",
      • "run_at": null,
      • "end_at": null
      },
    • "links": {
      • "self": "/api/data_cleanup_definitions/01a1e72e-4bc7-7b98-b522-660264db9801"
      }
    },
  • "meta": {
    • "authorisations": {
      • "update": true,
      • "delete": true
      }
    }
}

Preview an artefact retention policy

Reports how many artefact versions, and how many bytes, a purge_artifacts retention policy would purge for the supplied node paths and size tiers, without purging anything.

Notes:

  1. The node_paths and filters.artifacts.size_tiers attributes have the same shape and validation as when creating a data cleanup definition with purge_artifacts set to true. filters.artefacts is still accepted as an alias of filters.artifacts.
  2. At least one size tier is required.
  3. The counts are those that a purge run at the time of the request would remove: a version is counted only if it is beyond its tier's keep_versions newest versions per node and artefact code, and is older than its tier's keep_days.
  4. The result is returned in the top level meta object. meta.tiers lists each tier, in order of increasing size, with the versions and bytes it would purge. meta.totals sums them across all tiers.
  5. This endpoint requires the same authorisation as creating a data cleanup definition.
Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "node_paths": [
        ],
      • "filters": {
        }
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": null,
  • "meta": {
    • "tiers": [
      • {
        },
      • {
        }
      ],
    • "totals": {
      • "versions": 0,
      • "bytes": 0
      }
    }
}

Preview a template version archive

Lists the template versions an archive_template_versions data cleanup definition would archive for the supplied node paths and filters, without archiving anything.

Notes:

  1. The node_paths and filters.template_versions attributes have the same shape and validation as when creating a data cleanup definition with archive_template_versions set to true.
  2. The result is returned in the top level meta object. meta.template_versions lists the path of each version that a run at the time of the request would archive, and meta.total counts them.
  3. This endpoint requires the same authorisation as creating a data cleanup definition.
Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "node_paths": [
        ],
      • "filters": {
        }
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": null,
  • "meta": {
    • "template_versions": [ ],
    • "total": 0
    }
}

Show a data cleanup definition

Shows a data cleanup definition.

path Parameters
data_cleanup_definition_id
required
string
Example: 01a1e72b-1057-7278-80db-bacc995147d8

data cleanup definition id

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72e-78c8-7c91-838b-0881e8fb6db9",
    • "type": "data_cleanup_definition",
    • "attributes": {
      • "name": "capacitor",
      • "enabled": true,
      • "created_by": "jimmy_powlowski-1812",
      • "created_by_name": "jimmy_powlowski-1812",
      • "cron_schedule": "0 0 7,14,21,28 * *",
      • "repeat": true,
      • "maximum_run_count": null,
      • "purge_activities": true,
      • "purge_events": false,
      • "purge_jobs": false,
      • "purge_agent_images": false,
      • "purge_node_background_tasks": true,
      • "purge_artifacts": false,
      • "purge_system_data": false,
      • "purge_audit_events": false,
      • "archive_template_versions": false,
      • "analyze_statistics": false,
      • "filters": {
        },
      • "node_paths": [
        ],
      • "run_count": 0,
      • "created_at": "2026-11-17T01:45:44.903241Z",
      • "updated_at": "2026-11-17T01:45:44.903241Z",
      • "next_run_at": "2026-11-20T13:00:00.000000Z",
      • "run_at": null,
      • "end_at": "2027-02-15T01:45:44.818337Z"
      },
    • "links": {
      • "self": "/api/data_cleanup_definitions/01a1e72e-78c8-7c91-838b-0881e8fb6db9"
      }
    },
  • "meta": {
    • "authorisations": {
      • "update": true,
      • "delete": true
      }
    }
}

Update the data cleanup definition

Updates a data cleanup definition.

Notes:

  1. See the various payload examples in the create endpoint to understand the attributes you can supply to this endpoint.
  2. The payload need only consist of the attributes you wish to modify. There is no need to supply the entire data cleanup definition.
  3. Supplying only one of cron_schedule or run_at switches the definition to that type of schedule and clears the other. Supplying run_at also clears end_at and maximum_run_count and resets repeat to false, unless they are supplied too. Switching from one type to the other also resets run_count to 0.
path Parameters
data_cleanup_definition_id
required
string
Example: 01a1e72b-1057-7278-80db-bacc995147d8

data cleanup definition id

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
Example
{
  • "data": {
    • "attributes": {
      • "name": "new_name",
      • "run_at": null,
      • "end_at": null
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72e-80e6-783d-b5da-a1b4ee8f8024",
    • "type": "data_cleanup_definition",
    • "attributes": {
      • "name": "new_name",
      • "enabled": true,
      • "created_by": "emeline.hilpert-1822",
      • "created_by_name": "emeline.hilpert-1822",
      • "cron_schedule": "0 0 7,14,21,28 * *",
      • "repeat": true,
      • "maximum_run_count": 5,
      • "purge_activities": false,
      • "purge_events": true,
      • "purge_jobs": false,
      • "purge_agent_images": false,
      • "purge_node_background_tasks": true,
      • "purge_artifacts": false,
      • "purge_system_data": false,
      • "purge_audit_events": false,
      • "archive_template_versions": false,
      • "analyze_statistics": false,
      • "filters": {
        },
      • "node_paths": [
        ],
      • "run_count": 0,
      • "created_at": "2026-11-17T01:45:46.980664Z",
      • "updated_at": "2026-11-17T01:45:47.238610Z",
      • "next_run_at": "2026-11-20T13:00:00.000000Z",
      • "run_at": null,
      • "end_at": "2027-02-15T01:45:46.835463Z"
      },
    • "links": {
      • "self": "/api/data_cleanup_definitions/01a1e72e-80e6-783d-b5da-a1b4ee8f8024"
      }
    },
  • "meta": {
    • "authorisations": {
      • "update": true,
      • "delete": true
      }
    }
}

Delete the data cleanup definition

Delete a data cleanup definition.

path Parameters
data_cleanup_definition_id
required
string
Example: 01a1e72b-1057-7278-80db-bacc995147d8

data cleanup definition id

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    • {
      • "status": 403,
      • "title": "You do not have permission to delete the data cleanup definition",
      • "detail": "Your authorisation rules let you view the data cleanup definition but not delete it."
      }
    ]
}

Remote runner targets

Endpoints to manage the remote runner targets that run steps and change workers outside the OpsChain cluster.

List remote runner targets

Lists the remote runner targets the caller can read. Include remote_runner_target_scopes to return the node paths each target serves.

query Parameters
include
string
Example: include=remote_runner_target_scopes

Related resources to include

filter[<query/sort filter>]=
string
Example: filter[<query/sort filter>]==> filter[code_cont]=dc1

API filtering guide. Named filters: filter[created_by_eq], filter[created_by_in].

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "id": "01a1e730-ba05-718d-ad64-fb24bf3ed736",
      • "type": "remote_runner_target",
      • "attributes": {
        },
      • "relationships": {
        },
      • "links": {
        },
      • "meta": {
        }
      }
    ],
  • "included": [
    • {
      • "id": "01a1e730-ba10-764c-bef2-9fd4640753c8",
      • "type": "remote_runner_target_scope",
      • "attributes": {
        }
      }
    ],
  • "meta": {
    • "authorisations": {
      • "update": true
      },
    • "partial_response": false
    }
}

Create remote runner target

Creates a remote runner target. The response meta.bearer_token holds the token the remote runner daemon authenticates with; it is only returned by this request.

Notes:

  1. Omit node_id to create an instance-wide target (superuser only).
  2. scope_paths restricts the target to the listed node paths. Include remote_runner_target_scopes to return them in the response.
query Parameters
include
string
Example: include=remote_runner_target_scopes

Related resources to include

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "code": "dc2_runner",
      • "description": "Runner in the DC2 network",
      • "public_key": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----\n",
      • "client_certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n",
      • "node_id": "01a1e72a-f049-77ab-992b-01351732a1a3",
      • "scope_paths": [
        ]
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e730-bc3f-7fbc-a8b2-f22d64137b89",
    • "type": "remote_runner_target",
    • "attributes": {
      • "code": "dc2_runner",
      • "description": "Runner in the DC2 network",
      • "maintenance_mode": false,
      • "daemon_version": null,
      • "daemon_protocols": null,
      • "daemon_upgrade_allowed": null,
      • "daemon_status": "unknown",
      • "auto_upgrade": null,
      • "daemon_upgrade_error": null,
      • "effective_auto_upgrade": false,
      • "drained": false,
      • "live": false,
      • "key_rotation_overdue": false,
      • "bundled_daemon_version": "0.1.0.28",
      • "created_at": "2026-11-17T01:48:13.246734Z",
      • "updated_at": "2026-11-17T01:48:13.246734Z",
      • "last_connected_at": null,
      • "key_expires_at": "2027-11-17T23:59:59.999999Z",
      • "daemon_reported_at": null,
      • "upgrade_requested_at": null,
      • "upgrade_offered_at": null
      },
    • "relationships": {
      • "settings": {
        },
      • "node": {
        },
      • "remote_runner_target_scopes": {
        }
      },
    • "links": {
      • "self": "/api/remote_runner_targets/01a1e730-bc3f-7fbc-a8b2-f22d64137b89"
      },
    • "meta": {
      • "bearer_token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIwMWExZTczMC1iYzUxLTdkY2EtYTdmMi05ZTQ4ZjYzZjFlNWQiLCJpc3MiOiJPcHNDaGFpbiIsImF1ZCI6Im9wc2NoYWluX2FwaSIsImV4cCI6MTgyNjQ5NTk5OSwiaWF0IjoxNzk0ODgwMDkzfQ.DbjLK4UomIUgCwI_wcU8H-7RB9uaKE_ZOq1-cOEWw_8"
      }
    },
  • "included": [
    • {
      • "id": "01a1e730-bc4c-7156-b7cb-c34da1a5b87b",
      • "type": "remote_runner_target_scope",
      • "attributes": {
        }
      }
    ]
}

Show remote runner target

Shows a remote runner target. Include remote_runner_target_scopes to return the node paths it serves.

path Parameters
target_id
required
string
Example: 01a1e72b-1655-7e2f-8a63-156847f4afe0

remote runner target id

query Parameters
include
string
Example: include=remote_runner_target_scopes

Related resources to include

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e730-c67e-7a4e-9f8b-6199553172da",
    • "type": "remote_runner_target",
    • "attributes": {
      • "code": "dc1_runner",
      • "description": "Runner in the DC1 network",
      • "maintenance_mode": false,
      • "daemon_version": null,
      • "daemon_protocols": null,
      • "daemon_upgrade_allowed": null,
      • "daemon_status": "unknown",
      • "auto_upgrade": null,
      • "daemon_upgrade_error": null,
      • "effective_auto_upgrade": false,
      • "drained": false,
      • "live": true,
      • "key_rotation_overdue": false,
      • "bundled_daemon_version": "0.1.0.28",
      • "created_at": "2026-11-17T01:48:15.869425Z",
      • "updated_at": "2026-11-17T01:48:15.869425Z",
      • "last_connected_at": "2026-11-17T01:48:15.665320Z",
      • "key_expires_at": null,
      • "daemon_reported_at": null,
      • "upgrade_requested_at": null,
      • "upgrade_offered_at": null
      },
    • "relationships": {
      • "settings": {
        },
      • "node": {
        },
      • "remote_runner_target_scopes": {
        }
      },
    • "links": {
      • "self": "/api/remote_runner_targets/01a1e730-c67e-7a4e-9f8b-6199553172da"
      },
    • "meta": {
      • "authorisations": {
        }
      }
    },
  • "included": [
    • {
      • "id": "01a1e730-c68a-75ef-8f52-94aa246fe69d",
      • "type": "remote_runner_target_scope",
      • "attributes": {
        }
      }
    ]
}

Update remote runner target

Updates a remote runner target's description, maintenance mode or scopes.

Only the scope paths being added are checked for existence and authorisation; scopes that are kept or removed are not.

path Parameters
target_id
required
string
Example: 01a1e72b-1655-7e2f-8a63-156847f4afe0

remote runner target id

query Parameters
include
string
Example: include=remote_runner_target_scopes

Related resources to include

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "description": "Runner in the DC1 network",
      • "maintenance_mode": true,
      • "auto_upgrade": true,
      • "scope_paths": [
        ]
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e730-caa0-738b-a32d-d51a539f045b",
    • "type": "remote_runner_target",
    • "attributes": {
      • "code": "dc1_runner",
      • "description": "Runner in the DC1 network",
      • "maintenance_mode": true,
      • "daemon_version": null,
      • "daemon_protocols": null,
      • "daemon_upgrade_allowed": null,
      • "daemon_status": "unknown",
      • "auto_upgrade": null,
      • "daemon_upgrade_error": null,
      • "effective_auto_upgrade": false,
      • "drained": true,
      • "live": true,
      • "key_rotation_overdue": false,
      • "bundled_daemon_version": "0.1.0.28",
      • "created_at": "2026-11-17T01:48:16.927090Z",
      • "updated_at": "2026-11-17T01:48:16.975751Z",
      • "last_connected_at": "2026-11-17T01:48:16.757953Z",
      • "key_expires_at": null,
      • "daemon_reported_at": null,
      • "upgrade_requested_at": null,
      • "upgrade_offered_at": null
      },
    • "relationships": {
      • "settings": {
        },
      • "node": {
        },
      • "remote_runner_target_scopes": {
        }
      },
    • "links": {
      • "self": "/api/remote_runner_targets/01a1e730-caa0-738b-a32d-d51a539f045b"
      },
    • "meta": null
    },
  • "included": [
    • {
      • "id": "01a1e730-caaf-7483-817a-aed5f9b8475e",
      • "type": "remote_runner_target_scope",
      • "attributes": {
        }
      }
    ]
}

Delete remote runner target

Deletes a remote runner target. Work it has not yet claimed is left for another eligible target.

path Parameters
target_id
required
string
Example: 01a1e72b-1655-7e2f-8a63-156847f4afe0

remote runner target id

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    • {
      • "status": 403,
      • "title": "You do not have permission to delete the remote runner target",
      • "detail": "Your authorisation rules let you view the remote runner target but not delete it."
      }
    ]
}

Request a remote runner daemon upgrade

Asks the target's daemon to upgrade itself to the build bundled in this OpsChain version; the daemon is offered the build on its next poll. Requires update access to the target. Fails with upgrade_not_available unless the daemon is outdated or incompatible and its host allows upgrades.

path Parameters
target_id
required
string
Example: 01a1e72b-1655-7e2f-8a63-156847f4afe0

remote runner target id

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e730-dd8a-7c2d-9ff6-819a5bb47174",
    • "type": "remote_runner_target",
    • "attributes": {
      • "code": "dc1_runner",
      • "description": "Runner in the DC1 network",
      • "maintenance_mode": false,
      • "daemon_version": "0.0.1",
      • "daemon_protocols": null,
      • "daemon_upgrade_allowed": true,
      • "daemon_status": "outdated",
      • "auto_upgrade": null,
      • "daemon_upgrade_error": null,
      • "effective_auto_upgrade": false,
      • "drained": false,
      • "live": true,
      • "key_rotation_overdue": false,
      • "bundled_daemon_version": "0.1.0.5",
      • "created_at": "2026-11-17T01:48:21.769513Z",
      • "updated_at": "2026-11-17T01:48:21.841799Z",
      • "last_connected_at": "2026-11-17T01:48:21.533279Z",
      • "key_expires_at": null,
      • "daemon_reported_at": "2026-11-17T01:48:21.798107Z",
      • "upgrade_requested_at": "2026-11-17T01:48:21.823234Z",
      • "upgrade_offered_at": null
      },
    • "relationships": {
      • "settings": {
        },
      • "node": {
        },
      • "remote_runner_target_scopes": {
        }
      },
    • "links": {
      • "self": "/api/remote_runner_targets/01a1e730-dd8a-7c2d-9ff6-819a5bb47174"
      },
    • "meta": null
    }
}

Download the remote runner daemon archive

Downloads the remote runner daemon archive bundled in this OpsChain build, used to install the daemon on the target's host. Requires the same access as showing the target. The X-Checksum-Sha256 response header holds the archive's SHA-256 checksum.

path Parameters
target_id
required
string
Example: 01a1e72b-1655-7e2f-8a63-156847f4afe0

remote runner target id

Responses

Response samples

Content type
application/gzip
<binary data>

Download the remote runner simple-mode disk image

Downloads the simple-mode disk image (simple-mode.raw.zst) bundled in this OpsChain build, used to set up a simple-mode remote runner host. Requires the same access as showing the target. The X-Checksum-Sha256 response header holds the file's SHA-256 checksum.

path Parameters
target_id
required
string
Example: 01a1e72b-1655-7e2f-8a63-156847f4afe0

remote runner target id

Responses

Response samples

Content type
application/zstd
<binary data>

Download the remote runner simple-mode systemd unit

Downloads the simple-mode systemd unit (opschain-remote-runner.service) bundled in this OpsChain build, used to set up a simple-mode remote runner host. Requires the same access as showing the target. The X-Checksum-Sha256 response header holds the file's SHA-256 checksum.

path Parameters
target_id
required
string
Example: 01a1e72b-1655-7e2f-8a63-156847f4afe0

remote runner target id

Responses

Response samples

Content type
text/plain
<binary data>

Compare changes

Compare two changes

Compares two changes to help explain why one failed and the other succeeded: their run options, commits, settings and properties snapshots, templates, step trees, failing steps and logs, artifacts, the changes that ran alongside each, and what was updated between the two runs. Secret values are never returned. Both changes must have been created under a release that records the snapshots the comparison needs.

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "change_id_a": "01c5c541-d408-42dc-b336-c280d71f0c76",
      • "change_id_b": "225cd605-4de5-4518-baba-e6818795b949"
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "01a1e72d-e97e-7d93-9881-8bbe26dcfbfd:01a1e72d-ea27-78dd-bf06-9510c8395b22",
    • "type": "change_comparison",
    • "attributes": {
      • "changes": {
        },
      • "run_options": {
        },
      • "commit": {
        },
      • "settings": {
        },
      • "override_settings": {
        },
      • "override_properties": {
        },
      • "properties": {
        },
      • "template": {
        },
      • "failure": {
        },
      • "logs": {
        },
      • "artifacts": {
        },
      • "concurrency": {
        },
      • "between_runs": {
        },
      • "remote_runner": {
        },
      • "resource_usage": {
        },
      • "step_tree": {
        }
      },
    • "meta": {
      • "warnings": [ ]
      }
    }
}

Compare nodes

Compare two nodes

Extracts the converged properties, converged settings, and relevant asset MintModel for the two nodes supplied. Also includes environments and assets summaries, and most recent change for each node.

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "node_path_a": "/projects/opc/environments/dev/assets/env_soa",
      • "node_path_b": "/projects/opc/assets/prj_soa"
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "env_soa:prj_soa",
    • "type": "node_comparison",
    • "attributes": {
      • "nodes": {
        },
      • "properties": {
        },
      • "mintmodel": {
        },
      • "environments": {
        },
      • "assets": {
        },
      • "agents": {
        },
      • "settings": {
        }
      }
    }
}