Integrate external systems with the REST API

Manage workflows and executions programmatically by integrating with the REST API from external systems.

Before you begin

  • A running automation orchestrator instance is accessible from your integration environment.
  • You have valid credentials: local password login, an OpenID Connect (OIDC) identity provider, or a service account with client credentials.
  • You know the project ID for the project where you want to manage workflows. You can retrieve available projects by sending a GET request to /api/v1/projects.
  • You have the required role-based access control (RBAC) permissions for the operations you intend to perform. At minimum, you need workflow:create, workflow:read, and execution:run permissions within the target project.

Procedure

  1. Authenticate and obtain an access token.

    Authenticate with the REST API to obtain a JSON Web Token (JWT) access token. Include the access token in the Authorization header of all subsequent requests:

    Authorization: Bearer jwt_access_token

    For long-running integrations, implement token refresh logic by calling POST /api/v1/auth/refresh with the ao_refresh_token cookie. For service accounts, use the OAuth 2.0 client credentials grant at POST /api/v1/auth/token.

  2. Create a workflow definition.

    Send a POST request to create a workflow. Include project_id and workflow_definition in the request body:

    POST /api/v1/workflows
  Content-Type: application/json
  Authorization: Bearer jwt_access_token

  {
    "name": "my-cicd-workflow",
    "description": "Workflow triggered by CI/CD pipeline",
    "project_id": "project_id",
    "workflow_definition": {
      "name": "my-cicd-workflow",
      "schema_version": "2.0.0",
      "triggers": [{"type": "manual"}],
      "nodes": [],
      "edges": []
    }
  }

    The workflow_definition field is required. It must include schema_version (must be "2.0.0"), name (1-255 characters), triggers (at least one entry), nodes (list, can be empty), and edges (list, can be empty). The description field inside workflow_definition is optional. Unknown fields return HTTP 422.

    A successful response returns HTTP status 201 Created with the created workflow, including its id and the initial draft version. Save the workflow id for use in subsequent requests.

  3. Publish the workflow version.

    Send a POST request to publish the current draft version. Replace workflow_id with the workflow ID from the previous step, and version with the integer version number:

    POST /api/v1/workflows/workflow_id/versions/version/publish
  Content-Type: application/json
  Authorization: Bearer jwt_access_token

  {
    "publish_name": "Initial release",
    "change_description": "First published version for CI/CD integration"
  }

    The request body is optional. If omitted, the version is published without a name or change description.

  4. Trigger a workflow execution.

    Send a POST request to create an execution of the published workflow:

    POST /api/v1/executions
  Content-Type: application/json
  Authorization: Bearer jwt_access_token

  {
    "workflow_id": "workflow_id",
    "trigger_node_id": "trigger_node_id  ",
    "use_published": true,
    "input_data": {
      "environment": "staging",
      "deploy_version": "2.1.0"
    }
  }

    Both workflow_id and trigger_node_id are required. The input_data field is optional and defaults to an empty object. To find the trigger node ID, retrieve the workflow version with GET /api/v1/workflows/workflow_id/versions/version and locate the trigger node id in the workflow_definition.triggers array.

    Set use_published to true to execute the published version instead of the current draft version. It defaults to false.

    Note
    Set use_published: true when triggering workflows from external systems. This ensures the API runs the published version and respects workflow publication status. If you omit use_published or set it to false, the API runs the current draft version instead. Unpublishing the workflow does not block execution.

    A successful response returns HTTP status 201 Created with the execution id and initial status. Save the execution id for use in the polling step.

  5. Poll the execution status.

    Send GET requests to monitor the execution progress. Replace execution_id with the execution ID from the previous step:

    GET /api/v1/executions/execution_id
  Authorization: Bearer jwt_access_token

    Continue polling until the status field reaches a terminal state: completed, completed_with_errors, failed, or cancelled.

    Tip

    For real-time updates without polling, connect to the WebSocket endpoint at /ws/workflows/v1/executions/execution_id.
  6. Retrieve execution activity details.

    To view the results of individual nodes within the execution, list the activity executions:

    GET /api/v1/executions/execution_id/activities
  Authorization: Bearer jwt_access_token

    The response includes an array of activity execution records, each with its own status, outputs, and timing information.

  7. Optional: Export the workflow definition.

    To export the full workflow definition for a specific version:

    GET /api/v1/workflows/workflow_id/versions/version/export
  Authorization: Bearer jwt_access_token

    You can use the exported definition to replicate the workflow in another project or environment.

Results

You have completed the full workflow lifecycle through the REST API: authentication, workflow creation, publishing, execution, status monitoring, and result retrieval. You can now adapt these API calls to your CI/CD pipeline, ITSM integration, or automation scripts. To verify, confirm that the final execution status is completed.