Trigger Speak AI workflows with the automations API

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.

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.

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.

Get Automations

GET/automations

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:

{
  "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.

Example request

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'

Response

200 Success

The spec records this status code with no example body.

Create Automation

POST/automations

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:

{
  "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:

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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.

Example request

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"
      }
    }
  ]
}'

Response

200 Success

The spec records this status code with no example body.

Get Automation

GET/automations/{automationId}

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:

{
  "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

Example request

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'

Response

200 Success

The spec records this status code with no example body.

Update Automation

PUT/automations/{automationId}

Update Automation

Body (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	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.

Example request

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"
      }
    }
  ]
}'

Response

200 Success

The spec records this status code with no example body.

Delete Automation

DELETE/automations/{automationId}

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

Example request

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'

Response

200 Success

The spec records this status code with no example body.

Enable or Disable Automation

PUT/automations/status/{automationId}

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

{
    "status": "",
    "message": ""
}

Parameters

Parameter	In	Type	Required	Description
`automationId`	path	string	Yes

Example request

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'

Response

200 Success

The spec records this status code with no example body.

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

Get an API key on the Speak AI developer page.

Trigger Speak AI workflows with the automations API

What can you do with the automations endpoints?

Get Automations

Response

Create Automation

1. Instant Automation with AI Chat Action

2. Scheduled Automation with Translation Action

3. Instant Automation with Custom AI Chat

4. Scheduled Automation with Marketing Analysis

Available Enum Values:

Request body

Get Automation

Parameters

Update Automation

Update Automation

Key Points:

Parameters

Request body

Delete Automation

DELETE Automation

Request Format

Response Structure

Parameters

Enable or Disable Automation

Update Automation Status

Request Body

Response

Sample Response

Parameters

Related pages