--- title: "Create Automation" method: POST path: "/automations" tags: ["Automations"] --- # Create Automation `POST /automations` ## Request - Base URL: `https://api.speakai.co/v1` - URL: `https://api.speakai.co/v1/automations` - Auth: API key in header `x-speakai-key` and API key in header `x-access-token` 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 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 - object - `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 - `type` 'folders' | 'tags' | 'keywords' | 'composio' | 'webhook': Pick the kind of event that starts the automation. required inside trigger; values come from the AutomationTrigger list - `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` 'speak' | 'composio': Say which system owns the trigger. optional; the two values are written inline in the schema, not drawn from an enum - `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 - `fieldId` string: Identify the field to match on. required inside each entry, trimmed, min length 1, max length 100 - `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` 'AND' | 'OR': Choose whether every fieldValueMatches entry has to match or just one. Leaving it out behaves like OR. optional - `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` 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 - `type` 'folders' | 'tags' | 'keywords' | 'composio' | 'webhook': Pick the kind of event for this alternative trigger. optional here, unlike trigger.type which is required - `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` 'speak' | 'composio': Say which system owns this alternative trigger. optional - `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` 'AND' | 'OR': Choose whether every fieldValueMatches entry has to match or just one for this alternative trigger. optional - `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` object[], required: List the steps the automation runs, in order. required, min 1 entry, max 20 entries - `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` 'trigger' | 'magic-prompt' | 'translation' | 'composio-action' | 'filter' | 'speak-upload' | 'notify' | 'outbound-webhook' | 'condition': Say what kind of work the step does. This decides which config object the step must carry. required; values come from the AutomationStepType list - `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. - `title` string: Title the prompt so you can recognize its output later. optional, empty string allowed, no length cap - `modelId` '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': 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. - `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` 'researcher' | 'marketer' | 'sales' | 'general' | 'recruiter' | 'custom': 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. - `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` 'single' | 'multiple': 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. - `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." - `translation` object: Configure a translation step. required when stepType is "translation", rejected for any other stepType - `targetLanguage` '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': 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. - `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. - `logic` 'AND' | 'OR': 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. - `rules` object[]: List the conditions the filter checks. required, min 1 entry, max 20 entries - `field` string: Name the field the rule reads. required, trimmed, min length 1, max length 100 - `op` 'eq' | 'neq' | 'contains' | 'ncontains' | 'startsWith' | 'gt' | 'lt' | 'exists': 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 - `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. - `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. - `logic` 'AND' | 'OR': Choose whether every rule has to match or just one. optional. The declared default is 'AND' but the default is not persisted. - `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 - `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` object: Configure a step that uploads media into Speak. required when stepType is "speak-upload", rejected for any other stepType - `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` 'url' | 'file': Say whether the upload comes from a URL or from a file already in the run. required - `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 - `mode` 'static' | 'dynamic': Choose between the fixed folderId and a folder picked from the payload. required inside folderRouting, so sending folderRouting without mode returns a 400 - `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 - `onNoMatch` 'create' | 'default': 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. - `notify` object: Configure a notification step. required when stepType is "notify", rejected for any other stepType - `channel` 'in_app' | 'email' | 'slack': Pick where the notification goes. required; the three values are written inline in the schema - `target` string: Name the recipient, such as an email address or a Slack channel. optional, max length 500, empty string allowed - `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. - `emailContent` 'transcript' | 'ai_response': For the email channel, choose what the email carries. optional - `outboundWebhook` object: Configure a step that calls a URL of yours. required when stepType is "outbound-webhook", rejected for any other stepType - `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 - `method` 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE': 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. - `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 - `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` 'true' | 'false': 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. - `runType` 'instant' | 'schedule' | '': 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. - `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 - `timePeriod` 'today' | 'yesterday' | 'last7days' | 'last14days' | 'thisWeek': 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. - `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. ## Response `200` Success --- [API](https://skmtc.dev/speakai/apis/speak-ai-api.md) · [All operations](https://skmtc.dev/speakai/apis/speak-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/speakai/apis/speak-ai-api/revisions/52d777e6d46e?raw)