Agentuity Documentation

Region

https://catalyst-usw.agentuity.cloud

Authentication

All requests require a Bearer token. Pass your API or SDK key in the Authorization header.

Header	Value
`Authorization`	`Bearer YOUR_SDK_KEY`

You can find your SDK key in the Agentuity Console under your project settings.

Workflow Management

List Workflows

List all workflows with optional filtering and pagination.

GET/workflow/list

https://catalyst-usw.agentuity.cloud/workflow/list

Parameters

query

Name	Type	Required	Description
`limit`	number	No	Maximum number of workflows to return
`offset`	number	No	Pagination offset
`status`	string	No	Filter by status (enabled or disabled)
`source_type`	string	No	Filter by source type (email, queue, webhook, or schedule)
`filter`	string	No	Filter workflows by name

Response

Returns paginated list of workflows.

Status	Description
200	Workflows returned
401	Unauthorized — invalid or missing Bearer token

Response Fields

Field	Type	Description
`workflows`	object[]	Array of workflows
`workflows[].id`	string	Unique identifier for the workflow (prefixed with wf_)
`workflows[].created_at`	string	ISO 8601 timestamp when the workflow was created
`workflows[].updated_at`	string	ISO 8601 timestamp when the workflow was last updated
`workflows[].created_by`	string	ID of the user who created the workflow
`workflows[].org_id`	string	Organization ID that owns the workflow
`workflows[].name`	string	Human-readable name for the workflow
`workflows[].description`	string \| null	Optional description of the workflow
`workflows[].source_type`	string	The type of source that triggers this workflow
`workflows[].source_ref_id`	string	The ID of the source (email address, queue, webhook, or schedule)
`workflows[].source_config`	object \| null	Optional configuration for the source
`workflows[].status`	string	The current status of the workflow
`workflows[].graph_json`	object \| null	The workflow graph definition (nodes and edges)
`workflows[].execution_count`	number	Number of times this workflow has been executed (optional)
`workflows[].link`	string	Link to the workflow detail page (optional)
`total`	number	Total number of workflows

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/workflow/list' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Get Workflow

Get a specific workflow by ID.

GET/workflow/{workflowId}

https://catalyst-usw.agentuity.cloud/workflow/{workflowId}

Parameters

path

Name	Type	Required	Description
`workflowId`	string	Yes	Workflow ID (wf_ prefix)

Response

Returns the workflow object.

Status	Description
200	Workflow returned
401	Unauthorized — invalid or missing Bearer token
404	Workflow not found

Response Fields

Field	Type	Description
`workflow`	object	The requested workflow
`workflow.id`	string	Unique identifier for the workflow (prefixed with wf_)
`workflow.created_at`	string	ISO 8601 timestamp when the workflow was created
`workflow.updated_at`	string	ISO 8601 timestamp when the workflow was last updated
`workflow.created_by`	string	ID of the user who created the workflow
`workflow.org_id`	string	Organization ID that owns the workflow
`workflow.name`	string	Human-readable name for the workflow
`workflow.description`	string \| null	Optional description of the workflow
`workflow.source_type`	string	The type of source that triggers this workflow
`workflow.source_ref_id`	string	The ID of the source (email address, queue, webhook, or schedule)
`workflow.source_config`	object \| null	Optional configuration for the source
`workflow.status`	string	The current status of the workflow
`workflow.graph_json`	object \| null	The workflow graph definition (nodes and edges)
`workflow.execution_count`	number	Number of times this workflow has been executed
`workflow.link`	string	Link to the workflow detail page

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/workflow/wf_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Create Workflow

Create a new workflow with a source type and reference.

POST/workflow/create

https://catalyst-usw.agentuity.cloud/workflow/create

Request Body

Workflow creation payload.

Field	Type	Description
`name`	string	Human-readable name for the workflow
`description`	string	Optional description of the workflow (optional)
`source_type`	string	The type of source that triggers this workflow
`source_ref_id`	string	The ID of the source
`source_config`	object	Optional source configuration (optional)

Response

Returns the created workflow.

Status	Description
201	Workflow created
401	Unauthorized — invalid or missing Bearer token

Response Fields

Field	Type	Description
`workflow`	object	The newly created workflow
`workflow.id`	string	Unique identifier for the workflow (prefixed with wf_)
`workflow.created_at`	string	ISO 8601 timestamp when the workflow was created
`workflow.updated_at`	string	ISO 8601 timestamp when the workflow was last updated
`workflow.created_by`	string	ID of the user who created the workflow
`workflow.org_id`	string	Organization ID that owns the workflow
`workflow.name`	string	Human-readable name for the workflow
`workflow.description`	string \| null	Optional description of the workflow
`workflow.source_type`	string	The type of source that triggers this workflow
`workflow.source_ref_id`	string	The ID of the source (email address, queue, webhook, or schedule)
`workflow.source_config`	object \| null	Optional configuration for the source
`workflow.status`	string	The current status of the workflow
`workflow.graph_json`	object \| null	The workflow graph definition (nodes and edges)
`workflow.execution_count`	number	Number of times this workflow has been executed (optional)
`workflow.link`	string	Link to the workflow detail page (optional)

Example

curl -X POST 'https://catalyst-usw.agentuity.cloud/workflow/create' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "GitHub to Slack",
  "source_type": "webhook",
  "source_ref_id": "wh_abc123"
}'

Update Workflow

Update a workflow's name, description, or status.

PATCH/workflow/{workflowId}

https://catalyst-usw.agentuity.cloud/workflow/{workflowId}

Parameters

path

Name	Type	Required	Description
`workflowId`	string	Yes	Workflow ID

Request Body

Fields to update.

Field	Type	Description
`name`	string	New name for the workflow (optional)
`description`	string \| null	New description for the workflow (optional)
`status`	string	New status for the workflow (optional)

Response

Returns the updated workflow.

Status	Description
200	Workflow updated
401	Unauthorized — invalid or missing Bearer token
404	Workflow not found

Response Fields

Field	Type	Description
`workflow`	object	The updated workflow
`workflow.id`	string	Unique identifier for the workflow (prefixed with wf_)
`workflow.created_at`	string	ISO 8601 timestamp when the workflow was created
`workflow.updated_at`	string	ISO 8601 timestamp when the workflow was last updated
`workflow.created_by`	string	ID of the user who created the workflow
`workflow.org_id`	string	Organization ID that owns the workflow
`workflow.name`	string	Human-readable name for the workflow
`workflow.description`	string \| null	Optional description of the workflow
`workflow.source_type`	string	The type of source that triggers this workflow
`workflow.source_ref_id`	string	The ID of the source (email address, queue, webhook, or schedule)
`workflow.source_config`	object \| null	Optional configuration for the source
`workflow.status`	string	The current status of the workflow
`workflow.graph_json`	object \| null	The workflow graph definition (nodes and edges)
`workflow.execution_count`	number	Number of times this workflow has been executed
`workflow.link`	string	Link to the workflow detail page

Example

curl -X PATCH 'https://catalyst-usw.agentuity.cloud/workflow/wf_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Renamed Workflow",
  "status": "disabled"
}'

Update Workflow Graph

Update the workflow graph definition (nodes and edges).

PUT/workflow/graph/{workflowId}

https://catalyst-usw.agentuity.cloud/workflow/graph/{workflowId}

Parameters

path

Name	Type	Required	Description
`workflowId`	string	Yes	Workflow ID

Request Body

Graph definition with nodes and edges.

Field	Type	Description
`nodes`	object[]	Array of workflow nodes
`nodes[].id`	string
`nodes[].type`	string	(optional)
`nodes[].position`	object	(optional)
`nodes[].position.x`	number
`nodes[].position.y`	number
`nodes[].data`	any	(optional)
`edges`	object[]	Array of workflow edges
`edges[].id`	string
`edges[].source`	string
`edges[].target`	string
`edges[].sourceHandle`	string	(optional)
`edges[].targetHandle`	string	(optional)

Response

Returns the updated workflow.

Status	Description
200	Workflow graph updated
401	Unauthorized — invalid or missing Bearer token
404	Workflow not found

Response Fields

Field	Type	Description
`workflow`	object	The updated workflow
`workflow.id`	string	Unique identifier for the workflow (prefixed with wf_)
`workflow.created_at`	string	ISO 8601 timestamp when the workflow was created
`workflow.updated_at`	string	ISO 8601 timestamp when the workflow was last updated
`workflow.created_by`	string	ID of the user who created the workflow
`workflow.org_id`	string	Organization ID that owns the workflow
`workflow.name`	string	Human-readable name for the workflow
`workflow.description`	string \| null	Optional description of the workflow
`workflow.source_type`	string	The type of source that triggers this workflow
`workflow.source_ref_id`	string	The ID of the source (email address, queue, webhook, or schedule)
`workflow.source_config`	object \| null	Optional configuration for the source
`workflow.status`	string	The current status of the workflow
`workflow.graph_json`	object \| null	The workflow graph definition (nodes and edges)
`workflow.execution_count`	number	Number of times this workflow has been executed
`workflow.link`	string	Link to the workflow detail page

Example

curl -X PUT 'https://catalyst-usw.agentuity.cloud/workflow/graph/wf_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "graph_json": {
    "nodes": [
      {
        "id": "n1",
        "type": "filter"
      },
      {
        "id": "n2",
        "type": "action"
      }
    ],
    "edges": [
      {
        "id": "e1",
        "source": "n1",
        "target": "n2"
      }
    ]
  }
}'

Delete Workflow

Delete a workflow and all associated executions and deliveries.

DELETE/workflow/{workflowId}

https://catalyst-usw.agentuity.cloud/workflow/{workflowId}

Parameters

path

Name	Type	Required	Description
`workflowId`	string	Yes	Workflow ID

Response

Empty response on success.

Status	Description
204	Workflow deleted
401	Unauthorized — invalid or missing Bearer token
404	Workflow not found

Example

curl -X DELETE 'https://catalyst-usw.agentuity.cloud/workflow/wf_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Testing

Test Workflow

Test a workflow with a sample payload.

POST/workflow/test/{workflowId}

https://catalyst-usw.agentuity.cloud/workflow/test/{workflowId}

Parameters

path

Name	Type	Required	Description
`workflowId`	string	Yes	Workflow ID

Request Body

Test payload to send through the workflow.

Field	Type	Description
`payload`	any	Test payload to send through the workflow

Response

Returns the test execution result.

Status	Description
200	Test completed
401	Unauthorized — invalid or missing Bearer token
404	Workflow not found

Response Fields

Field	Type	Description
`execution_id`	string	ID of the test execution
`status`	string	Status of the test execution
`steps`	object[]	Individual step results (optional)
`steps[].node_id`	string
`steps[].node_type`	string
`steps[].status`	string
`steps[].output`	any	(optional)
`steps[].error`	string	(optional)
`error`	string	Error message if test failed (optional)

Example

curl -X POST 'https://catalyst-usw.agentuity.cloud/workflow/test/wf_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "payload": {
    "event": "test",
    "data": {
      "key": "value"
    }
  }
}'

Analytics

Get Workflow Activity

Get workflow activity statistics for the organization.

GET/workflow/activity

https://catalyst-usw.agentuity.cloud/workflow/activity

Parameters

query

Name	Type	Required	Description
`days`	number	No	Number of days to look back

Response

Returns aggregate workflow activity statistics.

Status	Description
200	Activity returned
401	Unauthorized — invalid or missing Bearer token

Response Fields

Field	Type	Description
`total_workflows`	number	Total number of workflows
`enabled_workflows`	number	Number of enabled workflows
`disabled_workflows`	number	Number of disabled workflows
`total_executions`	number	Total number of executions
`succeeded_executions`	number	Number of successful executions
`failed_executions`	number	Number of failed executions
`last_activity_at`	string \| null	When the last activity occurred

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/workflow/activity' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Executions

List Workflow Executions

List execution records for a specific workflow.

GET/workflow/executions/{workflowId}

https://catalyst-usw.agentuity.cloud/workflow/executions/{workflowId}

Parameters

path

Name	Type	Required	Description
`workflowId`	string	Yes	Workflow ID

Response

Returns list of executions.

Status	Description
200	Executions returned
401	Unauthorized — invalid or missing Bearer token
404	Workflow not found

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/workflow/executions/wf_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Deliveries

List Workflow Deliveries

List delivery records for a specific execution.

GET/workflow/deliveries/{executionId}

https://catalyst-usw.agentuity.cloud/workflow/deliveries/{executionId}

Parameters

path

Name	Type	Required	Description
`executionId`	string	Yes	Execution ID

Response

Returns list of deliveries.

Status	Description
200	Deliveries returned
401	Unauthorized — invalid or missing Bearer token
404	Execution not found

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/workflow/deliveries/exec_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Analytics

Get Recent Payload

Get the most recent payload received by a workflow.

GET/workflow/recent-payload/{workflowId}

https://catalyst-usw.agentuity.cloud/workflow/recent-payload/{workflowId}

Parameters

path

Name	Type	Required	Description
`workflowId`	string	Yes	Workflow ID

Response

Returns the most recent payload data.

Status	Description
200	Payload returned
401	Unauthorized — invalid or missing Bearer token
404	Workflow not found or no recent payload

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/workflow/recent-payload/wf_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'