overview
| Field | Description | Type | Required |
|---|---|---|---|
actionId | Identifier for the action, prefixed with the connector key to form its MCP tool name. | string | Yes |
actionType | Operation kind the engine treats this action as. Allowed: list, get, create, update, delete, custom, refresh_token, event, unknown | enum | Yes |
annotations | Explicit MCP tool-annotation overrides. Any field set here wins over the hint derived from effects. | object | No |
authRequirements | Per-authentication-method scopes required to run the action. Supersedes the deprecated requiredScopes. | object | No |
categories | Business-domain classifications used for filtering the action. | string[] | Yes |
compositeIdentifiers | Configuration for building a record id from multiple provider fields. | object | No |
cursor | Engine-managed cursor pagination configuration. | object | No |
dataSync | Data Sync configuration for bulk syncing this action’s records. | object | No |
description | Short description shown in the UI and MCP tool declarations. | string | Yes |
details | Extended context about the action for agents and developers. Used as the MCP tool description in place of description when set. | string | No |
effects | Semantic effects the action performs, used for MCP annotations and dashboard filtering. | string[] | No |
entrypointHttpMethod | HTTP method of the primary request. | string | No |
entrypointUrl | URL path of the action’s primary request. Paired with entrypointHttpMethod to form the action key such as GET /employees, and used as the request log URL. | string | No |
examples | Example input values for the action, each optionally labeled with exampleDescription. | object[] | No |
executionMode | Whether the action runs synchronously or is dispatched to an async workflow. An action with a browser_use step must be async.Allowed: sync, async | enum | No |
fieldConfigs | Field-level mapping and typing configuration for the result. | array | No |
inputs | Parameters the action accepts, forming its tool input schema. | object[] | No |
label | Human-readable display name for the action. | string | Yes |
prerequisiteActions | Action ids this action declares as dependencies. | string[] | No |
providerEvents | Provider event names this action handles. | string[] | No |
releaseStage | Maturity level of the action. Allowed: preview, beta, ga, deprecated, internal | enum | No |
requiredScopes | Permission scopes required to run the action. Deprecated; use authRequirements. | string | No |
resources | URL to provider documentation for this action. | string | No |
responses | Documented HTTP responses the action can return. | object[] | No |
result | Data returned to the caller, given as an expression or a map of output keys to expressions. | union | No |
schema | Name of the output schema the action conforms to. | string | No |
schemaType | Whether the output follows the native provider shape or the unified StackOne schema. Allowed: native, unifiedDefault: native | enum | Yes |
steps | Ordered steps executed to carry out the action. A single step runs one step function, and an iterator step runs step functions over each item of an array. | array | Yes |
tags | Free-form tags for grouping and filtering the action. | string[] | No |
userScoped | The action answers for the acting user, filtering the provider by $.user. The engine refuses the call when there is no acting user email. The object form also checks each returned record against the caller. | union | No |
validationRules | Cross-field validation rules applied to the action inputs. | array | No |
Action types
Action types
actionType tells the engine how to treat the operation.Unified types (list, get, create, update, delete) return normalized data:- Consistent response schemas across providers.
- Cross-provider compatibility.
- Automatic pagination handling.
- Normalized error responses.
list action always returns { data: [...], next: <cursor or null> }.Custom (custom) returns the raw provider response, with no schema normalization. Use it for provider-specific endpoints that need full flexibility.Special-purpose types are used in other blocks, not actions[]:event— an event handler underevents.actionsthat runs when a matching provider event arrives (matched viaproviderEvents). Same shape as a regular action.refresh_token— the credential-refresh action underrefreshAuthentication.
annotations
Explicit MCP tool-annotation overrides. Any field set here wins over the hint derived fromeffects.
| Field | Description | Type | Required |
|---|---|---|---|
destructiveHint | Whether the action may delete or overwrite data. | boolean | No |
idempotentHint | Whether repeating the action has no additional effect. | boolean | No |
openWorldHint | Whether the action interacts with an open, external world. | boolean | No |
readOnlyHint | Whether the action only reads data. | boolean | No |
title | Human-readable title exposed to MCP clients. | string | No |
authRequirements
Per-authentication-method scopes required to run the action. Supersedes the deprecatedrequiredScopes.
Examples
compositeIdentifiers
Configuration for building a record id from multiple provider fields.| Field | Description | Type | Required |
|---|---|---|---|
enabled | Whether composite identifiers are built for records. | boolean | Yes |
fields | Field mappings that make up each composite identifier. | object[] | No |
version | Version of the composite identifier encoding. | number | No |
compositeIdentifiers.fields
compositeIdentifiers.fields
| Field | Description | Type | Required |
|---|---|---|---|
components | Ordered output field keys whose values combine into the identifier. | string[] | Yes |
remote | Provider field the identifier component is read from. | string | No |
targetFieldKey | Key the composite identifier is written to. | string | Yes |
cursor
Engine-managed cursor pagination configuration.| Field | Description | Type | Required |
|---|---|---|---|
enabled | Whether cursor pagination is enabled. Only applies to list actions and has no effect on others. | boolean | Yes |
pageSize | Number of records requested per page. | number | Yes |
dataSync
Synced records are stored for reading with Deep Query. See Data Sync. Data Sync configuration for bulk syncing this action’s records.| Field | Description | Type | Required |
|---|---|---|---|
allowed | Whether Data Sync is enabled for this action. | boolean | Yes |
dataKey | Path within the step output to the records array, used when the action returns them in a single call rather than paginating. | string | No |
failureConditions | Conditions that mark the provider’s answer as wrong. When any matches on a full sync’s last page, the run fails and the previous sync stays live. | object[] | No |
incremental | Change-tracking configuration for incremental syncs. | union | No |
indexField | Field or fields forming each record’s primary key during sync. Must uniquely identify each record; a value shared across records collapses them and a record missing it is dropped. | union | Yes |
lookback | Provider filter that limits every sync, full and incremental, to records after a start date the customer picks per sync config. Ideally filters on a field that never changes on a record, such as a created date. | object | No |
maxDurationMinutes | Maximum time a single sync run may take. | integer | No |
maxPages | Maximum number of pages fetched in a single sync run. | integer | No |
pagination | Pagination strategy used while syncing. | union | No |
verifyDeletions | How a full sync checks a record missing from the listing before reporting it deleted. Used only when the connector profile turns verification on. | object | No |
dataSync.failureConditions
dataSync.failureConditions
| Field | Description | Type | Required |
|---|---|---|---|
condition | Expression evaluated against a full sync’s last page; true fails the run. Reads the action result at $, response headers at $.headers and run totals at $.sync. | string | Yes |
errorMessage | Why the run failed, shown in the run history when the condition matches. | string | Yes |
dataSync.incremental
dataSync.incremental
- time_filter
- delta_token
| Field | Description | Type | Required |
|---|---|---|---|
format | Encoding of the timestamp value: iso8601, unix_seconds, or unix_millis.Allowed: iso8601, unix_seconds, unix_millis | enum | Yes |
iterator | Names the request parameter carrying the last-sync timestamp and where on the request to place it. | object | Yes |
response | Configures reading the newest record timestamp from each page to advance the watermark. | object | No |
safetyBufferSeconds | Seconds subtracted from the run start time when falling back to the local clock so records near the boundary are not skipped. Default: 60 | integer | Yes |
type | Selects the updated-since strategy where each sync requests only records changed after the last watermark. | string | Yes |
dataSync.incremental.time_filter.iterator
dataSync.incremental.time_filter.iterator
| Field | Description | Type | Required |
|---|---|---|---|
in | Where to add the timestamp parameter: query, body, or headers.Allowed: query, body, headers | enum | Yes |
key | Request parameter name the last-sync timestamp is sent under. | string | Yes |
dataSync.incremental.time_filter.response
dataSync.incremental.time_filter.response
| Field | Description | Type | Required |
|---|---|---|---|
updatedAtPath | Path within each returned record to its last-updated timestamp, read to advance the watermark. | string | Yes |
dataSync.lookback
dataSync.lookback
| Field | Description | Type | Required |
|---|---|---|---|
defaultWindow | ISO 8601 duration used to prefill the start date for new sync configs, counted back from today (e.g. P2Y). | string | Yes |
format | Encoding of the start date value: iso8601, unix_seconds, or unix_millis.Allowed: iso8601, unix_seconds, unix_millis | enum | Yes |
iterator | Names the provider filter that limits a sync to records after the start date, and where on the request to place it. | object | Yes |
dataSync.lookback.iterator
dataSync.lookback.iterator
| Field | Description | Type | Required |
|---|---|---|---|
in | Where to add the lookback parameter: query, body, or headers.Allowed: query, body, headers | enum | Yes |
key | Request parameter name the lookback start date is sent under. Must differ from the incremental iterator key. | string | Yes |
dataSync.pagination
dataSync.pagination
- cursor
- offset
- page
| Field | Description | Type | Required |
|---|---|---|---|
iterator | Request parameter that carries the next-page cursor. | object | Yes |
response | How records and the next-page cursor are located in the response. | object | Yes |
stopCondition | JEXL expression evaluated against each response to stop paging, with response headers at $.headers (lowercased). Defaults to stopping when the resolved next-page cursor is null. | string | No |
type | Selects the cursor-based pagination strategy. | string | Yes |
dataSync.pagination.cursor.iterator
dataSync.pagination.cursor.iterator
| Field | Description | Type | Required |
|---|---|---|---|
in | Where to add the pagination parameters: query, body, or headers.Allowed: query, body, headers | enum | Yes |
key | Request parameter the next-page cursor is sent in. | string | Yes |
dataSync.pagination.cursor.response
dataSync.pagination.cursor.response
| Field | Description | Type | Required |
|---|---|---|---|
dataKey | Response key holding the array of records for each page. | string | Yes |
nextKey | Response key for the next-page cursor: a dot-path into the action result, or a {{ }} expression evaluated against the result with response headers at $.headers (lowercased). | string | Yes |
dataSync.verifyDeletions
dataSync.verifyDeletions
| Field | Description | Type | Required |
|---|---|---|---|
action | Unprefixed actionId, as written in this YAML, of the action that fetches one record. Must not be the list action itself. | string | Yes |
exists | Bare JEXL over { statusCode, data, headers, record }. True means the provider still has the record; anything else reports it deleted. | string | Yes |
inputs | Inputs for that action, grouped by location. Each value is a JSONPath, a literal or a '' expression, evaluated against { record }, the stored record in its provider shape. | object | Yes |
paramChecks | Per list-action input, a bare JEXL over the exists scope plus value, the sync’s value for that input. True means the record is still in the sync’s scope. | object | No |
dataSync.verifyDeletions.inputs
dataSync.verifyDeletions.inputs
{ record }, the stored record in its provider shape.| Field | Description | Type | Required |
|---|---|---|---|
body | Inputs sent in the body, keyed by input name. | object | No |
headers | Inputs sent in the headers, keyed by input name. | object | No |
path | Inputs sent in the path, keyed by input name. | object | No |
query | Inputs sent in the query, keyed by input name. | object | No |
- cursor
- offset
- page
- time_filter
- delta_token
Failure conditions
Some providers answer a bad request with a200. The records key is missing, the body carries an error, or a list that should match people comes back empty. failureConditions tells the sync what a wrong answer from this provider looks like.
On the last page of a full sync, each condition runs in order. The first one that returns true fails the run with its errorMessage. The previous sync stays live and no events go out. A condition that cannot be evaluated is skipped and logged, so a mistake in one never blocks the sync. Incremental syncs don’t run them, since an empty last page is normal there.
A condition can read:
effects
Semantic effects the action performs, used for MCP annotations and dashboard filtering. Optional, but worth setting on every action so an MCP client can auto-approve reads and prompt before writes.[read, write].
How effects become MCP annotations
How effects become MCP annotations
effects and no annotations override, no hints are emitted, so a read looks no safer than a delete.examples
Example input values for the action, each optionally labeled withexampleDescription.
| Field | Description | Type | Required |
|---|---|---|---|
exampleDescription | Explains what this usage example demonstrates. | string | No |
fieldConfigs
Field-level mapping and typing configuration for the result. Examplesinputs
Parameters the action accepts, forming its tool input schema.| Field | Description | Type | Required |
|---|---|---|---|
array | Whether the input accepts a list of values. Default: false | boolean | Yes |
arrayFormat | How a list input’s values are formatted in the request, such as repeated, comma-separated, or bracketed. Currently not in use. Allowed: repeat, brackets, comma, stringify | enum | No |
description | Explains the input for callers and generated tool schemas. | string | Yes |
in | Part of the HTTP request this input is placed in. Allowed: body, query, path, headers | enum | Yes |
name | Parameter name exposed to callers and mapped into the request. | string | Yes |
oneOf | Allowed values when the input is an enum. | union | No |
properties | Nested inputs when the input is an object. Each has the same shape as a top-level input, minus in. | object[] | No |
required | Whether the caller must supply this input. | boolean | Yes |
rules | Validation rules applied to the input value. | object | No |
type | Data type of the input value. Allowed: string, number, boolean, datetime_string, object, enum | enum | No |
variants | An input that accepts more than one type. Provide at least two variants, each defining one of those types the way an input does. The input itself sets no top-level type, array, properties, oneOf, or rules. | object[] | No |
inputs.oneOf
inputs.oneOf
- Option 1
- Option 2
| Field | Description | Type | Required |
|---|---|---|---|
values | Explicit list of allowed enum values. | string[] | Yes |
inputs.rules
inputs.rules
| Field | Description | Type | Required |
|---|---|---|---|
errorMessage | Message shown when the value violates a rule. | string | No |
format | Named format the value must conform to. Allowed: email, url, uri, uuid, date, datetime | enum | No |
max | Maximum numeric value allowed. | number | No |
maxLength | Maximum number of characters the value may have. | number | No |
min | Minimum numeric value allowed. | number | No |
minLength | Minimum number of characters the value must have. | number | No |
pattern | Regular expression the value must match. | string | No |
responses
Documented HTTP responses the action can return.| Field | Description | Type | Required |
|---|---|---|---|
description | What this response status means. | string | Yes |
statusCode | HTTP status code being documented. | number | Yes |
result
Data returned to the caller, given as an expression or a map of output keys to expressions. Examples- Expression
- Object map
steps
See Step Functions for the full catalog and their parameters. Ordered steps executed to carry out the action. A single step runs one step function, and an iterator step runs step functions over each item of an array.- Single step
- Iterator step
| Field | Description | Type | Required |
|---|---|---|---|
condition | JEXL expression gating whether this step runs. | string | No |
description | Explains what this step does. | string | Yes |
ignoreError | Whether a failure in this step is ignored so execution continues. | boolean | No |
onConditionError | How to behave when the condition expression errors: false (default) skips the step, true runs it anyway, and break halts the action.Allowed: true, false, break | enum | No |
stepFunction | Step function executed by this step. | object | Yes |
stepId | Identifier for this step, used to reference its output. | string | Yes |
steps.Single step.stepFunction
steps.Single step.stepFunction
| Field | Description | Type | Required |
|---|---|---|---|
functionName | Name of the step function to execute. | string | Yes |
parameters | Arguments passed to the step function. | object | Yes |
version | Version of the step function to use. | string | No |
userScoped
Set on an action that answers for the person calling it, not for the credential it runs on. Use it when a connector authenticates with a single admin-level key but each caller should only see their own records. Scoping happens in two places, and the second is optional:- The request. The action filters or queries the provider by
$.user.email(see Available contexts), either with a filter or search parameter, or with a lookup that resolves the email to the provider’s own user ID and then calls a per-user endpoint. This does the real work, so the provider has to support being queried by email. - The response. With the object form,
userScoped.identitylists JSONPath expressions into each record of the response’sdata. StackOne keeps a record only when one of them resolves to the caller’s email, compared trimmed and lowercased on both sides, and drops every other record. This catches a provider that ignores the filter or returns records for other people.
userScoped: true, there is no response check. The request is the whole of the scoping, and a call with no acting user email is still refused. Use identity where each record carries something that names its owner.
The caller’s email is trimmed and lowercased before an action sees it. The response check normalizes the provider’s side the same way, so a difference in case doesn’t matter there. A filter parameter is matched by the provider itself, so its own case handling applies.
With identity set:
- A single record that isn’t the caller’s is refused with a
403(USER_SCOPE_VIOLATION_ERROR), and so is a response with nodata. - Every key of the response other than
dataandnextis dropped, since nothing outsidedatacan be checked. - A record with no value at any
identitypath is dropped. - On a direct call, omitted records are logged, so a filter that isn’t working shows up.
userScoped action, raw step outputs are left out of the response, including on a debug request, because they are the provider’s answer before scoping.
StackOne refuses a userScoped action with a 403 (ACTING_USER_REQUIRED_ERROR) whenever the call carries no acting user email, rather than running it on the key alone. That applies to a direct call, to a call_action step that reaches the action, and to an authentication test action. A refused direct call shows in the action logs like any other failed call.
- A
userScopedaction can’t setdataSync.allowed, because a sync runs with no user. identitycan’t be used on an action that downloads a file, because a stream has no records to check.- Each
identityentry must be a JSONPath expression starting with$..
- To scope an operation for some callers and not others, keep two actions: a
userScopedone such asget_my_goals, alongside the unscopedget_user_goals. Where everyone on a Connector Profile should be scoped, enable only theuserScopedone there. See Scoping connectors. - An action that reads
$.userwithoutuserScopedtreats it like any optional input: when the caller has no user, an argument built from it is left out of the request. That suits an optional attribution header, but not a filter the action depends on, because the call would then return everyone’s records. SetuserScopedwhenever the action has no meaning without the user.
validationRules
Cross-field validation rules applied to the action inputs.- atLeastOneOf
- requiredIf
- mutuallyExclusive
| Field | Description | Type | Required |
|---|---|---|---|
errorMessage | Message shown when the rule is violated. | string | No |
fields | Input names of which at least one must be provided. | string[] | Yes |
rule | Requires at least one of the listed inputs to be provided. | string | Yes |
- atLeastOneOf
- requiredIf
- mutuallyExclusive