Automations

List automations

Return the automations configured in the project bound to the API key, with each automation's trigger configuration, prompt, tool kit, integration grants, model, enabled state, owner, and successful, failed, and total completed runs over the last 30 days. Optionally filter by enabled state and a partial, case-insensitive automation name match; filters determine which automations and per-automation run totals are returned. A project's automation set is intentionally bounded, so this endpoint returns the complete list rather than paginating. Returns an empty list when no automations match.

Authorization

ApiKeyAuth

X-API-Key<token>

External API key header (format: sofa-ext-). Authorization: Bearer is also accepted.

In: header

Query Parameters

enabled?|

Filter to enabled (true) or disabled (false) automations.

name?|

Partial, case-insensitive match against the automation name.

Response Body

`application/json`

curl -X GET "https://example.com/v2/external-api/automations"

{  "items": [    {      "object": "automation",      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "name": "string",      "enabled": true,      "is_built_in": true,      "triggers": [        {          "object": "automation_trigger",          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",          "trigger_type": "code_push",          "config": {            "cron_expression": "string",            "timezone": "UTC",            "preset": "hourly"          },          "next_fire_at": "2019-08-24T14:15:22Z"        }      ],      "user_prompt": "string",      "tool_kit": {        "object": "automation_tool_kit",        "permission_overrides": [          {            "domain": "requirements",            "restriction": "cannot_create"          }        ]      },      "integration_grants": [        {          "object": "connected_integration_grant",          "id": "string",          "display_name": "string",          "is_connected": true        }      ],      "model": "string",      "owner": {        "object": "user",        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",        "display_name": "string",        "email": "string"      },      "total_runs_30d": 0,      "successful_runs_30d": 0,      "failed_runs_30d": 0,      "created_at": "2019-08-24T14:15:22Z",      "updated_at": "2019-08-24T14:15:22Z"    }  ]}

Create an automation

Create an automation in the project bound to the API key. The automation is created enabled and owned by the key's creator — that user's permissions and connected integrations are what it runs with. Integration access is never granted implicitly: omit integration_grants for no external integration access. Omit model to select the recommended model at run time. The request applies immediately; there is no separate confirmation step.

Authorization

ApiKeyAuth

X-API-Key<token>

External API key header (format: sofa-ext-). Authorization: Bearer is also accepted.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Create an automation owned by the authenticating key's creator.

name*Name

Length1 <= length <= 160

user_prompt*User Prompt

The instruction the automation runs with, as markdown text.

Length1 <= length <= 100000

triggers*array<>

What fires the automation. At least one trigger is required.

Items1 <= items

tool_kit?|

Permission restrictions for the automation; omit for no restrictions.

integration_grants?array<string>

Connected-integration identifiers the automation may use. Omit for no integration access — access is never granted implicitly.

Itemsitems <= 50

model?|

Model the automation runs with; omit to select the recommended model.

Response Body

`application/json`

curl -X POST "https://example.com/v2/external-api/automations" \  -H "Content-Type: application/json" \  -d '{    "name": "string",    "user_prompt": "string",    "triggers": [      {        "trigger_type": "code_push"      }    ]  }'

{  "data": {    "object": "automation",    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "name": "string",    "enabled": true,    "is_built_in": true,    "triggers": [      {        "object": "automation_trigger",        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",        "trigger_type": "code_push",        "config": {          "cron_expression": "string",          "timezone": "UTC",          "preset": "hourly"        },        "next_fire_at": "2019-08-24T14:15:22Z"      }    ],    "user_prompt": "string",    "tool_kit": {      "object": "automation_tool_kit",      "permission_overrides": [        {          "domain": "requirements",          "restriction": "cannot_create"        }      ]    },    "integration_grants": [      {        "object": "connected_integration_grant",        "id": "string",        "display_name": "string",        "is_connected": true      }    ],    "model": "string",    "owner": {      "object": "user",      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "display_name": "string",      "email": "string"    },    "total_runs_30d": 0,    "successful_runs_30d": 0,    "failed_runs_30d": 0,    "created_at": "2019-08-24T14:15:22Z",    "updated_at": "2019-08-24T14:15:22Z"  }}

Read an automation

Return one automation's full configuration: name, trigger configuration, prompt, tool kit selection, integration grants, model selection, enabled state, owner, and successful, failed, and total completed runs over the last 30 days. Detailed run history is not included here — navigate from the automation to its runs, and from a run to its conversation.

Authorization

ApiKeyAuth

X-API-Key<token>

External API key header (format: sofa-ext-). Authorization: Bearer is also accepted.

In: header

Path Parameters

automation_id*Automation Id

Formatuuid

Response Body

`application/json`

curl -X GET "https://example.com/v2/external-api/automations/497f6eca-6276-4993-bfeb-53cbbbba6f08"

{  "data": {    "object": "automation",    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "name": "string",    "enabled": true,    "is_built_in": true,    "triggers": [      {        "object": "automation_trigger",        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",        "trigger_type": "code_push",        "config": {          "cron_expression": "string",          "timezone": "UTC",          "preset": "hourly"        },        "next_fire_at": "2019-08-24T14:15:22Z"      }    ],    "user_prompt": "string",    "tool_kit": {      "object": "automation_tool_kit",      "permission_overrides": [        {          "domain": "requirements",          "restriction": "cannot_create"        }      ]    },    "integration_grants": [      {        "object": "connected_integration_grant",        "id": "string",        "display_name": "string",        "is_connected": true      }    ],    "model": "string",    "owner": {      "object": "user",      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "display_name": "string",      "email": "string"    },    "total_runs_30d": 0,    "successful_runs_30d": 0,    "failed_runs_30d": 0,    "created_at": "2019-08-24T14:15:22Z",    "updated_at": "2019-08-24T14:15:22Z"  }}

Update an automation

Update any combination of an automation's name, trigger configuration, prompt, tool kit selection, integration grants, model selection, and enabled state. Only the fields you supply change. Supplying integration_grants replaces the automation's grants entirely; an empty list revokes all integration access. Setting enabled to false prevents new trigger-driven runs while letting any active run finish. Only the automation's owner may update it, unless the caller holds Super Admin standing in the organization. Built-in automations allow only their enabled state to be changed.

Authorization

ApiKeyAuth

X-API-Key<token>

External API key header (format: sofa-ext-). Authorization: Bearer is also accepted.

In: header

Path Parameters

automation_id*Automation Id

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Partially update an automation. Only supplied fields change.

name?|null

user_prompt?|null

enabled?|

Set false to stop new trigger-driven runs while letting any run already in progress finish; set true to resume trigger-driven execution.

triggers?array<>|

Replacement trigger set. Supply at least one trigger; omit this field to leave the existing triggers unchanged.

tool_kit?|null

integration_grants?array<string>|

Replacement grant set — supplying this replaces the automation's grants entirely. Pass an empty list to revoke all integration access.

model?string|null

Response Body

`application/json`

curl -X PATCH "https://example.com/v2/external-api/automations/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{}'

{  "data": {    "object": "automation",    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "name": "string",    "enabled": true,    "is_built_in": true,    "triggers": [      {        "object": "automation_trigger",        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",        "trigger_type": "code_push",        "config": {          "cron_expression": "string",          "timezone": "UTC",          "preset": "hourly"        },        "next_fire_at": "2019-08-24T14:15:22Z"      }    ],    "user_prompt": "string",    "tool_kit": {      "object": "automation_tool_kit",      "permission_overrides": [        {          "domain": "requirements",          "restriction": "cannot_create"        }      ]    },    "integration_grants": [      {        "object": "connected_integration_grant",        "id": "string",        "display_name": "string",        "is_connected": true      }    ],    "model": "string",    "owner": {      "object": "user",      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "display_name": "string",      "email": "string"    },    "total_runs_30d": 0,    "successful_runs_30d": 0,    "failed_runs_30d": 0,    "created_at": "2019-08-24T14:15:22Z",    "updated_at": "2019-08-24T14:15:22Z"  }}

List available integrations

Return the connected integrations available to an automation owner, so their identifiers can be supplied as integration_grants. Omit automation_id when creating an automation to use the API key's creator. When editing an existing automation, supply automation_id to use that automation's owner, including when a Super Admin edits on the owner's behalf. Returns an empty list when the owner has no connected integrations.

Authorization

ApiKeyAuth

X-API-Key<token>

External API key header (format: sofa-ext-). Authorization: Bearer is also accepted.

In: header

Query Parameters

automation_id?|

Automation being edited; selects its owner's connected integrations. Omit when creating an automation.

Response Body

`application/json`

curl -X GET "https://example.com/v2/external-api/integrations"

{  "items": [    {      "object": "connected_integration",      "id": "string",      "display_name": "string"    }  ]}

200application/json

422application/json

201application/json

422application/json

200application/json

422application/json

200application/json

422application/json

200application/json

422application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`