---
title: "Trigger Speak AI workflows with the automations API"
description: "Create, read, update, and delete Speak AI automations, and turn an automation on or off without changing the trigger and action it is built from."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.speakai.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Trigger Speak AI workflows with the automations API


import EndpointIndex from "@/components/api/EndpointIndex.astro";

The Speak AI API exposes 6 automations endpoints under the base URL `https://api.speakai.co/v1`. Every request needs the `x-speakai-key` and `x-access-token` headers described in [Authentication](/api/authentication/).

Best way to automate your workflow with Automations.

## What can you do with the automations endpoints?

Speak AI groups these 6 endpoints under the automations resource. Each entry below links to the full reference for that endpoint further down this page.

| Method | Path | What it does |
| --- | --- | --- |
| `GET` | [`/automations`](#get-automations) | Get Automations |
| `POST` | [`/automations`](#post-automations) | Create Automation |
| `GET` | [`/automations/{automationId}`](#get-automations-automation-id) | Get Automation |
| `PUT` | [`/automations/{automationId}`](#put-automations-automation-id) | Update Automation |
| `DELETE` | [`/automations/{automationId}`](#delete-automations-automation-id) | Delete Automation |
| `PUT` | [`/automations/status/{automationId}`](#put-automations-status-automation-id) | Enable or Disable Automation |

<h2 id="get-automations">Get Automations</h2>

The endpoint retrieves a list of automations via an HTTP GET request to https://api.speakai.co/v1/automations.

#### Response

The response will be in the form of a JSON schema, with the following structure:

``` json
{
  "status": "",
  "data": {
"totalCount": 0,
"automationList": [
  {
    "trigger": {
      "folderIds": [
        {
          "name": "",
          "folderId": ""
        }
      ],
      "values": [],
      "type": ""
    },
    "action": {
      "magicPrompt": {
        "title": "",
        "assistantType": "",
        "prompt": ""
      },
      "type": ""
    },
    "name": "",
    "description": "",
    "runType": "",
    "isActive": true,
    "automationId": "",
    "actionHistory": [
      {
        "type": ""
      }
    ],
    "createdAt": "",
    "updatedAt": "",
    "history": 0
  }
]
  }
}

```

The response will have a status code of 200 upon successful retrieval of the automation list.

For related responses from other endpoints of this API, the data model will be largely similar, with the addition of "email", "accessToken", and "refreshToken" fields in the "data" object, and a status code of 200.

<div slot="code">

<CodePanel label="Example request">

```bash
curl -X GET 'https://api.speakai.co/v1/automations' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000'
```

</CodePanel>

<ResponsePanel id="get-automations" statuses={[{"code":"200","description":"Success"}]}>

<div slot="status-200">

**`200` Success**

The spec records this status code with no example body.

</div>

</ResponsePanel>

</div>

<h2 id="post-automations">Create Automation</h2>

The API request creates an automation by sending an HTTP POST request to the specified endpoint. The request body is in JSON format and includes the name, description, runType, trigger, and action details. The trigger type is "folders" with specific folder IDs, and the action type is "magic-prompt" with associated details like title, assistantType, prompt, and assistantTemplateId.

The last call to this request used the following payload with the raw request body type:

``` json
{
  "name": "First Automation",
  "description": "Test",
  "action": {
"type": "magic-prompt",
"magicPrompt": {
  "prompt": "Summarize my meetings",
  "assistantType": "general"
}
  },
  "trigger": {
"type": "folders",
"folderIds": ["3711858e52a6"]
  }
}

```

The response to the last execution returned a 200 status code with the following content in JSON format:

``` json
{
  "status": "",
  "data": {
"automationId": "",
"message": ""
  }
}

```

Additionally, related responses from other endpoints of this API also returned 200 status codes with similar data models, including email, access token, refresh token, totalCount, automation list, and trigger details.

Please note that the specific values (such as automationId, email, accessToken, refreshToken, folderIds, etc.) have been intentionally masked for privacy.

##### 1\. **Instant Automation with AI Chat Action**

**Body (JSON):**

``` json
{
  "name": "Instant Folder Analysis",
  "description": "Automatically analyze documents in specific folders using AI assistant",
  "runType": "instant",
  "trigger": {
"type": "folders",
"folderIds": ["folder123", "folder456"]
  },
  "action": {
"type": "magic-prompt",
"magicPrompt": {
  "title": "Document Analysis",
  "assistantType": "researcher",
  "prompt": "Analyze the document content and provide key insights, main topics, and actionable recommendations.",
  "assistantTemplateId": "template123"
}
  },
  "fieldId": "field789"
}

```

##### 2\. **Scheduled Automation with Translation Action**

**Method:** `POST`

**Body (JSON):**

``` json
{
  "name": "Weekly Document Translation",
  "description": "Translate documents in selected folders every week",
  "runType": "schedule",
  "schedule": {
"timePeriod": "last7days",
"repeatAt": "09:00"
  },
  "trigger": {
"type": "folders",
"folderIds": ["folder789", "folder101"]
  },
  "action": {
"type": "translation",
"translation": {
  "targetLanguage": "spanish"
}
  }
}

```

##### 3\. **Instant Automation with Custom AI Chat**

**Method:** `POST`

**Body (JSON):**

``` json
{
  "name": "Sales Lead Analysis",
  "description": "Analyze potential leads and generate sales insights",
  "runType": "instant",
  "trigger": {
"type": "folders",
"folderIds": ["leads-folder"]
  },
  "action": {
"type": "magic-prompt",
"magicPrompt": {
  "title": "Sales Intelligence",
  "assistantType": "sales",
  "prompt": "Review the lead information and provide: 1) Lead quality score (1-10), 2) Key pain points identified, 3) Recommended follow-up strategy, 4) Potential deal size estimate",
  "assistantTemplateId": ""
}
  }
}

```

##### 4\. **Scheduled Automation with Marketing Analysis**

**Method:** `POST`

**Body (JSON):**

``` json
{
  "name": "Daily Marketing Report",
  "description": "Generate daily marketing insights from campaign data",
  "runType": "schedule",
  "schedule": {
"timePeriod": "yesterday",
"repeatAt": "08:00"
  },
  "trigger": {
"type": "folders",
"folderIds": ["marketing-data", "campaign-reports"]
  },
  "action": {
"type": "magic-prompt",
"magicPrompt": {
  "title": "Marketing Daily Digest",
  "assistantType": "marketer",
  "prompt": "Analyze yesterday's marketing data and provide: 1) Top performing campaigns, 2) Key metrics summary, 3) Trends identified, 4) Recommendations for today",
  "assistantTemplateId": "marketing-template-001"
}
  },
  "fieldId": "marketing-field-123"
}

```

#### **Available Enum Values:**

**Run Types:**

- `"instant"` - Executes immediately when triggered

- `"schedule"` - Executes based on schedule configuration

**Trigger Types:**

- `"folders"` - Triggered by folder changes

- `"tags"` - Triggered by tag changes

- `"keywords"` - Triggered by keyword matches

**Action Types:**

- `"magic-prompt"` - AI-powered content analysis

- `"translation"` - Document translation

**Assistant Types (for magic-prompt):**

- `"researcher"`, `"marketer"`, `"sales"`, `"general"`, `"recruiter"`, `"custom"`

**Schedule Time Periods:**

- `"today"`, `"yesterday"`, `"last7days"`, `"last14days"`, `"thisWeek"`

These examples cover both instant and scheduled automation types with different actions. Make sure to replace the placeholder values (folder IDs, template IDs, etc.) with actual values from your system.

### Request body

Field types and names come from the request body the spec records. The spec does not mark request body fields as required, so read this as the shape the endpoint accepts rather than a required field list.

| Field | Type | Description |
| --- | --- | --- |
| `name` | string |  |
| `description` | string |  |
| `runType` | string |  |
| `schedule` | object |  |
| `schedule.timePeriod` | string |  |
| `schedule.repeatAt` | string |  |
| `trigger` | object |  |
| `trigger.type` | string |  |
| `trigger.folderIds` | string[] |  |
| `fieldId` | string |  |
| `steps` | object[] | Ordered automation steps. Required, at least 1 and at most 20. |

<div slot="code">

<CodePanel label="Example request">

```bash
curl -X POST 'https://api.speakai.co/v1/automations' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Daily Marketing Report",
  "description": "Generate daily marketing insights from campaign data",
  "runType": "schedule",
  "schedule": {
"timePeriod": "yesterday",
"repeatAt": "08:00"
  },
  "trigger": {
"type": "folders",
"folderIds": [
  "marketing-data",
  "campaign-reports"
]
  },
  "fieldId": "marketing-field-123",
  "steps": [
{
  "stepId": "step-1",
  "stepType": "magic-prompt",
  "magicPrompt": {
    "promptId": "prompt-123",
    "name": "Weekly summary"
  }
}
  ]
}'
```

</CodePanel>

<ResponsePanel id="post-automations" statuses={[{"code":"200","description":"Success"}]}>

<div slot="status-200">

**`200` Success**

The spec records this status code with no example body.

</div>

</ResponsePanel>

</div>

<h2 id="get-automations-automation-id">Get Automation</h2>

The endpoint makes an HTTP GET request to retrieve a list of automations from the specified URL.

The response of this request can be documented as a JSON schema:

``` json
{
  "type": "object",
  "properties": {
"status": {
  "type": "string"
},
"data": {
  "type": "object",
  "properties": {
    "totalCount": {
      "type": "integer"
    },
    "automationList": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "trigger": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string"
              },
              "folderIds": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "folderId": {
                      "type": "string"
                    }
                  }
                }
              },
              "values": {
                "type": "array"
              }
            }
          },
          "action": {
            "type": "object",
            "properties": {
              "magicPrompt": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string"
                  },
                  "assistantType": {
                    "type": "string"
                  },
                  "assistantTemplateId": {
                    "type": "string"
                  },
                  "prompt": {
                    "type": "string"
                  }
                }
              },
              "type": {
                "type": "string"
              }
            }
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "runType": {
            "type": "string"
          },
          "isActive": {
            "type": "boolean"
          },
          "automationId": {
            "type": "string"
          },
          "actionHistory": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string"
                }
              }
            }
          },
          "createdAt": {
            "type": "string"
          },
          "updatedAt": {
            "type": "string"
          },
          "history": {
            "type": "integer"
          }
        }
      }
    }
  }
}
  }
}

```

### Parameters

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `automationId` | path | string | Yes |  |

<div slot="code">

<CodePanel label="Example request">

```bash
curl -X GET 'https://api.speakai.co/v1/automations/97c57afd7ff1' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000'
```

</CodePanel>

<ResponsePanel id="get-automations-automation-id" statuses={[{"code":"200","description":"Success"}]}>

<div slot="status-200">

**`200` Success**

The spec records this status code with no example body.

</div>

</ResponsePanel>

</div>

<h2 id="put-automations-automation-id">Update Automation</h2>

#### Update Automation

**Body (JSON):**

``` json
{
  "name": "Updated Marketing Analysis",
  "description": "Enhanced automation with schedule and new assistant type",
  "isActive": true,
  "runType": "schedule",
  "schedule": {
"timePeriod": "last7days",
"repeatAt": "09:30"
  },
  "trigger": {
"type": "folders",
"folderIds": ["folder123", "folder456"]
  },
  "action": {
"type": "magic-prompt",
"magicPrompt": {
  "title": "Weekly Marketing Report",
  "assistantType": "marketer",
  "prompt": "Analyze marketing data and provide insights, trends, and recommendations",
  "assistantTemplateId": "marketing-template-001"
}
  },
  "fieldId": "marketing-field-123"
}

```

#### **Key Points:**

• **Path Parameter Required:** `automationId` must be included in the URL path  
• **Partial Updates Supported:** You can update only specific fields, not all fields are required  
• **Run Type Changes:** When changing to `"schedule"`, include the `schedule` object with `timePeriod` and `repeatAt`  
• **Trigger & Action Required:** Both `trigger` and `action` objects appear to be required in the request body  
• **Assistant Type :** The `assistantType` is for custom Assistant selected  
• **Status Control:** Use `isActive: true/false` to enable or disable the automation  
• **Optional Fields:** `fieldId` is optional and only used with magic-prompt actions  
• **Schedule Time Periods:** Available options - `"today"`, `"yesterday"`, `"last7days"`, `"last14days"`, `"thisWeek"`  
• **Action Types:** Support for `"magic-prompt"` and `"translation"` action types  
• **Trigger Types:** Support for `"folders"`, `"tags"`, and `"keywords"` trigger types  
• **Assistant Types:** Available options - `"researcher"`, `"marketer"`, `"sales"`, `"general"`, `"recruiter"`, `"custom"`

### Parameters

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `automationId` | path | string | Yes |  |

### Request body

Field types and names come from the request body the spec records. The spec does not mark request body fields as required, so read this as the shape the endpoint accepts rather than a required field list.

| Field | Type | Description |
| --- | --- | --- |
| `name` | string |  |
| `description` | string |  |
| `isActive` | boolean |  |
| `runType` | string |  |
| `schedule` | object |  |
| `schedule.timePeriod` | string |  |
| `schedule.repeatAt` | string |  |
| `trigger` | object |  |
| `trigger.type` | string |  |
| `trigger.folderIds` | string[] |  |
| `fieldId` | string |  |
| `steps` | object[] | Ordered automation steps. Required, at least 1 and at most 20. |

<div slot="code">

<CodePanel label="Example request">

```bash
curl -X PUT 'https://api.speakai.co/v1/automations/AUTOMATION_ID' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Updated Marketing Analysis",
  "description": "Enhanced automation with schedule and new assistant type",
  "isActive": true,
  "runType": "schedule",
  "schedule": {
"timePeriod": "last7days",
"repeatAt": "09:30"
  },
  "trigger": {
"type": "folders",
"folderIds": [
  "folder123",
  "folder456"
]
  },
  "fieldId": "marketing-field-123",
  "steps": [
{
  "stepId": "step-1",
  "stepType": "magic-prompt",
  "magicPrompt": {
    "promptId": "prompt-123",
    "name": "Weekly summary"
  }
}
  ]
}'
```

</CodePanel>

<ResponsePanel id="put-automations-automation-id" statuses={[{"code":"200","description":"Success"}]}>

<div slot="status-200">

**`200` Success**

The spec records this status code with no example body.

</div>

</ResponsePanel>

</div>

<h2 id="delete-automations-automation-id">Delete Automation</h2>

#### DELETE Automation

This endpoint is used to delete a specific automation identified by its unique `automationId`. By sending a DELETE request to this endpoint, you can remove an automation from the system.

##### Request Format

- **Method**: DELETE

- **Endpoint**: `https://api.speakai.co/v1/automations/{automationId}`

- **Path Parameter**:

    - `automationId` (string): The unique identifier of the automation that you wish to delete. This parameter is required and should be included in the URL.

##### Response Structure

Upon successful deletion of the automation, the server will respond with a confirmation message. The expected response is typically structured as follows:

- **Status Code**: `204 No Content`

    - Indicates that the request was successful and there is no additional content to send in the response body.

In case of an error, the server may return a different status code along with an error message detailing the issue encountered.

Ensure to handle responses appropriately based on the status code received.

### Parameters

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `automationId` | path | string | Yes |  |

<div slot="code">

<CodePanel label="Example request">

```bash
curl -X DELETE 'https://api.speakai.co/v1/automations/null' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000'
```

</CodePanel>

<ResponsePanel id="delete-automations-automation-id" statuses={[{"code":"200","description":"Success"}]}>

<div slot="status-200">

**`200` Success**

The spec records this status code with no example body.

</div>

</ResponsePanel>

</div>

<h2 id="put-automations-status-automation-id">Enable or Disable Automation</h2>

#### Update Automation Status

This endpoint allows you to update the status of a specific automation to enable or disable by providing the automation ID in the URL path.

##### Request Body

The request body should contain the following parameters:

- `status`: (string) The new status for the automation.

- `message`: (string) An optional message related to the status update.

##### Response

The response will have a status code of 200 and a JSON body with the following structure:

- `status`: (string) Indicates the status of the request.

- `message`: (string) Provides additional information about the status.

##### Sample Response

``` json
{
"status": "",
"message": ""
}

```

### Parameters

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `automationId` | path | string | Yes |  |

<div slot="code">

<CodePanel label="Example request">

```bash
curl -X PUT 'https://api.speakai.co/v1/automations/status/97c57afd7ff1' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000'
```

</CodePanel>

<ResponsePanel id="put-automations-status-automation-id" statuses={[{"code":"200","description":"Success"}]}>

<div slot="status-200">

**`200` Success**

The spec records this status code with no example body.

</div>

</ResponsePanel>

</div>

## Related pages

- [API reference](/api/) for the base URL, authentication, and the error format.
- [Authenticate with the Speak AI API using access tokens](/api/authentication/)
- [Upload audio and video to Speak AI and read insights](/api/media/)
- [Create and update live transcription sessions in Speak AI](/api/live-transcription/)
- [Analyze text notes with the Speak AI text endpoints](/api/text/)

Get an API key on the [Speak AI developer page](https://app.speakai.co/developers?utm_source=docs&utm_medium=referral&utm_campaign=api-reference&utm_content=api-automations).

Source: https://docs.speakai.co/api/automations/index.mdx