Skip to content
Speak AIDocs

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.

Updated View as MarkdownAsk ClaudeOpen in ChatGPTllms.txt

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 rules. schedule is required only when runType is schedule, and then both schedule.timePeriod and schedule.repeatAt are required too. For any other runType, schedule is optional. Each step’s config object has to match that step’s stepType; a mismatched config is rejected with a 400.

Request body

Fields marked required are the ones the server rejects the request without. Anything conditional, where a field becomes required only alongside another, is described under Request rules above rather than marked here.

Field Type Description
name string, required Name the automation. This is what you see in the automations list. required, max length 150
description string Describe what the automation does. You can send an empty string. optional, max length 1000, empty string allowed
isActive boolean Set whether the automation runs after you create it. Leave it out and the automation is created active. optional. The schema.default(true) is not what produces this: the controller writes isActive only when you send a boolean, and the stored record defaults to true.
runOnceOnly string Ignore this field. The server accepts it and then never reads it, so whatever you send has no effect. optional. unconstrained.strip, so any JSON type passes validation. The.strip has no runtime effect here because RequestValidation discards the validated value; the field is simply never read by the controller, so it is never persisted.
trigger object, required Define the single event that starts the automation. required, unknown keys rejected
triggers object[] Add extra alternative triggers. The automation runs when any one of them fires. Leave it out or send an empty array for a single-trigger automation. optional, max 10 entries
steps object[], required List the steps the automation runs, in order. required, min 1 entry, max 20 entries
runType string Choose whether the automation runs as soon as its trigger fires or on a schedule. optional, empty string accepted. Values come from AutomationRunType plus an explicit ‘’. The declared default is ‘instant’, and although that default is not what reaches the controller, the effect holds anyway: createAutomation writes SCHEDULE only when runType strictly equals “schedule” and writes INSTANT otherwise. One of: instant, schedule, `` .
fieldId string Ignore this field. The server validates it and then never reads it, so setting it has no effect. optional, no length cap. Neither createAutomation nor updateAutomation destructures a top-level fieldId from req.body, so it is never persisted. Field targeting is done per step through magicPrompt.fieldId and magicPrompt.fieldIds.
isUpdated boolean Ignore this field. The server always marks a newly created automation as updated for the scheduler, whatever you send. optional. The controller does not read the client value; it hardcodes isUpdated: true on the new document.
schedule object Set when a scheduled automation runs. required when runType is “schedule”, otherwise optional
schedule.timePeriod string Choose the window of media the scheduled run covers. required when runType is “schedule”; otherwise optional and an empty string is also accepted. Values come from AutomationScheduleTimePeriod. One of: today, yesterday, last7days, last14days, thisWeek .
schedule.repeatAt string Set the time of day the scheduled run fires. required (trimmed, min length 1) when runType is “schedule”; otherwise optional and an empty string is accepted. No format is enforced by the schema.
trigger – 12 more fields
Field Type Description
type string Pick the kind of event that starts the automation. required inside trigger; values come from the AutomationTrigger list. One of: folders, tags, keywords, composio, webhook .
folderIds string[] List the folders the trigger watches. Folder triggers need this; other trigger types do not send it. optional. The item schema is unconstrained: the code is the schema.optional with no.items, so any item type passes.
values string[] Send the secondary list a trigger needs, such as the field IDs for a field-updated event. The server saves it verbatim. optional, items must be strings, empty strings allowed as items
provider string Say which system owns the trigger. optional; the two values are written inline in the schema, not drawn from an enum. One of: speak, composio .
app string Name the third-party app for a Composio trigger. optional, empty string allowed, no length cap
triggerSlug string Give the provider’s slug for the specific trigger you picked. optional, empty string allowed, no length cap
webhookId string Attach an inbound webhook to the trigger by its ID. optional, empty string allowed, no length cap
childKey string Point the trigger at a nested key inside the incoming payload. optional, empty string allowed, no length cap
connectedAccountId string Identify the connected account the trigger authenticates through. optional, empty string allowed. Unlike triggers[].connectedAccountId this one is not trimmed and has no max length.
fieldValueMatches object[] Only fire the trigger when the named fields hold the values you list. optional, max 20 entries
fieldValueMatches[].fieldId string Identify the field to match on. required inside each entry, trimmed, min length 1, max length 100
fieldValueMatches[].values string[] List the values that count as a match. Send an empty array to match any value. required inside each entry, max 50 items, each item max length 200, empty strings allowed
fieldMatchLogic string Choose whether every fieldValueMatches entry has to match or just one. Leaving it out behaves like OR. optional. One of: AND, OR .
triggerConfig object Pass provider-specific trigger settings, such as a watched folder ID. The server stores this object as sent and the provider catalog decides its shape. optional, unconstrained object
triggers – 10 more fields
Field Type Description
type string Pick the kind of event for this alternative trigger. optional here, unlike trigger.type which is required. One of: folders, tags, keywords, composio, webhook .
folderIds string[] List the folders this alternative trigger watches. optional, item schema unconstrained (the schema with no.items)
values string[] Send the secondary list this alternative trigger needs. optional, items must be strings, empty strings allowed as items
provider string Say which system owns this alternative trigger. optional. One of: speak, composio .
app string Name the third-party app for this alternative Composio trigger. optional, empty string allowed
triggerSlug string Give the provider’s slug for this alternative trigger. optional, empty string allowed
fieldValueMatches object[] Only fire this alternative trigger when the named fields hold the values you list. optional, max 20 entries, same fieldId and values shape as trigger.fieldValueMatches
fieldMatchLogic string Choose whether every fieldValueMatches entry has to match or just one for this alternative trigger. optional. One of: AND, OR .
triggerConfig object Pass provider-specific settings for this alternative trigger. optional, unconstrained object
connectedAccountId string Identify the connected account this alternative trigger authenticates through. optional, trimmed, max length 100, empty string allowed
steps – 12 more fields
Field Type Description
stepId string Give the step an ID that is unique within this automation. Other steps reference it through dependsOn. required, trimmed, min length 1, max length 100
stepType string Say what kind of work the step does. This decides which config object the step must carry. required; values come from the AutomationStepType list. One of: trigger, magic-prompt, translation, composio-action, filter, speak-upload, notify, outbound-webhook, condition .
magicPrompt object Configure an AI prompt step. required when stepType is “magic-prompt”, rejected for any other stepType. One step extracts at most 25 fields through fieldIds; send more and the request is rejected with 400. Split a longer rubric across several magic-prompt steps.
translation object Configure a translation step. required when stepType is “translation”, rejected for any other stepType
translation.targetLanguage string Pick the language to translate into. required inside translation. The accepted set is TranslationLanguageCodes, defined by mapping the static TranslationLanguages array (lines 6-118) to its transcriptionCode. That array holds 111 entries, so there are exactly 111 accepted values, listed here in source order. Reached through translationLanguageCode. One of: en-US, fr-FR, af-ZA, ar-SA, hy-AM, bg-BG, ca-ES, hr-HR, cs-CZ, da-DK, nl-NL, et-EE, fa-IR, fi-FI, de-DE, el-GR, gu-IN, he-IL, hi-IN, ht-HT, hu-HU, id-ID, is-IS, it-IT, ga-IE, ja-JP, kn-IN, ko-KR, lt-LT, lv-LV, ml-IN, ms-MY, nb-NO, pl-PL, pt-PT, ro-RO, ru-RU, es-ES, sk-SK, sl-SI, sv-SE, ta-IN, te-IN, th-TH, tr-TR, uk-UA, vi-VN, as-IN, ay-BO, bm-ML, eu-ES, be-BY, bho-IN, ceb-PH, co-FR, dv-MV, doi-IN, eo-XX, ee-GH, fil-PH, fy-NL, gl-ES, gn-PY, haw-US, hmn-CN, ig-NG, ilo-PH, jv-ID, km-KH, rw-RW, gom-IN, kri-SL, ku-TR, ckb-IQ, ky-KG, lo-LA, la-VA, ln-CG, lg-UG, lb-LU, mai-IN, mg-MG, mi-NZ, mni-IN, lus-IN, my-MM, ne-NP, ny-MW, or-IN, om-ET, qu-PE, sm-WS, sa-IN, gd-GB, nso-ZA, st-ZA, sn-ZW, sd-PK, si-LK, su-ID, tg-TJ, tt-RU, ti-ER, ts-ZA, tk-TM, ak-GH, ug-CN, xh-ZA, yi-XX, yo-NG, zu-ZA .
filter object Configure a filter step that stops the run when its rules do not match. required when stepType is “filter”, rejected for any other stepType. Declared inline in automationStep, not as a shared fragment.
filter.logic string Choose whether every rule has to match or just one. optional. The declared default is ‘AND’ but the default is not persisted, because the controller reads raw req.body and the model carries no default. One of: AND, OR .
filter.rules object[] List the conditions the filter checks. required, min 1 entry, max 20 entries
condition object Configure a branching step that sends the run down a true or false path. required when stepType is “condition”, rejected for any other stepType. Declared inline with the identical logic and rules shape as steps[].filter.
condition.logic string Choose whether every rule has to match or just one. optional. The declared default is ‘AND’ but the default is not persisted. One of: AND, OR .
condition.rules object[] List the conditions the branch evaluates. required, min 1 entry, max 20 entries, same field, op and value shape as filter rules
composio object Configure a step that runs a Composio app action. required when stepType is “composio-action”, rejected for any other stepType
speakUpload object Configure a step that uploads media into Speak. required when stepType is “speak-upload”, rejected for any other stepType
notify object Configure a notification step. required when stepType is “notify”, rejected for any other stepType
notify.channel string Pick where the notification goes. required; the three values are written inline in the schema. One of: in_app, email, slack .
notify.target string Name the recipient, such as an email address or a Slack channel. optional, max length 500, empty string allowed
notify.message string Write the notification body. It may contain {tokens}, so the server accepts any text. optional, max length 20000, empty string allowed. The in_app and slack channels use this field while email uses emailContent, but the schema leaves both optional and the pairing is enforced in the client and at run time.
notify.emailContent string For the email channel, choose what the email carries. optional. One of: transcript, ai_response .
outboundWebhook object Configure a step that calls a URL of yours. required when stepType is “outbound-webhook”, rejected for any other stepType
outboundWebhook.url string Give the URL to call. It may contain {tokens}, so it is validated as plain text rather than as a URI. required, trimmed, min length 1, max length 2000, no uri format check
outboundWebhook.method string Choose the HTTP method for the call. optional (no.required, and.default(‘POST’) makes the schema treat it as present). The ‘POST’ default is not persisted, because the controller reads raw req.body and the model carries no default. One of: GET, POST, PUT, PATCH, DELETE .
outboundWebhook.headers object Set request headers for the call. optional, declared as the schema.pattern(the schema, the schema), so keys and values must both be strings
outboundWebhook.bodyTemplate string Set the request body. Send either a string template or a JSON object. optional. Declared as a union.max(20000).allow(‘’), the schema), so the real type is a string-or-object union that a single OpenAPI type cannot express.
dependsOn string[] List the stepId values that must finish before this step runs. optional, items must be strings, no cap
branch string For a step under a condition, say which branch it belongs to. optional. These are the strings “true” and “false”, not booleans, so sending true instead of “true” returns a 400. One of: true, false .
magicPrompt – 12 more fields
Field Type Description
title string Title the prompt so you can recognize its output later. optional, empty string allowed, no length cap
modelId string Override the model for this step. Send an empty string or null to clear it and fall back to your company default. optional; all 43 values copied verbatim from LLMModels.ts. ‘’ and null are coerced to absent. empty(the schema) and are not enum members. The enum’s header comment states that within each provider the DEPRECATED models are grouped first and the LIVE ones follow, but it carries no per-value flag, so no individual value can be marked deprecated from the code. One of: gpt-3.5, gpt-3.5-turbo-16k, gpt-3.5-turbo-0125, gpt-4, gpt-4-1106-preview, gpt-4-turbo, gpt-4o-2024-05-13, gpt-4o, gpt-4o-mini, gpt-4o-2024-08-06, gpt-4o-mini-2024-07-18, gpt-4.1-2025-04-14, gpt-5.1-2025-11-13, gpt-5.2, gpt-5.4, gpt-5.4-mini, gpt-5.4-mini-2026-03-17, gpt-5.4-nano, gpt-5.5, gpt-5.5-thinking, gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna, claude-2, claude-3-5-sonnet, claude-3-5-sonnet-20241022, claude-3-7-sonnet-latest, claude-haiku-4-5, claude-sonnet-4-6, claude-sonnet-5, claude-opus-4-8, gemini-1.5-pro, gemini-1.5-flash, gemini-2.0-flash, gemini-2.5-pro, gemini-2.5-flash, gemini-2.5-flash-lite, gemini-3-flash-preview, gemini-3.1-flash-lite, gemini-3.1-pro-preview, gemini-3.5-flash, gemini-3.7-flash, gemini-3.8-flash, x-ai/grok-4.5, z-ai/glm-5.2 .
prompt string Write the instruction the model follows. max length 20000; required unless fieldIds is present with at least one entry, in which case an empty string is accepted. The declared default is ‘’ on that branch but the default is never persisted, because the controller reads raw req.body.
assistantType string Pick the assistant persona that answers the prompt. Optional, and restricted to the values listed here: any other string is rejected. Omitting it stores no value on the step. When the step runs, the persona falls back to the default saved on the user profile the run belongs to, and to ‘general’ when none is saved. One of: researcher, marketer, sales, general, recruiter, custom .
assistantTemplateId string Identify your custom assistant template. required when assistantType is “custom”; otherwise optional and accepts ‘’ or null. The declared default is ‘’ on the otherwise branch but the default is not persisted.
isIndividualFolder boolean Run the prompt separately per folder instead of once across everything. optional. The declared default is false but the default is not persisted; the model carries no default either.
allowedValues string[] Restrict the answer to this list of values. optional, items must be strings, no item cap
allowedValuesMode string Choose whether the answer may pick one allowed value or several. optional; values come from the AllowedValuesMode list. The declared default is ‘multiple’ but the default is not persisted. One of: single, multiple .
otherValues boolean Let the answer fall outside the allowed values list. optional
notApplicableValues string Say what the model should answer when nothing applies. optional, empty string allowed
fieldId string Write the answer into this single field. optional, accepts ‘’ or null
fieldIds string[] Extract several fields in one step. Sending at least one field ID makes prompt optional. optional, max 25 items. Over the cap the request is rejected with 400 and the message “A single AI step can extract at most 25 fields. Split the rest into another AI step.”
filter.rules – 3 more fields
Field Type Description
field string Name the field the rule reads. required, trimmed, min length 1, max length 100
op string Pick how the rule compares the field to the value. required; the eight values are written inline in the schema, not drawn from an enum. One of: eq, neq, contains, ncontains, startsWith, gt, lt, exists .
value string Give the value to compare against. You can send a string or a number. optional. Declared as a union.max(1000).allow(‘’), the schema), so the real type is a string-or-number union that a single OpenAPI type cannot express.
composio – 6 more fields
Field Type Description
app string Name the Composio app to act on. required, trimmed, min length 1, max length 100
action string Name the action to run in that app. required, trimmed, min length 1, max length 200
connectedAccountId string Identify the connected account the action runs as. optional, trimmed, max length 100, empty string allowed
argsTemplate object Pass the action’s arguments. Values may contain tokens, so the server accepts any shape. optional, unconstrained object
destructive boolean Mark the action as destructive so it asks for confirmation. optional
acknowledged boolean Confirm you accept a destructive action. optional
speakUpload – 8 more fields
Field Type Description
name string Name the uploaded media. optional, max length 500, empty string allowed
folderId string Choose the folder the upload lands in. In dynamic routing this becomes the fallback folder instead. required (trimmed, min length 1, max length 100) unless folderRouting.mode is “dynamic”, in which case it is optional (trimmed, max 100, empty string allowed)
sourceMode string Say whether the upload comes from a URL or from a file already in the run. required. One of: url, file .
sourceUrl string Give the URL to fetch the media from. max length 2000; required when sourceMode is “url”, otherwise optional and may be an empty string. Not validated as a URI, because it may carry {tokens}.
fieldsMap object Map field names to values to set on the uploaded media. optional, declared as the schema.pattern(the schema, the schema), so keys and values must both be strings
language string Set the language for the upload. You can send a language code or a token that resolves at run time, so known codes are not enforced. optional, max length 100, empty string allowed
waitForProcessing boolean Hold the automation until the uploaded media finishes processing before the next step runs. optional
folderRouting object Route the upload to a folder chosen from the incoming payload instead of a fixed one. optional
folderRouting.mode string Choose between the fixed folderId and a folder picked from the payload. required inside folderRouting, so sending folderRouting without mode returns a 400. One of: static, dynamic .
folderRouting.sourceKey string Name the payload key that holds the folder to route to. required (trimmed, min length 1, max length 500) when mode is “dynamic”; otherwise optional, trimmed, max length 500, empty string allowed
folderRouting.onNoMatch string Say what to do when no folder matches: create one, or fall back to the folderId. required when mode is “dynamic”, otherwise optional. Same two values on both branches. One of: create, default .
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"

Request rules. The same rules as creating an automation. schedule is required only when runType is schedule, and then both schedule.timePeriod and schedule.repeatAt are required. Each step’s config object has to match that step’s stepType.

Parameters

Parameter In Type Required Description
automationId path string Yes

Request body

Fields marked required are the ones the server rejects the request without. Anything conditional, where a field becomes required only alongside another, is described under Request rules above rather than marked here.

Field Type Description
name string, required Name the automation. This is what you see in the automations list. required, max length 150
description string Describe what the automation does. You can send an empty string. optional, max length 1000, empty string allowed
isActive boolean Turn the automation on or off. Leave it out and the automation keeps whatever active state it already has. optional. The declared default is true, but that default never reaches the controller, which does if (isActive !== undefined) setter.$set.isActive = isActive. Omitting the field therefore leaves the stored value untouched; it does NOT reactivate a paused automation.
runOnceOnly string Ignore this field. The server accepts it and then never reads it, so whatever you send has no effect. optional. unconstrained.strip, so any JSON type passes validation. The controller reads runOnceOnly only off the existing stored record, never off your request body, so you cannot set or clear it through this endpoint.
trigger object, required Define the single event that starts the automation. required, unknown keys rejected
triggers object[] Add extra alternative triggers. The automation runs when any one of them fires. optional, max 10 entries
steps object[], required List the steps the automation runs, in order. This replaces the existing steps rather than merging with them. required, min 1 entry, max 20 entries
runType string Choose whether the automation runs as soon as its trigger fires or on a schedule. optional, empty string accepted. The controller writes SCHEDULE only when runType strictly equals “schedule” and writes INSTANT otherwise, so omitting it on a scheduled automation converts it back to instant and unsets its schedule. One of: instant, schedule, `` .
fieldId string Ignore this field. The server validates it and then never reads it, so setting it has no effect. optional. updateAutomation does not destructure a top-level fieldId from req.body.
isUpdated boolean Ignore this field. The server always flags the automation as updated for the scheduler on every update, whatever you send. optional. The controller hardcodes isUpdated: true in its $set and never reads the client value.
schedule object Set when a scheduled automation runs. required when runType is “schedule”, otherwise optional. When runType is not “schedule” the controller unsets any stored schedule.
schedule.timePeriod string Choose the window of media the scheduled run covers. required when runType is “schedule”; otherwise optional and an empty string is also accepted. Values come from AutomationScheduleTimePeriod. One of: today, yesterday, last7days, last14days, thisWeek .
schedule.repeatAt string Set the time of day the scheduled run fires. required (trimmed, min length 1) when runType is “schedule”; otherwise optional and an empty string is accepted. No format is enforced.
trigger – 12 more fields
Field Type Description
type string Pick the kind of event that starts the automation. required inside trigger; values come from the AutomationTrigger list. One of: folders, tags, keywords, composio, webhook .
folderIds string[] List the folders the trigger watches. optional, item schema is unconstrained (the schema with no.items)
values string[] Send the secondary list a trigger needs, such as the field IDs for a field-updated event. optional, items must be strings, empty strings allowed as items
provider string Say which system owns the trigger. optional. One of: speak, composio .
app string Name the third-party app for a Composio trigger. optional, empty string allowed
triggerSlug string Give the provider’s slug for the specific trigger you picked. optional, empty string allowed
webhookId string Attach an inbound webhook to the trigger by its ID. optional, empty string allowed
childKey string Point the trigger at a nested key inside the incoming payload. optional, empty string allowed
connectedAccountId string Identify the connected account the trigger authenticates through. optional, empty string allowed, not trimmed and no max length
fieldValueMatches object[] Only fire the trigger when the named fields hold the values you list. optional, max 20 entries
fieldValueMatches[].fieldId string Identify the field to match on. required inside each entry, trimmed, min length 1, max length 100
fieldValueMatches[].values string[] List the values that count as a match. Send an empty array to match any value. required inside each entry, max 50 items, each item max length 200, empty strings allowed
fieldMatchLogic string Choose whether every fieldValueMatches entry has to match or just one. Leaving it out behaves like OR. optional. One of: AND, OR .
triggerConfig object Pass provider-specific trigger settings. The server stores this object as sent. optional, unconstrained object
triggers – 10 more fields
Field Type Description
type string Pick the kind of event for this alternative trigger. optional here, unlike trigger.type which is required. One of: folders, tags, keywords, composio, webhook .
folderIds string[] List the folders this alternative trigger watches. optional, item schema unconstrained
values string[] Send the secondary list this alternative trigger needs. optional, items must be strings, empty strings allowed as items
provider string Say which system owns this alternative trigger. optional. One of: speak, composio .
app string Name the third-party app for this alternative Composio trigger. optional, empty string allowed
triggerSlug string Give the provider’s slug for this alternative trigger. optional, empty string allowed
fieldValueMatches object[] Only fire this alternative trigger when the named fields hold the values you list. optional, max 20 entries, same fieldId and values shape as trigger.fieldValueMatches
fieldMatchLogic string Choose whether every fieldValueMatches entry has to match or just one for this alternative trigger. optional. One of: AND, OR .
triggerConfig object Pass provider-specific settings for this alternative trigger. optional, unconstrained object
connectedAccountId string Identify the connected account this alternative trigger authenticates through. optional, trimmed, max length 100, empty string allowed
steps – 12 more fields
Field Type Description
stepId string Give the step an ID that is unique within this automation. Other steps reference it through dependsOn. required, trimmed, min length 1, max length 100
stepType string Say what kind of work the step does. This decides which config object the step must carry. required; values come from the AutomationStepType list. One of: trigger, magic-prompt, translation, composio-action, filter, speak-upload, notify, outbound-webhook, condition .
magicPrompt object Configure an AI prompt step. required when stepType is “magic-prompt”, rejected for any other stepType. One step extracts at most 25 fields through fieldIds; send more and the request is rejected with 400. Split a longer rubric across several magic-prompt steps.
translation object Configure a translation step. required when stepType is “translation”, rejected for any other stepType
translation.targetLanguage string Pick the language to translate into. required inside translation. The accepted set is TranslationLanguageCodes, defined by mapping the static TranslationLanguages array (lines 6-118) to its transcriptionCode. That array holds 111 entries, so there are exactly 111 accepted values, listed here in source order. One of: en-US, fr-FR, af-ZA, ar-SA, hy-AM, bg-BG, ca-ES, hr-HR, cs-CZ, da-DK, nl-NL, et-EE, fa-IR, fi-FI, de-DE, el-GR, gu-IN, he-IL, hi-IN, ht-HT, hu-HU, id-ID, is-IS, it-IT, ga-IE, ja-JP, kn-IN, ko-KR, lt-LT, lv-LV, ml-IN, ms-MY, nb-NO, pl-PL, pt-PT, ro-RO, ru-RU, es-ES, sk-SK, sl-SI, sv-SE, ta-IN, te-IN, th-TH, tr-TR, uk-UA, vi-VN, as-IN, ay-BO, bm-ML, eu-ES, be-BY, bho-IN, ceb-PH, co-FR, dv-MV, doi-IN, eo-XX, ee-GH, fil-PH, fy-NL, gl-ES, gn-PY, haw-US, hmn-CN, ig-NG, ilo-PH, jv-ID, km-KH, rw-RW, gom-IN, kri-SL, ku-TR, ckb-IQ, ky-KG, lo-LA, la-VA, ln-CG, lg-UG, lb-LU, mai-IN, mg-MG, mi-NZ, mni-IN, lus-IN, my-MM, ne-NP, ny-MW, or-IN, om-ET, qu-PE, sm-WS, sa-IN, gd-GB, nso-ZA, st-ZA, sn-ZW, sd-PK, si-LK, su-ID, tg-TJ, tt-RU, ti-ER, ts-ZA, tk-TM, ak-GH, ug-CN, xh-ZA, yi-XX, yo-NG, zu-ZA .
filter object Configure a filter step that stops the run when its rules do not match. required when stepType is “filter”, rejected for any other stepType
filter.logic string Choose whether every rule has to match or just one. optional. The schema.default(‘AND’) is not persisted. One of: AND, OR .
filter.rules object[] List the conditions the filter checks. required, min 1 entry, max 20 entries
condition object Configure a branching step that sends the run down a true or false path. required when stepType is “condition”, rejected for any other stepType; identical shape to steps[].filter
condition.logic string Choose whether every rule has to match or just one. optional. The schema.default(‘AND’) is not persisted. One of: AND, OR .
condition.rules object[] List the conditions the branch evaluates. required, min 1 entry, max 20 entries, same field, op and value shape as filter rules
composio object Configure a step that runs a Composio app action. required when stepType is “composio-action”, rejected for any other stepType
speakUpload object Configure a step that uploads media into Speak. required when stepType is “speak-upload”, rejected for any other stepType
notify object Configure a notification step. required when stepType is “notify”, rejected for any other stepType
notify.channel string Pick where the notification goes. required. One of: in_app, email, slack .
notify.target string Name the recipient, such as an email address or a Slack channel. optional, max length 500, empty string allowed
notify.message string Write the notification body. It may contain {tokens}, so the server accepts any text. optional, max length 20000, empty string allowed
notify.emailContent string For the email channel, choose what the email carries. optional. One of: transcript, ai_response .
outboundWebhook object Configure a step that calls a URL of yours. required when stepType is “outbound-webhook”, rejected for any other stepType
outboundWebhook.url string Give the URL to call. It may contain {tokens}, so it is validated as plain text rather than as a URI. required, trimmed, min length 1, max length 2000, no uri format check
outboundWebhook.method string Choose the HTTP method for the call. optional. The schema.default(‘POST’) is not persisted. One of: GET, POST, PUT, PATCH, DELETE .
outboundWebhook.headers object Set request headers for the call. optional, keys and values must both be strings
outboundWebhook.bodyTemplate string Set the request body. Send either a string template or a JSON object. optional. Declared as a union.max(20000).allow(‘’), the schema), a string-or-object union.
dependsOn string[] List the stepId values that must finish before this step runs. optional, items must be strings
branch string For a step under a condition, say which branch it belongs to. optional. These are the strings “true” and “false”, not booleans. One of: true, false .
magicPrompt – 12 more fields
Field Type Description
title string Title the prompt so you can recognize its output later. optional, empty string allowed
modelId string Override the model for this step. Send an empty string or null to clear it and fall back to your company default. optional; all 43 values copied verbatim from LLMModels. ‘’ and null coerce to absent. empty(the schema) and are not enum members. The enum’s header comment says DEPRECATED models are grouped first within each provider and LIVE ones follow, but there is no per-value flag, so no individual value can be marked deprecated from the code. One of: gpt-3.5, gpt-3.5-turbo-16k, gpt-3.5-turbo-0125, gpt-4, gpt-4-1106-preview, gpt-4-turbo, gpt-4o-2024-05-13, gpt-4o, gpt-4o-mini, gpt-4o-2024-08-06, gpt-4o-mini-2024-07-18, gpt-4.1-2025-04-14, gpt-5.1-2025-11-13, gpt-5.2, gpt-5.4, gpt-5.4-mini, gpt-5.4-mini-2026-03-17, gpt-5.4-nano, gpt-5.5, gpt-5.5-thinking, gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna, claude-2, claude-3-5-sonnet, claude-3-5-sonnet-20241022, claude-3-7-sonnet-latest, claude-haiku-4-5, claude-sonnet-4-6, claude-sonnet-5, claude-opus-4-8, gemini-1.5-pro, gemini-1.5-flash, gemini-2.0-flash, gemini-2.5-pro, gemini-2.5-flash, gemini-2.5-flash-lite, gemini-3-flash-preview, gemini-3.1-flash-lite, gemini-3.1-pro-preview, gemini-3.5-flash, gemini-3.7-flash, gemini-3.8-flash, x-ai/grok-4.5, z-ai/glm-5.2 .
prompt string Write the instruction the model follows. max length 20000; required unless fieldIds is present with at least one entry, in which case an empty string is accepted. The schema.default(‘’) on that branch is not persisted.
assistantType string Pick the assistant persona that answers the prompt. Optional, and restricted to the values listed here: any other string is rejected. Omitting it stores no value on the step. When the step runs, the persona falls back to the default saved on the user profile the run belongs to, and to ‘general’ when none is saved. One of: researcher, marketer, sales, general, recruiter, custom .
assistantTemplateId string Identify your custom assistant template. required when assistantType is “custom”; otherwise optional and accepts ‘’ or null. The schema.default(‘’) is not persisted.
isIndividualFolder boolean Run the prompt separately per folder instead of once across everything. optional. The schema.default(false) is not persisted.
allowedValues string[] Restrict the answer to this list of values. optional, items must be strings, no item cap
allowedValuesMode string Choose whether the answer may pick one allowed value or several. optional; values come from AllowedValuesMode. The schema.default(‘multiple’) is not persisted. One of: single, multiple .
otherValues boolean Let the answer fall outside the allowed values list. optional
notApplicableValues string Say what the model should answer when nothing applies. optional, empty string allowed
fieldId string Write the answer into this single field. optional, accepts ‘’ or null
fieldIds string[] Extract several fields in one step. Sending at least one field ID makes prompt optional. optional, max 25 items. Over the cap the request is rejected with 400 and the message “A single AI step can extract at most 25 fields. Split the rest into another AI step.”
filter.rules – 3 more fields
Field Type Description
field string Name the field the rule reads. required, trimmed, min length 1, max length 100
op string Pick how the rule compares the field to the value. required. One of: eq, neq, contains, ncontains, startsWith, gt, lt, exists .
value string Give the value to compare against. You can send a string or a number. optional. Declared as a union.max(1000).allow(‘’), the schema), a string-or-number union.
composio – 6 more fields
Field Type Description
app string Name the Composio app to act on. required, trimmed, min length 1, max length 100
action string Name the action to run in that app. required, trimmed, min length 1, max length 200
connectedAccountId string Identify the connected account the action runs as. optional, trimmed, max length 100, empty string allowed
argsTemplate object Pass the action’s arguments. Values may contain tokens, so the server accepts any shape. optional, unconstrained object
destructive boolean Mark the action as destructive so it asks for confirmation. optional
acknowledged boolean Confirm you accept a destructive action. optional
speakUpload – 8 more fields
Field Type Description
name string Name the uploaded media. optional, max length 500, empty string allowed
folderId string Choose the folder the upload lands in. In dynamic routing this becomes the fallback folder instead. required (trimmed, min length 1, max length 100) unless folderRouting.mode is “dynamic”, in which case it is optional (trimmed, max 100, empty string allowed)
sourceMode string Say whether the upload comes from a URL or from a file already in the run. required. One of: url, file .
sourceUrl string Give the URL to fetch the media from. max length 2000; required when sourceMode is “url”, otherwise optional and may be an empty string. Not validated as a URI, because it may carry {tokens}.
fieldsMap object Map field names to values to set on the uploaded media. optional, keys and values must both be strings
language string Set the language for the upload. You can send a language code or a token that resolves at run time, so known codes are not enforced. optional, max length 100, empty string allowed
waitForProcessing boolean Hold the automation until the uploaded media finishes processing before the next step runs. optional
folderRouting object Route the upload to a folder chosen from the incoming payload instead of a fixed one. optional
folderRouting.mode string Choose between the fixed folderId and a folder picked from the payload. required inside folderRouting. One of: static, dynamic .
folderRouting.sourceKey string Name the payload key that holds the folder to route to. required (trimmed, min length 1, max length 500) when mode is “dynamic”; otherwise optional, trimmed, max length 500, empty string allowed
folderRouting.onNoMatch string Say what to do when no folder matches: create one, or fall back to the folderId. required when mode is “dynamic”, otherwise optional. One of: create, default .
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.

Get an API key on the Speak AI developer page.

Navigation

Get Speak AI

Web PlatformSign in or start free in your browser
Log inStart free
iOS appiPhone and iPadAndroid appPhones and tabletsMCP ServerConnect Claude, ChatGPT and other AI tools
All sections

Type to search…

↑↓ navigate↵ selectEsc close