Use this file to discover all available pages before exploring further.
Automations are the core server-side processes that power your Builder applications. They define what to do and when to do it, allowing you to create sophisticated workflows, integrate with external systems, and build intelligent applications.
Automations can be activated through different types of triggers, configured at the top of the automation graph:
URL (Webhook/API Endpoint)
When an automation activates its URL trigger, it becomes publicly available through a URL which you can copy from your Workspace graph or source code. You can then use this URL in external services that support webhooks.From inside the automation, 5 variables give access to input HTTP requests:
body: Request body
headers: Request headers
method: HTTP method (GET, POST, etc.)
query: URL query parameters
pathParams: Extracted path parameter values (when using path parameters like :id)
For multipart/form-data requests, uploaded files will be detailed within a body.<fileKey> object variable.
Example :
By default, these HTTP requests will receive the automation output as a response body. However, an $http variable available inside the automation gives full control over the response:
- set: name: $http value: chunk: # Data object that will be sent as an SSE event partial: "First part of response"- set: name: $http value: chunk: # Another chunk partial: "Second part of response"
$http is only available in the URL-triggered automation (not in children calls)
Headers cannot be set after the first chunk is sent
When using SSE events, the automation output will also be sent as the last event
Webhook endpoints support path parameters for building RESTful APIs. Path parameters allow you to define dynamic URL segments that extract values from incoming requests.Basic Usage:
Multi-segment Parameters (wildcards):Use *paramName instead of :paramName when the value can contain slashes — for instance, model identifiers like openai/text-embedding-3-large or hierarchical paths.
A request to /webhooks/{workspaceSlug}/v1/models/gpt-4o (no slash) matches the same endpoint with pathParams.model_id = "gpt-4o".
Path Parameter Behavior:
Single-segment parameters use :paramName syntax (e.g., :id, :userId) — they match one URL segment and reject values containing /
Multi-segment parameters use *paramName syntax — they match one or more segments and let you capture values containing /
All defined parameters are required - requests missing parameters will not match
Parameter values are automatically URL-decoded
Exact match endpoints take priority over pattern endpoints
When multiple patterns could match, the first defined pattern wins
Patterns like message:stream (colon without preceding slash) are treated as exact matches, not patterns
Path parameters must be defined in the endpoint field, not in the automation slug.The automation slug (e.g., get-user) only supports letters, numbers, spaces, underscores, and hyphens. To use path parameters, you must explicitly set the endpoint field to your desired path pattern:
slug: get-user # Slug without path parameters when: endpoint: "v1/users/:id" # Path parameters defined here
Using endpoint: true will expose the automation at the slug path, but the slug itself cannot contain : characters.
Events
An automation can listen to a list of events. Whenever such events are received, the automation is executed and can access:
payload: Event payload data
source: Event source information (source IP, correlationId, userId, automation, etc.)
These events can be:
Native events: Generated automatically by the platform
Custom events: Emitted from automations in the same workspace
App events: Emitted from installed Apps
Example configuration:
when: events: - user-login - document-uploaded
Workspaces can only listen to a specific subset of native events. See the Supported Native Events section for details.
Schedules
An automation can be regularly triggered based on cron expressions:
when: schedules: - '0 9 * * 1-5' # Run at 9:00 AM on weekdays
Automations can be scheduled at most every 15 minutes
Schedules use UTC timezone
When scheduled, the automation runs “on the hour” (e.g., a 20-minute schedule starting at 3:14 will run at 3:20, 3:40, etc.)
When successfully scheduled, a runtime.automations.scheduled event is emitted
A helpful tool for creating cron expressions is crontab.guru.
For authenticated users, session expiration is defined by the Gateway API (default 1 month).
For unauthenticated endpoint calls, sessions expire after 1 hour of inactivity.
global.studioUrl: Current studio instance public URL
global.pagesUrl: Current workspace pages public URL
global.pagesHost: Current pages instance base domain
global.endpoints: Map of available endpoint slugs to URLs
global.workspacesRegistry: Map of public workspaces
Custom workspace-wide variables
Socket Scope
Available for the current websocket connection
Access pattern: {{socket.variable}}Socket scope provides a temporary state local to a websocket connection, useful for separating state between multiple browser tabs. This context automatically expires after 6 hours without any updates.
Config Scope
Workspace and app configuration
Access pattern: {{config.variable}}Contains the workspace configuration defined in the workspace settings.
$workspace Scope
Read-only workspace information
Access pattern: {{$workspace.variable}}This read-only context holds the current workspace definition, allowing access to any of its sections (e.g., installed apps config via $workspace.imports.myApp.config).
Except for $workspace, all these contexts can be written to using the set instruction. Written data will be persisted and available in subsequent requests. However, when setting variables inside session/user contexts from an unauthenticated webhook, they will not be persisted.
Inside your automation instructions, dynamic data can be injected by surrounding a variable name with double braces: {{some.variable.name}}.Variables can be created and modified using the set instruction and removed using the delete instruction.For objects or arrays, you can access specific properties:
# Basic property access{{user.profile.name}}# Dynamic property access using another variable{{session.myObjectVariable[{{item.field}}]}}
If session.myObjectVariable equals {"mickey": "house"} and item.field equals mickey, the entire expression resolves to house.
Loop through items or execute instructions multiple times.
# Iterate through an array- repeat: on: '{{users}}' do: - set: name: processedUsers[] value: '{{item.name}}'# Execute a fixed number of times- repeat: until: 5 do: - set: name: counter value: '{% {{$index}} + 1 %}'
You can also process batches in parallel:
- repeat: on: '{{workQueue}}' batch: size: 3 # Process 3 items by 3 items in parallel interval: 500 # Pause 500ms between batches do: - process: item: '{{item}}'
Break
Stop execution of the current automation or loop.
- break: scope: repeat # Breaks out of the nearest repeat loop- break: scope: automation # Stops the current automation- break: scope: all # Stops all parent automations too payload: reason: "Operation cancelled"
When break is meant to be handled from a parent automation’s try/catch, scope must be set to all.If using the instruction like this : - break: {}, it will default to scope: automation.
# Basic GET request - fetch: url: https://api.example.com/users method: GET headers: Authorization: Bearer {{secret.apiToken}} output: apiResponse # POST request with JSON body - fetch: url: https://api.example.com/users method: POST body: name: "New User" email: "user@example.com" output: createResponse
Retrieve response headers and status with outputMode: detailed_response :
# Detailed response with headers - fetch: url: https://api.example.com/status outputMode: detailed_response output: fullResponse # Access `{{fullResponse.body}}`, `{{fullResponse.headers}}` and `{{fullResponse.status}}`
Other outputMode :
base64 : return the base64 encoded response body
data_url : return the response body encoded as a data_url
- fetch: url: https://api.example.com/upload method: POST multipart: - fieldname: file value: "{{fileContent}}" # Can be an ascii string, a base64 encoded string or a buffer array filename: report.pdf # Required if value is a file contentType: application/pdf - fieldname: metadata value: "{{fileMetadata}}" output: uploadResult
- fetch: url: '...' headers: Content-Type: application/x-www-form-urlencoded body: foo: bar
By default, HTTP responses indicating a content-type: text/event-stream header will force their responseMode to detailed_response, and their {{output.body}} will be a stream that can be read in real time from the calling automation :
Here, the repeat instruction will block until all chunks have been processed & the HTTP socket is closed.
Each {{item}} will look like this :
{ "chunk": { "data": [ "data1", "data2" ] }}
Here, data1 and data2 correspond to 2 individual chunks written by the remote server, which can be grouped together if they were received at the same time.
If these data strings are valid JSON, they will be automatically parsed into objects.Alternatively, we can emit received chunks so they can be processed asynchronously & concurrently from other automations :
- fetch: url: .. stream: event: chunk payload: foo: bar
Generate authentication tokens for internal API calls.
This token cannot be used outside of automations, and is specifically intented for fetch consumption (as an Authorization header).
When fetching a Prismeai automation endpoint with such workspace token, a {{run.authenticatedWorkspaceId}} variable (which cannot be manually set) will be made available to securely check calling workspace.
You can also forward source workspace authentication to a subsequent fetch :
Manage user subscription topics.User topics allow sending events to multiple users without knowing who they are in advance, automatically granting them read access to these events without requiring any API Key.
# Create a user topic- createUserTopic: topic: project-updates userIds: - "{{user1Id}}" - "{{user2Id}}"# Add users to a topic- joinUserTopic: topic: project-updates userIds: # Defaults to current user.id - "{{newUserId}}"
User topics allow sending events to multiple users without knowing who they are in advance.
Run is a generic instruction allowing you to call runtime modules.
These are lightweight NodeJS packages offering various methods for use cases needing raw Javascript for better performances than standard automations.Example :
Conditions allow you to execute different instructions based on contextual information. You can use a powerful expression syntax in conditions and anywhere with {% ... %} delimiters.
# Comparison operators{{someAge}} > 18{{someAge}} >= 18{{someAge}} < 18{{someAge}} <= 18{{someAge}} == 18{{someAge}} = 18{{cityName}} = "Toulouse"# Inequality{{someAge}} !== 18{{someAge}} != 18# String matching"hello" matches "hel""hello" matches {{someArray}}# Variable checking{{testedVariable}} # Is this variable defined?!{{testedVariable}} # Is this variable empty?# Membership testing{{someValue}} in {{someList}}{{someKey}} in {{someObject}}{{someKey}} not in {{someObject}}{{someKey}} not in "my,string,list"# Type checkingisArray({{someVariable}})isObject({{someVariable}})isString({{someVariable}})isNumber({{someVariable}})
rand(50, 150) # Random number between 50 and 150rand() # Random float between 0 and 1number("42") # 42 — parse a string to integerround(10.2) # 10round(10.2, 1) # 10.2round(10.26, 1) # 10.3floor(10.9) # 10floor(10.26, 1) # 10.2ceil(10.1) # 11ceil(10.9) # 11
When calling a native instruction or another automation, different arguments can be transmitted. These graphical inputs are not reserved to native instructions, but can also be configured for your own custom automations by specifying expected arguments and their types.
The someToken argument defined with secret: true is automatically redacted from native runtime events to avoid accidental leaks of sensitive information.
Arguments support various validation formats including date, url, time, password, etc. Validation errors immediately stop current and parent automations.
Break complex flows into smaller automationsUse events for communication between modulesCreate reusable patterns for common tasksDocument automation purposes and interfaces
Error Handling
Build robust fault tolerance:
Use try/catch blocks for risky operationsImplement appropriate retry strategiesProvide informative error messagesCreate fallback paths for critical operations
State Management
Handle data appropriately across scopes:
Use appropriate memory scopes for different data needsClean up temporary variables when finishedInitialize variables before using themBe mindful of persistence requirements
Security Best Practices
Keep your automations secure:
Store sensitive data in secretsValidate inputs from external sourcesImplement rate limiting for external APIsUse proper authentication for API calls
Performance Optimization
Ensure efficient execution:
Use parallel processing for independent operationsImplement batching for large data setsCache results when appropriateMonitor execution times and optimize bottlenecks
Testing
Validate automation functionality:
Test with representative data samplesVerify error handling pathsTest edge cases and unexpected inputsUse Activity view to review execution history
