Actions - Stackone

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
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

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

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
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`	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

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

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
offset
page

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

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

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
delta_token

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

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
Option 2

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

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
Object map

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

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
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
`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

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
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

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

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
requiredIf
mutuallyExclusive

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

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

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

Step functions

Full catalog of stepFunction implementations.

Expression language

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

​overview

​annotations

​authRequirements

​compositeIdentifiers

​cursor

​dataSync

​effects

​examples

​fieldConfigs

​inputs

​responses

​result

​steps

​validationRules

​Related

Step functions

Expression language

overview

annotations

authRequirements

compositeIdentifiers

cursor

dataSync

effects

examples

fieldConfigs

inputs

responses

result

steps

validationRules

Related