Workflows

Workflows are event-driven automations that execute actions when specific events occur in sphere-core. Define trigger conditions, chain multiple actions, and monitor execution history through a dedicated API.

The workflow model

Workflows consist of a trigger event, a set of conditions that must be met, and a list of actions to execute when triggered.

Properties

Name
id
Type
string (UUID)
Description
Unique identifier for the workflow.
Name
name
Type
string
Description
Human-readable name for the workflow.
Name
description
Type
string
Description
Optional description explaining the workflow's purpose.
Name
trigger_event
Type
string
Description
The event that triggers this workflow (e.g., entity.created, entity.updated, entity.deleted).
Name
conditions
Type
array
Description
List of conditions that must all be met for the workflow to execute. Each condition has field, operator, and value.
Name
actions
Type
array
Description
List of actions to execute when the workflow triggers. Each action has a type and a config object.
Name
is_active
Type
boolean
Description
Whether the workflow is currently active and will respond to trigger events.
Name
created_at
Type
string (ISO 8601)
Description
Timestamp when the workflow was created.

GET/core/api/v1/workflows

List workflows

Retrieve a paginated list of all workflows for the current tenant. Results are ordered by creation date descending.

Request

GET

/core/api/v1/workflows

curl https://your-sphere.example.com/core/api/v1/workflows \
  -H "Authorization: Bearer {access_token}"

Response

{
  "data": [
    {
      "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "name": "Auto-assign on creation",
      "description": "Automatically assign new entities to the default workspace member",
      "trigger_event": "entity.created",
      "conditions": [
        {
          "field": "family_code",
          "operator": "equals",
          "value": "contacts"
        }
      ],
      "actions": [
        {
          "type": "update_field",
          "config": {
            "field": "assigned_to",
            "value": "{{current_user}}"
          }
        }
      ],
      "is_active": true,
      "created_at": "2026-01-15T10:30:00Z"
    }
  ]
}

POST/core/api/v1/workflows

Create workflow

Create a new workflow automation. The workflow is created in an inactive state by default. Use the activate endpoint to enable it.

Required attributes

Name
name
Type
string
Description
A descriptive name for the workflow.
Name
trigger_event
Type
string
Description
The event that triggers this workflow. Common values: entity.created, entity.updated, entity.deleted.
Name
actions
Type
array
Description
At least one action to execute. Each action requires a type (e.g., update_field, send_notification, create_entity) and a config object with action-specific parameters.

Optional attributes

Name
description
Type
string
Description
A human-readable description of what this workflow does.
Name
conditions
Type
array
Description
Conditions that must all be met for the workflow to execute. Each condition requires field, operator (e.g., equals, not_equals, contains, greater_than), and value.

Request

POST

/core/api/v1/workflows

curl -X POST https://your-sphere.example.com/core/api/v1/workflows \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Auto-assign on creation",
    "trigger_event": "entity.created",
    "conditions": [
      {
        "field": "family_code",
        "operator": "equals",
        "value": "contacts"
      }
    ],
    "actions": [
      {
        "type": "update_field",
        "config": {
          "field": "assigned_to",
          "value": "{{current_user}}"
        }
      }
    ]
  }'

Response (201 Created)

{
  "data": {
    "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "name": "Auto-assign on creation",
    "description": null,
    "trigger_event": "entity.created",
    "conditions": [
      {
        "field": "family_code",
        "operator": "equals",
        "value": "contacts"
      }
    ],
    "actions": [
      {
        "type": "update_field",
        "config": {
          "field": "assigned_to",
          "value": "{{current_user}}"
        }
      }
    ],
    "is_active": false,
    "created_at": "2026-01-15T10:30:00Z"
  }
}

GET/core/api/v1/workflows/{id}

Get workflow

Retrieve the full details of a specific workflow by its ID.

Request

GET

/core/api/v1/workflows/{id}

curl https://your-sphere.example.com/core/api/v1/workflows/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d \
  -H "Authorization: Bearer {access_token}"

Response

{
  "data": {
    "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "name": "Auto-assign on creation",
    "description": "Automatically assign new entities to the default workspace member",
    "trigger_event": "entity.created",
    "conditions": [
      {
        "field": "family_code",
        "operator": "equals",
        "value": "contacts"
      }
    ],
    "actions": [
      {
        "type": "update_field",
        "config": {
          "field": "assigned_to",
          "value": "{{current_user}}"
        }
      }
    ],
    "is_active": true,
    "created_at": "2026-01-15T10:30:00Z"
  }
}

PATCH/core/api/v1/workflows/{id}

Update workflow

Update an existing workflow. Only the fields you include in the request body will be modified. Active workflows can be updated without deactivating them first.

Optional attributes

Name
name
Type
string
Description
Updated name for the workflow.
Name
description
Type
string
Description
Updated description.
Name
trigger_event
Type
string
Description
Updated trigger event.
Name
conditions
Type
array
Description
Updated list of conditions. Replaces the entire conditions array.
Name
actions
Type
array
Description
Updated list of actions. Replaces the entire actions array.

Request

PATCH

/core/api/v1/workflows/{id}

curl -X PATCH https://your-sphere.example.com/core/api/v1/workflows/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Auto-assign contacts on creation",
    "description": "Updated: assigns to current user when a contact is created"
  }'

Response

{
  "data": {
    "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "name": "Auto-assign contacts on creation",
    "description": "Updated: assigns to current user when a contact is created",
    "trigger_event": "entity.created",
    "conditions": [
      {
        "field": "family_code",
        "operator": "equals",
        "value": "contacts"
      }
    ],
    "actions": [
      {
        "type": "update_field",
        "config": {
          "field": "assigned_to",
          "value": "{{current_user}}"
        }
      }
    ],
    "is_active": true,
    "created_at": "2026-01-15T10:30:00Z"
  }
}

DELETE/core/api/v1/workflows/{id}

Delete workflow

Permanently delete a workflow. This action cannot be undone. The workflow's execution history is retained for audit purposes.

Request

DELETE

/core/api/v1/workflows/{id}

curl -X DELETE https://your-sphere.example.com/core/api/v1/workflows/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d \
  -H "Authorization: Bearer {access_token}"

Response (204 No Content)

// No response body

POST/core/api/v1/workflows/{id}/activate

Activate workflow

Activate a workflow so it begins responding to its trigger event. Only inactive workflows can be activated. This endpoint accepts no request body.

Request

POST

/core/api/v1/workflows/{id}/activate

curl -X POST https://your-sphere.example.com/core/api/v1/workflows/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d/activate \
  -H "Authorization: Bearer {access_token}"

Response

{
  "data": {
    "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "name": "Auto-assign on creation",
    "is_active": true
  }
}

POST/core/api/v1/workflows/{id}/deactivate

Deactivate workflow

Deactivate a workflow so it stops responding to its trigger event. The workflow configuration is preserved and can be reactivated later. This endpoint accepts no request body.

Request

POST

/core/api/v1/workflows/{id}/deactivate

curl -X POST https://your-sphere.example.com/core/api/v1/workflows/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d/deactivate \
  -H "Authorization: Bearer {access_token}"

Response

{
  "data": {
    "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "name": "Auto-assign on creation",
    "is_active": false
  }
}

GET/core/api/v1/workflows/{id}/runs

List workflow runs

Retrieve the execution history for a specific workflow. Each run represents a single time the workflow was triggered and executed. Use this to monitor workflow performance and debug failed executions.

Request

GET

/core/api/v1/workflows/{id}/runs

curl https://your-sphere.example.com/core/api/v1/workflows/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d/runs \
  -H "Authorization: Bearer {access_token}"

Response

{
  "data": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "workflow_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "trigger_event_id": "a1b2c3d4-5678-9012-abcd-ef0123456789",
      "status": "completed",
      "started_at": "2026-01-20T14:22:10Z",
      "completed_at": "2026-01-20T14:22:11Z",
      "actions_executed": 1
    },
    {
      "id": "e8b2c5a1-9f3d-4e7b-8c6a-1d2e3f4a5b6c",
      "workflow_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "trigger_event_id": "b2c3d4e5-6789-0123-bcde-f01234567890",
      "status": "failed",
      "started_at": "2026-01-20T15:10:05Z",
      "completed_at": "2026-01-20T15:10:06Z",
      "actions_executed": 0
    }
  ]
}