Actions

Field reference for the operations a connector exposes: inputs, steps, fieldConfigs, result, responses, cursor, dataSync, executionMode, compositeIdentifiers, validationRules, and examples.

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 for the action.	object	No
authRequirements	Per-authentication-method scopes required to run the action.	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.	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. 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.	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, unified Default: native	enum	Yes
steps	Ordered steps executed to carry out the action.	array	Yes
tags	Free-form tags for grouping and filtering the action.	string[]	No
validationRules	Cross-field validation rules applied to the action inputs.	array	No

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.

A 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 under events.actions that runs when a matching provider event arrives (matched via providerEvents). Same shape as a regular action.
• refresh_token — the credential-refresh action under refreshAuthentication.

Examples

actions:
  - actionId: list_tickets
    actionType: custom
    effects: [read]
    label: List tickets
    description: List tickets from the provider.
    inputs:
      - name: limit
        description: Maximum number of results to return.
        type: number
        in: query
        required: false
      - name: offset
        description: Number of results to skip.
        type: number
        in: query
        required: false
    steps:
      - stepId: list_tickets_request
        description: Fetch tickets from the provider.
        stepFunction:
          functionName: request
          parameters:
            url: /tickets
            method: get
            args:
              - name: limit
                value: $.inputs.limit
                in: query
                condition: '{{present(inputs.limit)}}'
              - name: offset
                value: $.inputs.offset
                in: query
                condition: '{{present(inputs.offset)}}'
    result:
      data: $.steps.list_tickets_request.output.data

annotations

Explicit MCP tool-annotation overrides for the action.

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

Examples

annotations:
  title: List employees
  readOnlyHint: true
  destructiveHint: false
  idempotentHint: true
  openWorldHint: false

authRequirements

Per-authentication-method scopes required to run the action.

Examples

authRequirements:
  oauth2:
    - employees:read
  api_key:
    - employees:read

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

Field mappings that make up each composite identifier.

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

Examples

compositeIdentifiers:
  enabled: true
  version: 1
  fields:
    - targetFieldKey: id
      remote: '$.record.identifier'
      components: [tenant_id, employee_id]

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

Examples

cursor:
  enabled: true
  pageSize: 100

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
incremental	Change-tracking configuration for incremental syncs.	union	No
indexField	Field or fields forming each record’s primary key during sync.	union	Yes
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

dataSync.incremental

Change-tracking configuration for incremental syncs.

time_filter

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

Names the request parameter carrying the last-sync timestamp and where on the request to place it.

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

Configures reading the newest record timestamp from each page to advance the watermark.

Field	Description	Type	Required
updatedAtPath	Path within each returned record to its last-updated timestamp, read to advance the watermark.	string	Yes

delta_token

Field	Description	Type	Required
iterator	Names the request parameter carrying the previous delta token and where on the request to place it.	object	Yes
response	Configures reading the next delta token from the response.	object	Yes
type	Selects the delta-token strategy where each sync sends the token returned by the previous sync.	string	Yes

dataSync.incremental.delta_token.iterator

Names the request parameter carrying the previous delta token and where on the request to place it.

Field	Description	Type	Required
in	Where to add the delta token: query, body, or headers. Allowed: query, body, headers	enum	Yes
key	Request parameter name the delta token is sent under.	string	Yes

dataSync.incremental.delta_token.response

Configures reading the next delta token from the response.

Field	Description	Type	Required
onlyOnFinalPage	When true, read the delta token only from the final page of results.	boolean	No
path	Path within the response to the delta token used for the next sync.	string	Yes

dataSync.pagination

Pagination strategy used while syncing.

cursor

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	Expression evaluated against each response to stop paging. Defaults to stopping when the next-page cursor key is null.	string	No
type	Selects the cursor-based pagination strategy.	string	Yes

dataSync.pagination.cursor.iterator

Request parameter that carries the next-page cursor.

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

How records and the next-page cursor are located in the response.

Field	Description	Type	Required
dataKey	Response key holding the array of records for each page.	string	Yes
nextKey	Response key holding the cursor for the next page.	string	Yes

offset

Field	Description	Type	Required
iterator	Request parameters that page through results by offset and limit.	object	Yes
response	How each page of records is located in the response.	object	Yes
stopCondition	Expression evaluated against each response to stop paging. Defaults to stopping when the data key returns no records.	string	No
type	Selects the offset-based pagination strategy.	string	Yes

dataSync.pagination.offset.iterator

Request parameters that page through results by offset and limit.

Field	Description	Type	Required
defaultLimit	Number of records requested per page. Defaults to 100 when omitted.	number	No
in	Where to add the pagination parameters: query, body, or headers. Allowed: query, body, headers	enum	Yes
limitKey	Request parameter set to the number of records requested per page.	string	Yes
offsetKey	Request parameter set to the number of records to skip for each page.	string	Yes

dataSync.pagination.offset.response

How each page of records is located in the response.

Field	Description	Type	Required
dataKey	Response key holding the array of records for each page.	string	Yes

page

Field	Description	Type	Required
iterator	Request parameters that page through results by page number.	object	Yes
response	How each page of records is located in the response.	object	Yes
stopCondition	Expression evaluated against each response to stop paging. Defaults to stopping when the data key returns no records.	string	No
type	Selects the page-number pagination strategy.	string	Yes

dataSync.pagination.page.iterator

Request parameters that page through results by page number.

Field	Description	Type	Required
defaultPageSize	Number of records requested per page. Defaults to 100 when omitted.	number	No
in	Where to add the pagination parameters: query, body, or headers. Allowed: query, body, headers	enum	Yes
pageKey	Request parameter set to the page number for each request.	string	Yes
pageSizeKey	Request parameter set to the number of records requested per page. Omit when the endpoint takes no page-size parameter.	string	No
startPage	Page number requested for the first page. Defaults to 1 when omitted.	number	No

dataSync.pagination.page.response

How each page of records is located in the response.

Field	Description	Type	Required
dataKey	Response key holding the array of records for each page.	string	Yes

Examples

cursor

dataSync:
  allowed: true
  indexField: id
  pagination:
    type: cursor
    response:
      dataKey: data
      nextKey: next
    iterator:
      key: next
      in: query
  incremental: { ... }

offset

dataSync:
  allowed: true
  indexField: id
  pagination:
    type: offset
    response:
      dataKey: data.data
    iterator:
      offsetKey: offset
      limitKey: limit
      in: query
  incremental: { ... }

page

dataSync:
  allowed: true
  indexField: id
  pagination:
    type: page
    response:
      dataKey: data.records
    iterator:
      pageKey: page
      pageSizeKey: per_page
      startPage: 1
      in: query
  incremental: { ... }

time_filter

dataSync:
  allowed: true
  indexField: id
  pagination: { ... }
  incremental:
    type: time_filter
    iterator:
      key: updated_since
      in: query
    format: iso8601

delta_token

dataSync:
  allowed: true
  indexField: id
  pagination: { ... }
  incremental:
    type: delta_token
    iterator:
      key: after
      in: query
    response:
      path: data.cursor

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.

Effect	Use for
read	Fetching a record or a list. Changes nothing.
search	Querying with filters. Changes nothing.
write	Creating or updating records.
delete	Removing records.
execute	Operations that aren’t CRUD: send, sync, deploy, approve, merge.

An action can carry more than one effect. A find-or-create gets [read, write].

How effects become MCP annotations

Annotation	Derived from
readOnlyHint	true when every effect is read or search.
destructiveHint	true when effects include delete.
openWorldHint	Always true, since actions call external provider APIs.
title	The action’s label.
idempotentHint	Never derived. Set it with annotations.

With no effects and no annotations override, no hints are emitted, so a read looks no safer than a delete.

Annotations are hints, not enforcement. Clients use them for grouping and approval defaults, not as a security boundary. To actually restrict what a linked account can call, disable the actions on its Connector Profile. See Scoping connectors.

Examples

effects:
  - read

examples

Example input values for the action, each optionally labeled with exampleDescription.

Field	Description	Type	Required
exampleDescription	Explains what this usage example demonstrates.	string	No

Examples

examples:
  - exampleDescription: Fetch a single active employee.
    input:
      employee_id: emp_123
    output:
      id: emp_123
      name: Ada Lovelace
      status: active

  - exampleDescription: Employee not found.
    input:
      employee_id: emp_does_not_exist
    output:
      error: not_found
      statusCode: 404

fieldConfigs

Field-level mapping and typing configuration for the result.

Examples

fieldConfigs:
  - targetFieldKey: id
    alias: employee_id
    type: string
  - targetFieldKey: name
    expression: '${item.first_name} ${item.last_name}'
    type: string
  - targetFieldKey: country
    alias: country_code
    type: string
    enumMapper:
      matcher: country_alpha2code_by_country_name
  - targetFieldKey: address
    type: object
    properties:
      - { targetFieldKey: street, alias: street_address, type: string }
      - { targetFieldKey: city, alias: city, type: string }
  - targetFieldKey: salary
    type: number
    requiredScopes: read:compensation   # hidden if scope not granted

inputs

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.	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	Alternative typed shapes the input may take.	object[]	No

inputs.oneOf

Allowed values when the input is an enum.

Option 1

Field	Description	Type	Required
values	Explicit list of allowed enum values.	string[]	Yes

Option 2

Field	Description	Type	Required
ref	Name of a shared enum definition supplying the allowed values. One of: employment_status, employment_type, gender, marital_status.	string	Yes

inputs.rules

Validation rules applied to the input value.

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

Examples

inputs:
  - name: employee_id
    type: string
    required: true
    in: path
    description: Provider's employee identifier.

  - name: status
    type: enum
    required: false
    in: query
    description: Filter by employment status.
    oneOf:
      values: [active, inactive, terminated]

  - name: hire_date
    type: datetime_string
    required: false
    in: body
    description: ISO 8601 hire date.
    rules:
      format: date

  - name: skills
    type: string
    array: true
    arrayFormat: comma
    in: query
    description: Comma-separated skill filter.

  - name: destination
    in: body
    required: true
    description: Where to send the payload. The type field selects the variant.
    variants:
      - type: object
        description: Post to a webhook URL.
        properties:
          - name: type
            type: enum
            required: true
            oneOf:
              values: [webhook]
          - name: url
            type: string
            required: true
      - type: object
        description: Send to an email address.
        properties:
          - name: type
            type: enum
            required: true
            oneOf:
              values: [email]
          - name: address
            type: string
            required: true

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

Examples

responses:
  - statusCode: 200
    description: Employee record returned.
  - statusCode: 404
    description: No employee found with the provided ID.
  - statusCode: 409
    description: Conflicts with an existing record; check inputs.

result

Data returned to the caller, given as an expression or a map of output keys to expressions.

Examples

Expression

result: '${steps.cast.output.data}'

Object map

result:
  user: '${steps.fetch_user.output.data}'
  team: '${steps.fetch_team.output.data}'
  last_synced_at: '{{now()}}'

steps

See Step Functions for the full catalog and their parameters.

Ordered steps executed to carry out the action.

Single step

Field	Description	Type	Required
condition	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. 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

Step function executed by this step.

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

Iterator step

Field	Description	Type	Required
condition	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
iterator	Expression that produces the array this step loops over. The step function(s) run once per item until the array is exhausted, halting early if an item fails and ignoreError is not set.	string	Yes
onConditionError	How to behave when the condition expression errors. Allowed: true, false, break	enum	No
stepFunction	Step function run for each iterated item. Provide this or stepFunctions, not both.	object	No
stepFunctions	Step functions run in sequence for each iterated item. Provide this or stepFunction, not both.	object[]	No
stepId	Identifier for this step, used to reference its output.	string	Yes

steps.Iterator step.stepFunction

Step function run for each iterated item. Provide this or stepFunctions, not both.

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

steps.Iterator step.stepFunctions

Step functions run in sequence for each iterated item. Provide this or stepFunction, not both.

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

validationRules

Cross-field validation rules applied to the action inputs.

atLeastOneOf

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

requiredIf

Field	Description	Type	Required
condition	Condition under which the field is required.	object	Yes
errorMessage	Message shown when the rule is violated.	string	No
field	Input that becomes required when the condition holds.	string	Yes
rule	Requires an input when another field satisfies a condition.	string	Yes

validationRules.requiredIf.condition

Condition under which the field is required.

Field	Description	Type	Required
equals	Condition holds when the referenced field equals this value.	string	No
field	Name of the other input this condition inspects.	string	Yes
notEquals	Condition holds when the referenced field does not equal this value.	string	No
present	When true, the condition holds if the referenced field is present. When false, it holds if the field is absent.	boolean	No

mutuallyExclusive

Field	Description	Type	Required
errorMessage	Message shown when the rule is violated.	string	No
fields	Input names of which at most one may be provided.	string[]	Yes
rule	Allows at most one of the listed inputs to be provided.	string	Yes

Examples

atLeastOneOf

validationRules:
  - rule: atLeastOneOf
    fields: [email, employee_id]
    errorMessage: Provide either email or employee_id.

requiredIf

validationRules:
  - rule: requiredIf
    field: termination_date
    condition: { field: status, equals: terminated }
    errorMessage: termination_date is required when status is "terminated".

mutuallyExclusive

validationRules:
  - rule: mutuallyExclusive
    fields: [start_date, anchor_date]
    errorMessage: Use one of start_date or anchor_date, not both.

Related

Step functions

Full catalog of stepFunction implementations.

Expression language

JEXL syntax for condition, iterator, result, and step inputs.