Automations API

Automations is the platform’s reaction layer: it listens for domain events and schedules, matches them to trigger nodes, and executes directed graphs of conditions, switches, actions, and waits. Projects are zero-trust federated zones, automations are child boundaries inside them, and action dispatch runs under the automation’s IAM principal. The registry lists event types, action types, and operators contributed by services; this service also contributes `automations.schedule.fired`, `automations.manual.invoked`, and the `automations.set_variable` ("Set value") action. Generic outbound HTTP is provided by the compute service's `compute.http.request` action.

Base URL/api/v1/automations

Automation triggers: view every Automations event, payload field, and predicate.

Projects

Top-level folders in the Studio hierarchy. Each project belongs to one organization and contains automations. Deleting a project requires that it have no live automations.

GET/api/v1/automations/projects

List Projects

List automation projects for the authenticated organization with cursor pagination. Optional case-insensitive name filter.

Bearer token required. IAM permission `automations:projects:view` on `org/{company_id}`.

Query Parameters

Name	Type	Description
`limit`	integer	Page size (1–200, default 50)
`cursor`	string \| null	Opaque pagination cursor from a prior response
`name`	string \| null	Case-insensitive substring filter on project name

Response Fields

Name	Type	Description
`items`*	ProjectOut[]	Project rows including automation_count
`next_cursor`*	string \| null	Cursor for the next page, or null

curl "https://platform.ergondata.ai/api/v1/automations/projects?limit=50" \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "items": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
      "name": "Revenue ops",
      "description": "Customer-facing automations",
      "created_by_principal_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T10:30:00Z",
      "deleted_at": null,
      "automation_count": 3
    }
  ],
  "next_cursor": null
}

POST/api/v1/automations/projects

Create Project

Create a new automation project. Duplicate names in the same organization return 409.

Bearer token required. IAM permission `automations:projects:create` on `org/{company_id}`.

Request Body

Name	Type	Description
`name`*	string	Display name (1–200 chars)
`description`	string \| null	Optional description

Response Fields

Name	Type	Description
`id`*	UUID	Project ID
`company_id`*	UUID	Organization ID
`name`*	string	Name
`description`*	string \| null	Description
`created_by_principal_id`*	UUID \| null	Creating principal
`created_at`*	datetime	Creation time
`updated_at`*	datetime	Last update
`deleted_at`*	datetime \| null	Soft-delete time if deleted
`automation_count`*	integer	Live automations in project

curl -X POST https://platform.ergondata.ai/api/v1/automations/projects \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Revenue ops",
    "description": "Customer-facing automations"
  }'

Response

201 Created

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
  "name": "Revenue ops",
  "description": "Customer-facing automations",
  "created_by_principal_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z",
  "deleted_at": null,
  "automation_count": 0
}

GET/api/v1/automations/projects/{project_id}

Get Project

Retrieve one project by ID.

Bearer token required. IAM permission `automations:projects:view` on `org/{company_id}/automation-project/{project_id}`.

Path Parameters

Name	Type	Description
`project_id`*	string (UUID)	Project ID

curl https://platform.ergondata.ai/api/v1/automations/projects/{project_id} \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
  "name": "Revenue ops",
  "description": "Customer-facing automations",
  "created_by_principal_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z",
  "deleted_at": null,
  "automation_count": 3
}

PATCH/api/v1/automations/projects/{project_id}

Update Project

Update project name and/or description.

Bearer token required. IAM permission `automations:projects:edit` on `org/{company_id}/automation-project/{project_id}`.

Path Parameters

Name	Type	Description
`project_id`*	string (UUID)	Project ID

Request Body

Name	Type	Description
`name`	string	New name (1–200 chars)
`description`	string \| null	New description

curl -X PATCH https://platform.ergondata.ai/api/v1/automations/projects/{project_id} \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"name": "Revenue ops v2"}'

Response

200 OK

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
  "name": "Revenue ops v2",
  "description": "Customer-facing automations",
  "created_by_principal_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-16T09:00:00Z",
  "deleted_at": null,
  "automation_count": 3
}

DELETE/api/v1/automations/projects/{project_id}

Delete Project

Soft-delete a project. Returns 409 if any live automations remain.

Bearer token required. IAM permission `automations:projects:delete` on `org/{company_id}/automation-project/{project_id}`.

Path Parameters

Name	Type	Description
`project_id`*	string (UUID)	Project ID

curl -X DELETE https://platform.ergondata.ai/api/v1/automations/projects/{project_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

Automations

Named automations inside a project. Creating an automation provisions an IAM automation principal used for every dispatch from its action nodes. Use the flat list for overview screens; use the project-scoped list when drilling into a folder.

GET/api/v1/automations/projects/{project_id}/automations

List Automations in Project

Cursor-paginated automations for a single project, with optional filters.

Bearer token required. IAM permission `automations:automations:view` on `org/{company_id}/automation-project/{project_id}`.

Path Parameters

Name	Type	Description
`project_id`*	string (UUID)	Project ID

Query Parameters

Name	Type	Description
`limit`	integer	Page size (1–200, default 50)
`cursor`	string \| null	Pagination cursor
`is_active`	boolean \| null	Filter by active flag
`name`	string \| null	Case-insensitive substring filter on name

Response Fields

Name	Type	Description
`items`*	AutomationOut[]	Automation rows including node_count
`next_cursor`*	string \| null	Next page cursor

curl "https://platform.ergondata.ai/api/v1/automations/projects/{project_id}/automations?limit=50" \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "items": [
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
      "project_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
      "name": "Escalate urgent tickets",
      "description": null,
      "iam_automation_id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
      "iam_principal_id": "d4e5f6a7-b8c9-0123-def0-456789012345",
      "is_active": true,
      "max_trigger_depth": 3,
      "graph_version": 4,
      "created_by_principal_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T10:30:00Z",
      "deleted_at": null,
      "node_count": 12
    }
  ],
  "next_cursor": null
}

GET/api/v1/automations/automations

List Automations (Organization)

Flat, cursor-paginated list of automations for the organization. Optionally filter by project, name, or active flag.

Bearer token required. IAM permission `automations:automations:view` on `org/{company_id}`.

Query Parameters

Name	Type	Description
`project_id`	UUID \| null	Restrict to one project
`is_active`	boolean \| null	Filter by active flag
`name`	string \| null	Case-insensitive substring on name
`limit`	integer	Page size (1–200)
`cursor`	string \| null	Pagination cursor

curl "https://platform.ergondata.ai/api/v1/automations/automations?limit=50" \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "items": [],
  "next_cursor": null
}

POST/api/v1/automations/projects/{project_id}/automations

Create Automation

Create an automation and provision its IAM automation principal. Initial graph is empty (node_count 0).

Bearer token required. IAM permission `automations:projects:automations:create` on `org/{company_id}/automation-project/{project_id}`.

Path Parameters

Name	Type	Description
`project_id`*	string (UUID)	Project ID

Request Body

Name	Type	Description
`name`*	string	Name (1–200 chars)
`description`	string \| null	Description
`is_active`	boolean	Default true
`max_trigger_depth`	integer	0–10, default 3

curl -X POST https://platform.ergondata.ai/api/v1/automations/projects/{project_id}/automations \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Escalate urgent tickets",
    "is_active": true,
    "max_trigger_depth": 3
  }'

Response

201 Created

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "project_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
  "name": "Escalate urgent tickets",
  "description": null,
  "iam_automation_id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "iam_principal_id": "d4e5f6a7-b8c9-0123-def0-456789012345",
  "is_active": true,
  "max_trigger_depth": 3,
  "graph_version": 1,
  "created_by_principal_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z",
  "deleted_at": null,
  "node_count": 0
}

GET/api/v1/automations/automations/{automation_id}

Get Automation

Fetch a single automation including live node_count.

Bearer token required. IAM permission `automations:automations:view` on `org/{company_id}/automation-project/{project_id}/automation/{automation_id}`.

Path Parameters

Name	Type	Description
`automation_id`*	string (UUID)	Automation ID

curl https://platform.ergondata.ai/api/v1/automations/automations/{automation_id} \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "project_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
  "name": "Escalate urgent tickets",
  "description": null,
  "iam_automation_id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "iam_principal_id": "d4e5f6a7-b8c9-0123-def0-456789012345",
  "is_active": true,
  "max_trigger_depth": 3,
  "graph_version": 4,
  "created_by_principal_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-16T09:00:00Z",
  "deleted_at": null,
  "node_count": 12
}

PATCH/api/v1/automations/automations/{automation_id}

Update Automation

Patch name, description, active flag, or max trigger depth. Toggling is_active emits activation/deactivation domain events.

Bearer token required. IAM permission `automations:automations:edit` on `org/{company_id}/automation-project/{project_id}/automation/{automation_id}`.

Path Parameters

Name	Type	Description
`automation_id`*	string (UUID)	Automation ID

Request Body

Name	Type	Description
`name`	string	Name (1–200 chars)
`description`	string \| null	Description
`is_active`	boolean \| null	Active flag
`max_trigger_depth`	integer \| null	0–10

curl -X PATCH https://platform.ergondata.ai/api/v1/automations/automations/{automation_id} \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"is_active": false}'

Response

200 OK

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "project_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
  "name": "Escalate urgent tickets",
  "description": null,
  "iam_automation_id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "iam_principal_id": "d4e5f6a7-b8c9-0123-def0-456789012345",
  "is_active": false,
  "max_trigger_depth": 3,
  "graph_version": 4,
  "created_by_principal_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-16T09:15:00Z",
  "deleted_at": null,
  "node_count": 12
}

DELETE/api/v1/automations/automations/{automation_id}

Delete Automation

Soft-delete the automation and its graph nodes; deactivates and best-effort deletes the IAM automation principal.

Bearer token required. IAM permission `automations:automations:delete` on `org/{company_id}/automation-project/{project_id}/automation/{automation_id}`.

Path Parameters

Name	Type	Description
`automation_id`*	string (UUID)	Automation ID

curl -X DELETE https://platform.ergondata.ai/api/v1/automations/automations/{automation_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

POST/api/v1/automations/automations/{automation_id}/invoke/{trigger_node_id}

Invoke Manual Trigger

Fire a manual-trigger node (`automations.manual.invoked`). Body `input` is validated against the trigger node’s `config.input_schema` when present. Optional `Idempotency-Key` header deduplicates in-flight invocations and replays completed runs. Response includes `Location` pointing at the new run.

Bearer token required. IAM permission `automations:automations:runs:create` on `org/{company_id}/automation-project/{project_id}/automation/{automation_id}`.

Path Parameters

Name	Type	Description
`automation_id`*	string (UUID)	Automation ID
`trigger_node_id`*	string (UUID)	Trigger node ID (must be a manual trigger)

Request Body

Name	Type	Description
`input`*	object	Payload for the manual trigger (default empty object)

Response Fields

Name	Type	Description
`run_id`*	UUID	Created run
`automation_id`*	UUID	Automation
`trigger_node_id`*	UUID	Trigger node
`status`*	string	Run status
`correlation_id`*	string	Correlation id for tracing
`location`*	string	Path to the run (also `Location` header)

curl -X POST https://platform.ergondata.ai/api/v1/automations/automations/{automation_id}/invoke/{trigger_node_id} \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: manual-run-001" \
  -d '{"input": {"ticket_id": "T-1001"}}'

Response

202 Accepted

{
  "run_id": "e5f6a7b8-c9d0-1234-ef01-567890abcdef",
  "automation_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "trigger_node_id": "f6a7b8c9-d0e1-2345-f012-678901bcdef0",
  "status": "pending",
  "correlation_id": "11111111-2222-3333-4444-555555555555",
  "location": "/runs/e5f6a7b8-c9d0-1234-ef01-567890abcdef"
}

Step Graphs

Nodes (triggers, conditions, switches, actions, waits) and edges define how an automation runs. GET returns the live graph and `graph_version` for optimistic concurrency; PUT replaces the entire graph atomically when validation passes.

GET/api/v1/automations/automations/{automation_id}/graph

Get Automation Graph

Return all non-deleted nodes and edges plus the current graph_version.

Bearer token required. IAM permission `automations:automations:graph:view` on `org/{company_id}/automation-project/{project_id}/automation/{automation_id}`.

Path Parameters

Name	Type	Description
`automation_id`*	string (UUID)	Automation ID

Response Fields

Name	Type	Description
`automation_id`*	UUID	Automation
`graph_version`*	integer	Monotonic version for If-Match
`nodes`*	NodeOut[]	Trigger, condition, switch, action, wait nodes
`edges`*	EdgeOut[]	Directed edges with optional predicates

curl https://platform.ergondata.ai/api/v1/automations/automations/{automation_id}/graph \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "automation_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "graph_version": 4,
  "nodes": [],
  "edges": []
}

PUT/api/v1/automations/automations/{automation_id}/graph

Replace Automation Graph

Atomically replace the graph. Send `If-Match: <graph_version>` for optimistic concurrency (mismatch → 412). Set `force_slug_rename` when renaming existing node slugs. Validation failures return 422 with per-node errors; unknown catalog slugs may return 409.

Bearer token required. IAM permission `automations:automations:graph:edit` on `org/{company_id}/automation-project/{project_id}/automation/{automation_id}`.

Path Parameters

Name	Type	Description
`automation_id`*	string (UUID)	Automation ID

Request Body

Name	Type	Description
`nodes`*	NodeIn[]	Node definitions (kind, slug, config, optional trigger_event_slug / action_type_slug, etc.)
`edges`*	EdgeIn[]	Edges (source_node_id, target_node_id, predicate, ordinal, …)
`force_slug_rename`	boolean	Acknowledge slug renames (default false)

Response Fields

Name	Type	Description
`automation_id`*	UUID	Automation
`graph_version`*	integer	New graph version
`diff`*	object	Counts: nodes_created, nodes_updated, nodes_deleted, edges_created, edges_updated, edges_deleted, slug_renames, graph_version

curl -X PUT https://platform.ergondata.ai/api/v1/automations/automations/{automation_id}/graph \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "If-Match: 4" \
  -d '{"nodes": [], "edges": [], "force_slug_rename": false}'

Response

200 OK

{
  "automation_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "graph_version": 5,
  "diff": {
    "nodes_created": 0,
    "nodes_updated": 0,
    "nodes_deleted": 0,
    "edges_created": 0,
    "edges_updated": 0,
    "edges_deleted": 0,
    "slug_renames": 0,
    "graph_version": 5
  }
}

Access Management

Project and automation security-page endpoints. Project routes require `automations:permissions:projects:manage`; automation routes require `automations:permissions:automations:manage`. Project pages grant only project-zone permissions (`automations:projects:*`, view/edit/activity, child automation creation, and project grant management). Automation pages grant automation CRUD, graph, run, activity, and automation grant-management permissions. Creator bundles stop at zone boundaries: project creators receive `automations:projects:*` plus project grant management; automation creators receive `automations:automations:*` plus automation grant management.

GET/api/v1/automations/projects/{project_id}/access/eligible

List Project Eligible Principals

Return IAM principals that can receive Automations grants on this project.

Bearer token required. IAM permission `automations:permissions:projects:manage` on `org/{company_id}/automation-project/{project_id}`.

Path Parameters

Name	Type	Description
`project_id`*	string (UUID)	Project ID

Response Fields

Name	Type	Description
`[]`*	EligiblePrincipal[]	Eligible principals with principal_type, principal_id, and label

curl https://platform.ergondata.ai/api/v1/automations/projects/{project_id}/access/eligible \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "principal_type": "member",
    "principal_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "label": "Jane Doe"
  },
  {
    "principal_type": "automation",
    "principal_id": "d4e5f6a7-b8c9-0123-def0-456789012345",
    "label": "Escalate urgent tickets"
  }
]

GET/api/v1/automations/projects/{project_id}/access/resource-types

List Project Grantable Permissions

Return Automations resource types and permissions grantable from the project boundary, including project, automation, graph, run, activity, and permissions-management grants.

Bearer token required. IAM permission `automations:permissions:projects:manage` on `org/{company_id}/automation-project/{project_id}`.

Path Parameters

Name	Type	Description
`project_id`*	string (UUID)	Project ID

Response Fields

Name	Type	Description
`resource_types`*	ResourceTypeNode[]	Automations resource type tree
`permissions`*	PermissionOption[]	Permissions grantable from this project boundary

curl https://platform.ergondata.ai/api/v1/automations/projects/{project_id}/access/resource-types \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "resource_types": [
    { "id": "rt-project", "name": "automation-project", "slug": "automation-project", "parent_id": null, "children": [] }
  ],
  "permissions": [
    {
      "id": "perm-view",
      "name": "automations:automations:view",
      "friendly_name": "View automations",
      "description": "View automations in this project",
      "resource_type_id": "rt-automation",
      "parent_resource_type_slug": "automation-project",
      "scope_anchor": "instance",
      "display_order": 10
    }
  ]
}

GET/api/v1/automations/projects/{project_id}/access/grants

List Project Access Grants

List IAM grants scoped to this automation project boundary.

Bearer token required. IAM permission `automations:permissions:projects:manage` on `org/{company_id}/automation-project/{project_id}`.

Path Parameters

Name	Type	Description
`project_id`*	string (UUID)	Project ID

Query Parameters

Name	Type	Description
`page`	integer	Page numberDefault: `1`
`limit`	integer	Page size (1-500)Default: `100`

Response Fields

Name	Type	Description
`items`*	GrantEntry[]	Grants in this page
`total`*	integer	Total grants
`page`*	integer	Current page
`limit`*	integer	Page size

curl "https://platform.ergondata.ai/api/v1/automations/projects/{project_id}/access/grants?page=1&limit=100" \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "items": [
    {
      "id": "grant-001",
      "principal_type": "member",
      "principal_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "principal_label": "Jane Doe",
      "permission_id": "perm-view",
      "permission_name": "automations:automations:view",
      "resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/automation-project/f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "effect": "allow",
      "granted_at": "2026-05-17T12:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 100
}

POST/api/v1/automations/projects/{project_id}/access/grants

Create Project Access Grant

Grant a project-scoped Automations permission to a principal. The optional resource override must stay within the project resource prefix.

Bearer token required. IAM permission `automations:permissions:projects:manage` on `org/{company_id}/automation-project/{project_id}`.

Path Parameters

Name	Type	Description
`project_id`*	string (UUID)	Project ID

Request Body

Name	Type	Description
`principal_type`*	member \| api_key \| agent \| automation \| workflow \| worksheet	IAM principal type
`principal_id`*	string	IAM principal UUID
`permission_id`*	string	IAM permission UUID
`resource`	string \| null	Defaults to the project boundary; must stay within it
`effect`	allow \| deny	Grant effectDefault: `allow`

Response Fields

Name	Type	Description
`id`*	string	Grant ID
`permission_id`*	string	Permission ID
`name`*	string	Permission slug
`resource`*	string	Resource path
`effect`*	string	Grant effect
`is_system`*	boolean	Whether IAM marked the grant as system-managed
`granted_at`*	datetime	Creation time

curl -X POST https://platform.ergondata.ai/api/v1/automations/projects/{project_id}/access/grants \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "principal_type": "member",
    "principal_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "permission_id": "perm-view",
    "effect": "allow"
  }'

Response

201 Created

{
  "id": "grant-001",
  "permission_id": "perm-view",
  "name": "automations:automations:view",
  "resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/automation-project/f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "effect": "allow",
  "is_system": false,
  "granted_at": "2026-05-17T12:00:00Z"
}

DELETE/api/v1/automations/projects/{project_id}/access/grants/{grant_id}

Delete Project Access Grant

Revoke an IAM grant through the project security page.

Bearer token required. IAM permission `automations:permissions:projects:manage` on `org/{company_id}/automation-project/{project_id}`.

Path Parameters

Name	Type	Description
`project_id`*	string (UUID)	Project ID
`grant_id`*	string	Grant ID

curl -X DELETE https://platform.ergondata.ai/api/v1/automations/projects/{project_id}/access/grants/{grant_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

GET/api/v1/automations/automations/{automation_id}/access/grants

List Automation Access Grants

List IAM grants scoped directly to one automation. Eligible principals and resource-types routes are also available at the same automation access prefix.

Bearer token required. IAM permission `automations:permissions:automations:manage` on `org/{company_id}/automation-project/{project_id}/automation/{automation_id}`.

Path Parameters

Name	Type	Description
`automation_id`*	string (UUID)	Automation ID

Query Parameters

Name	Type	Description
`page`	integer	Page numberDefault: `1`
`limit`	integer	Page size (1-500)Default: `100`

curl "https://platform.ergondata.ai/api/v1/automations/automations/{automation_id}/access/grants?page=1&limit=100" \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "items": [],
  "total": 0,
  "page": 1,
  "limit": 100
}

POST/api/v1/automations/automations/{automation_id}/access/grants

Create Automation Access Grant

Grant an automation-local permission. Automation access pages accept automation, graph, run, activity, and permissions-management grants; project-only permissions are rejected.

Bearer token required. IAM permission `automations:permissions:automations:manage` on `org/{company_id}/automation-project/{project_id}/automation/{automation_id}`.

Path Parameters

Name	Type	Description
`automation_id`*	string (UUID)	Automation ID

Request Body

Name	Type	Description
`principal_type`*	member \| api_key \| agent \| automation \| workflow \| worksheet	IAM principal type
`principal_id`*	string	IAM principal UUID
`permission_id`*	string	IAM permission UUID
`resource`	string \| null	Defaults to the automation boundary; must stay within it
`effect`	allow \| deny	Grant effectDefault: `allow`

curl -X POST https://platform.ergondata.ai/api/v1/automations/automations/{automation_id}/access/grants \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "principal_type": "agent",
    "principal_id": "agent-principal-id",
    "permission_id": "perm-runs-create"
  }'

Response

201 Created

{
  "id": "grant-002",
  "permission_id": "perm-runs-create",
  "name": "automations:automations:runs:create",
  "resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/automation-project/f47ac10b-58cc-4372-a567-0e02b2c3d479/automation/b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "effect": "allow",
  "is_system": false,
  "granted_at": "2026-05-17T12:05:00Z"
}

DELETE/api/v1/automations/automations/{automation_id}/access/grants/{grant_id}

Delete Automation Access Grant

Revoke an IAM grant through the automation security page.

Bearer token required. IAM permission `automations:permissions:automations:manage` on `org/{company_id}/automation-project/{project_id}/automation/{automation_id}`.

Path Parameters

Name	Type	Description
`automation_id`*	string (UUID)	Automation ID
`grant_id`*	string	Grant ID

curl -X DELETE https://platform.ergondata.ai/api/v1/automations/automations/{automation_id}/access/grants/{grant_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

POST/api/v1/automations/access/projects/grants/batch

Batch Create Project Access Grants

Create grants across project roots with ordered partial success. Operations expand as resources × permission_ids in request order, with at most 200 expanded grants. Invalid or unauthorized items fail independently. `already_exists` is an idempotent success, so retrying the whole request or only failed client_ref/index entries is safe. Side-effect errors do not roll back a successful IAM grant and must be reconciled separately. Agent ToolDef slug: `automations.project_access.create_grants_batch`.

Bearer token required. IAM permission `automations:permissions:projects:manage` on every concrete `org/{company_id}/automation-project/{project_id}` root.

Request Body

Name	Type	Description
`operations`*	BatchGrantOperation[]	One or more grouped operations; expanded request limit is 200 grants

Response Fields

Name	Type	Description
`results`*	BatchGrantResult[]	Ordered expanded results: index, client_ref, status, principal_type, principal_id, permission_id, resource, effect, grant, error_status/error_detail, and side_effect_error_status/side_effect_error_detail
`summary`*	object	created, already_exists, and failed counts

curl -X POST https://platform.ergondata.ai/api/v1/automations/access/projects/grants/batch \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"operations":[{"client_ref":"project-access","principal_type":"member","principal_id":"{principal_id}","resources":["org/{company_id}/automation-project/{project_id}"],"permission_ids":["{permission_id}"],"effect":"allow"}]}'

Response

200 OK

{
  "results": [
    {
      "index": 0,
      "client_ref": "project-access",
      "status": "created",
      "principal_type": "member",
      "principal_id": "{principal_id}",
      "permission_id": "{permission_id}",
      "resource": "org/{company_id}/automation-project/{project_id}",
      "effect": "allow",
      "grant": {},
      "error_status": null,
      "error_detail": null,
      "side_effect_error_status": null,
      "side_effect_error_detail": null
    }
  ],
  "summary": { "created": 1, "already_exists": 0, "failed": 0 }
}

POST/api/v1/automations/access/automations/grants/batch

Batch Create Automation Access Grants

Create grants across automation roots with ordered partial success. Operations expand as resources × permission_ids in request order, with at most 200 expanded grants. Invalid or unauthorized items fail independently. `already_exists` is an idempotent success, so whole-request or failed-item retries are safe. Side-effect errors do not roll back successful grants. Agent ToolDef slug: `automations.automation_access.create_grants_batch`.

Bearer token required. IAM permission `automations:permissions:automations:manage` on every concrete automation root.

Request Body

Name	Type	Description
`operations`*	BatchGrantOperation[]	Same BatchCreateGrantsRequest operation fields as the project batch route; expanded request limit is 200 grants

Response Fields

Name	Type	Description
`results`*	BatchGrantResult[]	Ordered results with primary and side-effect error fields for each expanded grant
`summary`*	object	created, already_exists, and failed counts

curl -X POST https://platform.ergondata.ai/api/v1/automations/access/automations/grants/batch \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"operations":[{"principal_type":"agent","principal_id":"{principal_id}","resources":["org/{company_id}/automation-project/{project_id}/automation/{automation_id}"],"permission_ids":["{permission_id}"]}]}'

Response

200 OK

{
  "results": [
    {
      "index": 0,
      "client_ref": null,
      "status": "already_exists",
      "principal_type": "agent",
      "principal_id": "{principal_id}",
      "permission_id": "{permission_id}",
      "resource": "org/{company_id}/automation-project/{project_id}/automation/{automation_id}",
      "effect": "allow",
      "grant": {},
      "error_status": null,
      "error_detail": null,
      "side_effect_error_status": null,
      "side_effect_error_detail": null
    }
  ],
  "summary": { "created": 0, "already_exists": 1, "failed": 0 }
}

Runs

Execution history for one automation. Aggregate operational history is exposed through Activity. `automations:automations:runs:view` returns a redacted run (no raw event graph/context snapshots, no resume_key, no step request/response payloads). `automations:automations:runs:debug` on the same resource scope reveals those fields and is required for `GET /automations/{automation_id}/runs/waiting`.

GET/api/v1/automations/automations/{automation_id}/runs

List Runs

Automation-scoped run history with optional filters and cursor pagination.

Bearer token required. IAM permission `automations:automations:runs:view` on `org/{company_id}`. Debug fields appear if `automations:automations:runs:debug` is also granted on `org/{company_id}`.

Query Parameters

Name	Type	Description
`automation_id`	UUID \| null	Filter to one automation
`status`	string \| null	Filter by run status
`limit`	integer	Page size (1–200)
`cursor`	string \| null	Pagination cursor

Response Fields

Name	Type	Description
`items`*	RunOut[]	Runs (fields redacted per permissions)
`next_cursor`*	string \| null	Next page cursor

curl "https://platform.ergondata.ai/api/v1/automations/automations/{automation_id}/runs?limit=50" \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "items": [],
  "next_cursor": null
}

GET/api/v1/automations/automations/{automation_id}/runs

List Runs (Automation)

Runs for a single automation; redaction rules match the organization-wide list.

Bearer token required. IAM permission `automations:automations:runs:view` on `org/{company_id}/automation-project/{project_id}/automation/{automation_id}`. Debug fields if `automations:automations:runs:debug` on that automation resource.

Path Parameters

Name	Type	Description
`automation_id`*	string (UUID)	Automation ID

Query Parameters

Name	Type	Description
`status`	string \| null	Filter by run status
`limit`	integer	Page size (1–200)
`cursor`	string \| null	Pagination cursor

curl "https://platform.ergondata.ai/api/v1/automations/automations/{automation_id}/runs?limit=50" \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "items": [],
  "next_cursor": null
}

GET/api/v1/automations/automations/{automation_id}/runs/waiting

List Waiting Runs (Debug)

Suspended runs (`status=waiting`). Requires `automations:automations:runs:debug`; otherwise 403. Exposes resume_key in the list shape.

Bearer token required. IAM permission `automations:automations:runs:debug` on `org/{company_id}` (hard requirement).

Query Parameters

Name	Type	Description
`automation_id`	UUID \| null	Filter to one automation
`limit`	integer	Page size (1–200)
`cursor`	string \| null	Pagination cursor

Response Fields

Name	Type	Description
`items`*	WaitingRunOut[]	Slim waiting run rows
`next_cursor`*	string \| null	Next page cursor

curl "https://platform.ergondata.ai/api/v1/automations/automations/{automation_id}/runs/waiting" \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "items": [],
  "next_cursor": null
}

GET/api/v1/automations/automations/{automation_id}/runs/{run_id}

Get Run

Run detail including steps. Payload-bearing fields are null unless `automations:automations:runs:debug` is granted on `org/{company_id}/automation-run/{run_id}`.

Bearer token required. IAM permission `automations:automations:runs:view` on `org/{company_id}/automation-run/{run_id}`; optional `automations:automations:runs:debug` on the same resource for full payloads.

Path Parameters

Name	Type	Description
`run_id`*	string (UUID)	Run ID

Response Fields

Name	Type	Description
`id`*	UUID	Run id
`run_group_id`*	UUID	Run group
`automation_id`*	UUID \| null	Automation
`trigger_node_id`*	UUID \| null	Entry trigger
`status`*	string	Run status
`steps`*	RunStepOut[]	Ordered steps
`event_payload`*	object \| null	Debug-only when permitted
`graph_snapshot`*	object \| null	Debug-only when permitted
`context_snapshot`*	object \| null	Debug-only when permitted
`resume_key`*	string \| null	Debug-only when permitted

curl https://platform.ergondata.ai/api/v1/automations/automations/{automation_id}/runs/{run_id} \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "id": "e5f6a7b8-c9d0-1234-ef01-567890abcdef",
  "run_group_id": "e5f6a7b8-c9d0-1234-ef01-567890abcdef",
  "automation_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "trigger_node_id": "f6a7b8c9-d0e1-2345-f012-678901bcdef0",
  "current_node_id": null,
  "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
  "event_type_slug": "workflows.item.updated",
  "event_id": null,
  "correlation_id": "11111111-2222-3333-4444-555555555555",
  "trigger_depth": 0,
  "status": "succeeded",
  "error": null,
  "resume_until": null,
  "started_at": "2025-01-15T10:30:00Z",
  "completed_at": "2025-01-15T10:30:05Z",
  "steps": [],
  "event_payload": null,
  "graph_snapshot": null,
  "context_snapshot": null,
  "resume_key": null
}

POST/api/v1/automations/automations/{automation_id}/runs/{run_id}/retry

Retry Run

Re-fire a finished or failed run from its trigger. v0 supports only `mode: "from_start"`. Optional `Idempotency-Key` deduplicates like invoke.

Bearer token required. IAM permission `automations:automations:runs:create` on `org/{company_id}/automation-project/{project_id}/automation/{automation_id}` for the run’s automation.

Path Parameters

Name	Type	Description
`run_id`*	string (UUID)	Original run ID

Request Body

Name	Type	Description
`mode`	"from_start"	Retry mode (v0: only from_start; default from_start)

Response Fields

Name	Type	Description
`run_id`*	UUID	New run
`retried_from_run_id`*	UUID	Source run
`status`*	string	New run status
`correlation_id`*	string	Correlation id
`location`*	string	Path to new run (`Location` header)

curl -X POST https://platform.ergondata.ai/api/v1/automations/automations/{automation_id}/runs/{run_id}/retry \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: retry-001" \
  -d '{"mode": "from_start"}'

Response

202 Accepted

{
  "run_id": "a7b8c9d0-e1f2-3456-789a-bcdef0123456",
  "retried_from_run_id": "e5f6a7b8-c9d0-1234-ef01-567890abcdef",
  "status": "pending",
  "correlation_id": "11111111-2222-3333-4444-555555555555",
  "location": "/runs/a7b8c9d0-e1f2-3456-789a-bcdef0123456"
}

Registry & Schedule Preview

Read-only catalog of event types, action types, operators, and per-service sync metadata. `POST /registry/schedule/preview` projects next fire times from an in-memory schedule config for authoring (no persisted state). The catalog is membership-readable — any authenticated company member may read it (no grant required); it is platform-global, non-sensitive node metadata needed by both authors and view-only inspectors.

GET/api/v1/automations/registry/event-types

List Event Types

Browse registered trigger/event types (payload shapes, resource chains, condition sources).

Bearer token required. Membership-readable — any authenticated company member; no IAM grant required.

Query Parameters

Name	Type	Description
`owning_service`	string \| null	Filter by `service_slug`
`q`	string \| null	Substring search on slug or name

curl "https://platform.ergondata.ai/api/v1/automations/registry/event-types?q=workflow" \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "slug": "automations.manual.invoked",
    "service_slug": "automations",
    "name": "Manual run invoked",
    "description": "Emitted by POST .../invoke/... after validation.",
    "entity_type": "trigger",
    "payload_schema": [],
    "skip_processing": false,
    "resource_service": null,
    "resource_type": null,
    "resource_chain": [],
    "scope_anchor": "instance",
    "condition_sources": [],
    "metadata": {}
  }
]

GET/api/v1/automations/registry/action-types

List Action Types

Browse action types (inputs, dispatch metadata, compatible events).

Bearer token required. Membership-readable — any authenticated company member; no IAM grant required.

Query Parameters

Name	Type	Description
`owning_service`	string \| null	Filter by `service_slug`
`for_event_slug`	string \| null	Only actions compatible with this trigger event slug
`q`	string \| null	Substring search on slug or name

curl https://platform.ergondata.ai/api/v1/automations/registry/action-types \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "slug": "automations.set_variable",
    "service_slug": "automations",
    "name": "Set value",
    "description": "Capture a value from another node (or a static value / template) and re-emit it unchanged.",
    "entity_type": "set",
    "required_permission": "automations:automations:runs:create",
    "input_schema": [{"name": "value", "label": "Value", "value_family": "text", "required": true}],
    "output_schema": [{"name": "value", "label": "Value", "value_family": "text"}],
    "supports_wait_pairing": [],
    "side_effects": [],
    "compatible_event_slugs": null,
    "resource_chain": [],
    "scope_anchor": "instance",
    "condition_sources": []
  }
]

GET/api/v1/automations/registry/operators

List Operators

Condition/switch operators (value families, arity).

Bearer token required. Membership-readable — any authenticated company member; no IAM grant required.

curl https://platform.ergondata.ai/api/v1/automations/registry/operators \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "slug": "text:equals_ignore_case",
    "namespace": "text",
    "label": "Equals (ignore case)",
    "description": null,
    "value_families": ["text"],
    "arity": "binary"
  }
]

POST/api/v1/automations/registry/schedule/preview

Preview Schedule Fires

Compute up to `count` next UTC fire times from a schedule trigger config (timezone, rules, optional bounds). Stateless: identical input yields identical output.

Bearer token required. Membership-readable — any authenticated company member; no IAM grant required.

Request Body

Name	Type	Description
`config`*	object	Schedule config (timezone, rules, optional starts_at/ends_at)
`count`	integer	Number of fires to project (1–20, default 5)
`after`	datetime \| null	Lower bound UTC (exclusive); defaults to now

Response Fields

Name	Type	Description
`fires`*	datetime[]	Upcoming fire times in UTC
`error`*	string \| null	Set when no fires could be produced

curl -X POST https://platform.ergondata.ai/api/v1/automations/registry/schedule/preview \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {"timezone": "America/New_York", "rules": [{"kind": "weekly", "byweekday": [1], "time": "09:00"}]},
    "count": 3
  }'

Response

200 OK

{
  "fires": [
    "2025-01-20T14:00:00Z",
    "2025-01-27T14:00:00Z",
    "2025-02-03T14:00:00Z"
  ],
  "error": null
}

GET/api/v1/automations/registry/services

List Service Catalog Versions

Mirrored `service_catalog_versions` rows with per-service event and action counts.

Bearer token required. Membership-readable — any authenticated company member; no IAM grant required.

curl https://platform.ergondata.ai/api/v1/automations/registry/services \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "service_slug": "automations",
    "version": 1,
    "last_synced_at": "2025-01-15T10:30:00Z",
    "event_type_count": 2,
    "action_type_count": 1
  }
]

Inbound Access Connections

Approver-side connection views for project and automation security boundaries. These complement the requester-side automation connections surface.

GET/api/v1/automations/projects/{project_id}/access/connections

List Project Inbound Connections

List active connections where another principal or role connects to this project boundary.

Bearer token required. IAM permission `automations:permissions:projects:manage` on the target project resource.

Path Parameters

Name	Type	Description
`project_id`*	string (UUID)	Project ID

Response Fields

Name	Type	Description
`id`*	string	Connection ID
`principal_id`	string \| null	Connected principal ID; null for role-subject connections
`role_id`	string \| null	Connected role ID; null for principal-subject connections
`principal_type`	string \| null	Resolved principal or role type
`principal_label`	string \| null	Resolved display label
`target_service`*	string	Target service slug (`automations`)
`target_resource`*	string	Project or automation resource path
`created_at`*	string	Connection creation timestamp

curl "https://platform.ergondata.ai/api/v1/automations/projects/{project_id}/access/connections" \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "55556666-7777-8888-9999-aaaabbbbcccc",
    "principal_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "role_id": null,
    "principal_type": "agent",
    "principal_label": "Operations agent",
    "target_service": "automations",
    "target_resource": "org/{company_id}/automation-project/{project_id}",
    "created_at": "2026-08-06T12:00:00Z"
  }
]

DELETE/api/v1/automations/projects/{project_id}/access/connections/{connection_id}

Revoke Project Inbound Connection

Sever an inbound connection to this project boundary and remove the connected subject's access.

Bearer token required. IAM permission `automations:permissions:projects:manage` on the target project resource.

Path Parameters

Name	Type	Description
`project_id`*	string (UUID)	Project ID
`connection_id`*	string	Connection ID

curl -X DELETE "https://platform.ergondata.ai/api/v1/automations/projects/{project_id}/access/connections/{connection_id}" \
  -H "Authorization: Bearer {token}"

Response

204 No Content

GET/api/v1/automations/automations/{automation_id}/access/connections

List Automation Inbound Connections

List active connections where another principal or role connects to this automation boundary.

Bearer token required. IAM permission `automations:permissions:automations:manage` on the target automation resource.

Path Parameters

Name	Type	Description
`automation_id`*	string (UUID)	Automation ID

Response Fields

Name	Type	Description
`id`*	string	Connection ID
`principal_id`	string \| null	Connected principal ID; null for role-subject connections
`role_id`	string \| null	Connected role ID; null for principal-subject connections
`principal_type`	string \| null	Resolved principal or role type
`principal_label`	string \| null	Resolved display label
`target_service`*	string	Target service slug (`automations`)
`target_resource`*	string	Project or automation resource path
`created_at`*	string	Connection creation timestamp

curl "https://platform.ergondata.ai/api/v1/automations/automations/{automation_id}/access/connections" \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "55556666-7777-8888-9999-aaaabbbbcccc",
    "principal_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "role_id": null,
    "principal_type": "agent",
    "principal_label": "Operations agent",
    "target_service": "automations",
    "target_resource": "org/{company_id}/automation-project/{project_id}",
    "created_at": "2026-08-06T12:00:00Z"
  }
]

DELETE/api/v1/automations/automations/{automation_id}/access/connections/{connection_id}

Revoke Automation Inbound Connection

Sever an inbound connection to this automation boundary and remove the connected subject's access.

Bearer token required. IAM permission `automations:permissions:automations:manage` on the target automation resource.

Path Parameters

Name	Type	Description
`automation_id`*	string (UUID)	Automation ID
`connection_id`*	string	Connection ID

curl -X DELETE "https://platform.ergondata.ai/api/v1/automations/automations/{automation_id}/access/connections/{connection_id}" \
  -H "Authorization: Bearer {token}"

Response

204 No Content

Connections & Requests

Automations reach resources in other services (workflows, worksheets, buckets, channels, …) through explicit connections. A connection is a grant the target resource's owner has approved. Where the owner has not pre-granted access, the automation raises a connection request that the owner approves or rejects; the requester can withdraw a pending request.

GET/api/v1/automations/automations/{automation_id}/connections

List Automation Connections

List the resources this automation is connected to (the approved grants its action nodes can reach).

Bearer token required.

Path Parameters

Name	Type	Description
`automation_id`*	string (UUID)	Automation ID

Response Fields

Name	Type	Description
`connections`*	ConnectionEntry[]	Established connections, including target, label, creator/requester provenance, system-management metadata, and creation time
`pending_requests`*	OutgoingRequestEntry[]	Pending outgoing requests, including requested permissions, message, status, decision metadata, and creation time

curl "https://platform.ergondata.ai/api/v1/automations/automations/a1b2c3d4-e5f6-7890-abcd-ef1234567890/connections" \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "connections": [
    {
      "id": "55556666-7777-8888-9999-aaaabbbbcccc",
      "principal_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "target_service": "workflows",
      "target_resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/workflow/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "label": "Create tickets in Support",
      "created_by": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "created_by_label": "Ada",
      "requested_by": null,
      "requested_by_label": null,
      "system_managed_by": null,
      "system_managed_key": null,
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "pending_requests": []
}

POST/api/v1/automations/automations/{automation_id}/connections

Connect Automation

Connect this automation to a target resource. If the caller can already grant access on the target, the connection is established immediately; otherwise a connection request is raised for the target owner to approve.

Bearer token required.

Path Parameters

Name	Type	Description
`automation_id`*	string (UUID)	Automation ID

Request Body

Name	Type	Description
`target_service`*	string	Service slug to connect to (e.g. `workflows`, `channels`)
`target_resource`*	string	Resource path to connect to (e.g. `org/{cid}/workflow/{wid}`)
`permissions`	string[] \| null	Permission actions to request on the target resource
`label`	string \| null	Optional human-friendly label
`message`	string \| null	Optional message included with a connection request

Response Fields

Name	Type	Description
`status`*	string	`connected` if established immediately, or `requested` if approval is pending
`connection`	ConnectionEntry \| null	Established connection when status is `connected`
`request`	OutgoingRequestEntry \| null	Pending request when status is `requested`

curl -X POST "https://platform.ergondata.ai/api/v1/automations/automations/a1b2c3d4-e5f6-7890-abcd-ef1234567890/connections" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "target_service": "workflows",
    "target_resource": "org/{company_id}/workflow/{workflow_id}",
    "permissions": ["workflows:workflows:items:create"],
    "label": "Create tickets in Support"
  }'

Response

201 Created

{
  "status": "requested",
  "connection": null,
  "request": {
    "id": "66667777-8888-9999-aaaa-bbbbccccdddd",
    "principal_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "target_service": "workflows",
    "target_resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/workflow/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "requested_by": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "requested_permissions": ["workflows:workflows:items:create"],
    "message": null,
    "status": "pending",
    "connection_id": null,
    "decided_by": null,
    "decided_at": null,
    "created_at": "2025-01-15T10:30:00Z"
  }
}

DELETE/api/v1/automations/automations/{automation_id}/connections/{connection_id}

Revoke Automation Connection

Revoke an established connection, removing the automation's access to the target resource.

Bearer token required.

Path Parameters

Name	Type	Description
`automation_id`*	string (UUID)	Automation ID
`connection_id`*	string (UUID)	Connection ID

curl -X DELETE "https://platform.ergondata.ai/api/v1/automations/automations/a1b2c3d4-e5f6-7890-abcd-ef1234567890/connections/55556666-7777-8888-9999-aaaabbbbcccc" \
  -H "Authorization: Bearer {token}"

Response

204 No Content

GET/api/v1/automations/automations/{automation_id}/access/connection-requests

List Automation Connection Requests

List connection requests targeting this automation (i.e. requests from other principals or services asking to connect to it).

Bearer token required.

Path Parameters

Name	Type	Description
`automation_id`*	string (UUID)	Automation ID

Query Parameters

Name	Type	Description
`status`	string	Filter by request status (e.g. `pending`, `approved`, `rejected`)

Response Fields

Name	Type	Description
`id`*	UUID	Connection request ID
`status`*	string	Request status
`requester_service`*	string	Service slug that raised the request
`requester_resource`*	string	Resource path of the requester
`permissions`*	string[]	Requested permission actions
`message`	string \| null	Message from the requester
`created_at`*	datetime	When the request was raised

curl "https://platform.ergondata.ai/api/v1/automations/automations/a1b2c3d4-e5f6-7890-abcd-ef1234567890/access/connection-requests?status=pending" \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "66667777-8888-9999-aaaa-bbbbccccdddd",
    "status": "pending",
    "requester_service": "automations",
    "requester_resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/automation-project/f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "permissions": ["automations:automations:invoke"],
    "message": "Allow the billing project to trigger this automation",
    "created_at": "2025-01-15T10:30:00Z"
  }
]

POST/api/v1/automations/automations/{automation_id}/access/connection-requests/{request_id}/approve

Approve Automation Connection Request

Approve a pending connection request targeting this automation, optionally narrowing the granted permissions.

Bearer token required.

Path Parameters

Name	Type	Description
`automation_id`*	string (UUID)	Automation ID
`request_id`*	string (UUID)	Connection request ID

Request Body

Name	Type	Description
`grant`	boolean	Whether to issue the IAM grant on approval (default true)
`permissions`	string[] \| null	Override the permission actions to grant (defaults to the requested set)
`label`	string \| null	Optional label for the resulting connection

Response Fields

Name	Type	Description
`id`*	UUID	Connection request ID
`status`*	string	`approved`
`connection_id`	UUID \| null	ID of the connection created on approval

curl -X POST "https://platform.ergondata.ai/api/v1/automations/automations/a1b2c3d4-e5f6-7890-abcd-ef1234567890/access/connection-requests/66667777-8888-9999-aaaa-bbbbccccdddd/approve" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{ "grant": true }'

Response

200 OK

{
  "id": "66667777-8888-9999-aaaa-bbbbccccdddd",
  "status": "approved",
  "connection_id": "55556666-7777-8888-9999-aaaabbbbcccc"
}

POST/api/v1/automations/automations/{automation_id}/access/connection-requests/{request_id}/reject

Reject Automation Connection Request

Reject a pending connection request targeting this automation.

Bearer token required.

Path Parameters

Name	Type	Description
`automation_id`*	string (UUID)	Automation ID
`request_id`*	string (UUID)	Connection request ID

Request Body

Name	Type	Description
`reason`	string \| null	Optional reason recorded with the rejection

Response Fields

Name	Type	Description
`id`*	UUID	Connection request ID
`status`*	string	`rejected`

curl -X POST "https://platform.ergondata.ai/api/v1/automations/automations/a1b2c3d4-e5f6-7890-abcd-ef1234567890/access/connection-requests/66667777-8888-9999-aaaa-bbbbccccdddd/reject" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Not needed" }'

Response

200 OK

{
  "id": "66667777-8888-9999-aaaa-bbbbccccdddd",
  "status": "rejected"
}

POST/api/v1/automations/automations/{automation_id}/connection-requests/{request_id}/withdraw

Withdraw Automation Connection Request

Withdraw a pending connection request that this automation raised against another resource.

Bearer token required.

Path Parameters

Name	Type	Description
`automation_id`*	string (UUID)	Automation ID
`request_id`*	string (UUID)	Connection request ID

Response Fields

Name	Type	Description
`id`*	UUID	Connection request ID
`status`*	string	`withdrawn`

curl -X POST "https://platform.ergondata.ai/api/v1/automations/automations/a1b2c3d4-e5f6-7890-abcd-ef1234567890/connection-requests/66667777-8888-9999-aaaa-bbbbccccdddd/withdraw" \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "id": "66667777-8888-9999-aaaa-bbbbccccdddd",
  "status": "withdrawn"
}

GET/api/v1/automations/projects/{project_id}/access/connection-requests

List Project Connection Requests

List connection requests targeting this project (the project-level access boundary).

Bearer token required.

Path Parameters

Name	Type	Description
`project_id`*	string (UUID)	Project ID

Query Parameters

Name	Type	Description
`status`	string	Filter by request status (e.g. `pending`)

Response Fields

Name	Type	Description
`id`*	UUID	Connection request ID
`status`*	string	Request status
`requester_service`*	string	Service slug that raised the request
`requester_resource`*	string	Resource path of the requester
`permissions`*	string[]	Requested permission actions
`created_at`*	datetime	When the request was raised

curl "https://platform.ergondata.ai/api/v1/automations/projects/f47ac10b-58cc-4372-a567-0e02b2c3d479/access/connection-requests?status=pending" \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "66667777-8888-9999-aaaa-bbbbccccdddd",
    "status": "pending",
    "requester_service": "workflows",
    "requester_resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/workflow/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "permissions": ["automations:automations:invoke"],
    "created_at": "2025-01-15T10:30:00Z"
  }
]

POST/api/v1/automations/projects/{project_id}/access/connection-requests/{request_id}/approve

Approve Project Connection Request

Approve a pending connection request targeting this project.

Bearer token required.

Path Parameters

Name	Type	Description
`project_id`*	string (UUID)	Project ID
`request_id`*	string (UUID)	Connection request ID

Request Body

Name	Type	Description
`grant`	boolean	Whether to issue the IAM grant on approval (default true)
`permissions`	string[] \| null	Override the permission actions to grant

Response Fields

Name	Type	Description
`id`*	UUID	Connection request ID
`status`*	string	`approved`
`connection_id`	UUID \| null	ID of the connection created on approval

curl -X POST "https://platform.ergondata.ai/api/v1/automations/projects/f47ac10b-58cc-4372-a567-0e02b2c3d479/access/connection-requests/66667777-8888-9999-aaaa-bbbbccccdddd/approve" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{ "grant": true }'

Response

200 OK

{
  "id": "66667777-8888-9999-aaaa-bbbbccccdddd",
  "status": "approved",
  "connection_id": "55556666-7777-8888-9999-aaaabbbbcccc"
}

POST/api/v1/automations/projects/{project_id}/access/connection-requests/{request_id}/reject

Reject Project Connection Request

Reject a pending connection request targeting this project.

Bearer token required.

Path Parameters

Name	Type	Description
`project_id`*	string (UUID)	Project ID
`request_id`*	string (UUID)	Connection request ID

Request Body

Name	Type	Description
`reason`	string \| null	Optional reason recorded with the rejection

Response Fields

Name	Type	Description
`id`*	UUID	Connection request ID
`status`*	string	`rejected`

curl -X POST "https://platform.ergondata.ai/api/v1/automations/projects/f47ac10b-58cc-4372-a567-0e02b2c3d479/access/connection-requests/66667777-8888-9999-aaaa-bbbbccccdddd/reject" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Not needed" }'

Response

200 OK

{
  "id": "66667777-8888-9999-aaaa-bbbbccccdddd",
  "status": "rejected"
}

Activity & Discovery

Automations records an activity event for every state change — runs starting and finishing, graphs being edited, connections approved. Query the service-wide feed, or scope it to a single automation or project. The access subtree also exposes the principals eligible to be granted on an automation and the resource types available for grants.

GET/api/v1/automations/activity

List Activity

List activity events across all automations the caller can see, newest first.

Bearer token required.

Query Parameters

Name	Type	Description
`event_type`	string	Filter by event type slug
`correlation_id`	string	Filter by correlation ID to follow one causal chain
`page`	integer	Page number (1-based)Default: `1`
`limit`	integer	Page sizeDefault: `50`

Response Fields

Name	Type	Description
`items`*	AutomationActivityItem[]	Events with id, event_type, actor_id, actor_type, correlation_id, automation_id, project_id, data, and created_at
`total`*	integer	Matching event count
`page`*	integer	Current page
`limit`*	integer	Page size

curl "https://platform.ergondata.ai/api/v1/automations/activity?limit=50" \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "items": [
    {
      "id": "22223333-4444-5555-6666-777788889999",
      "event_type": "automations.run.completed",
      "actor_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "actor_type": "member",
      "correlation_id": "11111111-2222-3333-4444-555555555555",
      "automation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "project_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "data": { "status": "succeeded", "duration_ms": 412 },
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 50
}

GET/api/v1/automations/activity/{event_id}

Get Activity Event

Fetch a single activity event by ID.

Bearer token required.

Path Parameters

Name	Type	Description
`event_id`*	string (UUID)	Activity event ID

Response Fields

Name	Type	Description
`id`*	UUID	Activity event ID
`event_type`*	string	Event type slug
`actor_id`	UUID \| null	Actor principal ID
`actor_type`	string \| null	Actor principal type
`automation_id`	UUID \| null	Related automation
`project_id`	UUID \| null	Related project
`correlation_id`	UUID \| null	Correlation ID
`data`	object \| null	Event metadata payload
`created_at`*	datetime	When the event occurred

curl "https://platform.ergondata.ai/api/v1/automations/activity/22223333-4444-5555-6666-777788889999" \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "id": "22223333-4444-5555-6666-777788889999",
  "event_type": "automations.run.completed",
  "actor_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "actor_type": "member",
  "correlation_id": "11111111-2222-3333-4444-555555555555",
  "automation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "project_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "data": { "status": "succeeded", "duration_ms": 412 },
  "created_at": "2025-01-15T10:30:00Z"
}

GET/api/v1/automations/automations/{automation_id}/activity

List Automation Activity

List activity events scoped to a single automation.

Bearer token required.

Path Parameters

Name	Type	Description
`automation_id`*	string (UUID)	Automation ID

Query Parameters

Name	Type	Description
`event_type`	string	Filter by event type slug
`correlation_id`	string	Filter by correlation ID
`page`	integer	Page number (1-based)Default: `1`
`limit`	integer	Page sizeDefault: `50`

Response Fields

Name	Type	Description
`items`*	AutomationActivityItem[]	Activity events for the automation
`total`*	integer	Matching event count
`page`*	integer	Current page
`limit`*	integer	Page size

curl "https://platform.ergondata.ai/api/v1/automations/automations/a1b2c3d4-e5f6-7890-abcd-ef1234567890/activity?limit=50" \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "items": [
    {
      "id": "22223333-4444-5555-6666-777788889999",
      "event_type": "automations.run.started",
      "automation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 50
}

GET/api/v1/automations/projects/{project_id}/activity

List Project Activity

List activity events for every automation in a project.

Bearer token required.

Path Parameters

Name	Type	Description
`project_id`*	string (UUID)	Project ID

Query Parameters

Name	Type	Description
`event_type`	string	Filter by event type slug
`correlation_id`	string	Filter by correlation ID
`page`	integer	Page number (1-based)Default: `1`
`limit`	integer	Page sizeDefault: `50`

Response Fields

Name	Type	Description
`items`*	AutomationActivityItem[]	Activity events for the project
`total`*	integer	Matching event count
`page`*	integer	Current page
`limit`*	integer	Page size

curl "https://platform.ergondata.ai/api/v1/automations/projects/f47ac10b-58cc-4372-a567-0e02b2c3d479/activity?limit=50" \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "items": [
    {
      "id": "22223333-4444-5555-6666-777788889999",
      "event_type": "automations.automation.created",
      "automation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 50
}

GET/api/v1/automations/automations/{automation_id}/access/eligible

List Eligible Principals

List the principals (members, API keys, agents, machine principals) eligible to be granted access on this automation.

Bearer token required.

Path Parameters

Name	Type	Description
`automation_id`*	string (UUID)	Automation ID

Response Fields

Name	Type	Description
`principal_id`*	UUID	Principal ID
`principal_type`*	string	user \| api_key \| agent \| machine
`display_name`*	string	Principal display name

curl "https://platform.ergondata.ai/api/v1/automations/automations/a1b2c3d4-e5f6-7890-abcd-ef1234567890/access/eligible" \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "principal_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "principal_type": "user",
    "display_name": "Ada Lovelace"
  }
]

GET/api/v1/automations/automations/{automation_id}/access/resource-types

List Grantable Resource Types

List the resource types (and their permission actions) available when granting access on this automation.

Bearer token required.

Path Parameters

Name	Type	Description
`automation_id`*	string (UUID)	Automation ID

Response Fields

Name	Type	Description
`resource_type`*	string	Resource type slug
`label`*	string	Human-friendly label
`permissions`*	string[]	Permission actions available for this resource type

curl "https://platform.ergondata.ai/api/v1/automations/automations/a1b2c3d4-e5f6-7890-abcd-ef1234567890/access/resource-types" \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "resource_type": "automation",
    "label": "Automation",
    "permissions": ["automations:automations:view", "automations:automations:invoke", "automations:automations:manage"]
  }
]

Personal Project Preferences

User-session-only Studio presentation state. These operations are intentionally not agent tools because agent and machine principals do not have personal project-tree preferences.

GET/api/v1/automations/companies/{company_id}/project-prefs

Get Project Preferences

Return the calling user's favorite project and custom project ordering for one company.

Bearer token with a user identity required. The token company must match `company_id`; principal-only tokens without `user_id` are rejected.

Path Parameters

Name	Type	Description
`company_id`*	string (UUID)	Company ID

Response Fields

Name	Type	Description
`favorite_project_id`	UUID \| null	Favorite project, or null
`project_order`*	UUID[]	Custom project ordering

curl "https://platform.ergondata.ai/api/v1/automations/companies/{company_id}/project-prefs" \
  -H "Authorization: Bearer {user_token}"

Response

200 OK

{
  "favorite_project_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "project_order": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"]
}

PUT/api/v1/automations/companies/{company_id}/project-prefs

Update Project Preferences

Partially update the calling user's favorite project and custom project ordering.

Bearer token with a user identity required. The token company must match `company_id`; principal-only tokens without `user_id` are rejected.

Path Parameters

Name	Type	Description
`company_id`*	string (UUID)	Company ID

Request Body

Name	Type	Description
`favorite_project_id`	UUID \| null	Favorite project; null clears it
`project_order`	UUID[] \| null	Replacement order; null clears it

Response Fields

Name	Type	Description
`favorite_project_id`	UUID \| null	Favorite project, or null
`project_order`*	UUID[]	Custom project ordering

curl -X PUT "https://platform.ergondata.ai/api/v1/automations/companies/{company_id}/project-prefs" \
  -H "Authorization: Bearer {user_token}" \
  -H "Content-Type: application/json" \
  -d '{"favorite_project_id":"f47ac10b-58cc-4372-a567-0e02b2c3d479"}'

Response

200 OK

{
  "favorite_project_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "project_order": []
}