# Action kinds

_Every saved action kind, its configuration and runtime input, its result, and where the action can run._

Canonical: https://snoze.dev/help/actions/

An Action is a named, enabled workspace item with one typed configuration. It
can run from the Actions surface, a command, a page or dashboard Button, a
database Button field, or an Automation Action node. Each attempt creates an
Action run with `started`, `completed`, or `failed` status and a stored result
or error.

Runtime input is separate from saved configuration. It lets one Action operate
on the record or values supplied by the button or automation that invoked it.
The caller's permissions still apply.

<!-- GENERATED:action-kinds:START -->

Canonical contract values:

- `refresh_data_source`
- `create_database_record`
- `update_database_record`
- `run_actions`
- `http_request`
- `connector_operation`
- `provider_operation`
- `code`

<!-- GENERATED:action-kinds:END -->

## Kinds

### Refresh data source `refresh_data_source`

Refreshes one configured data source. The saved config requires
`dataSourceId`; it has no kind-specific runtime input. The result exposes
`dataSourceId` and the refresh `runId`, which a later automation step can store
or inspect. It starts the source's normal refresh path rather than changing the
managed database directly.

### Create database record `create_database_record`

Creates a row in a required `databaseId` and writes the configured `fields`
map. The values are saved templates, not automation expressions in this Action
kind. The result is `{ recordId }`, so a later step can address the new record.
Database validation, writable-field rules, and caller permissions still apply.

### Update database record `update_database_record`

Updates one database row. Configure `databaseId`, optional fixed `recordId`, and
field values. At run time, `input.recordId` takes precedence over the fixed ID,
and `input.fields` is merged over configured fields. The run fails if neither
source supplies a record ID. It returns `{ recordId }` after the update.

### Run actions `run_actions`

Runs an ordered program of steps. A program can create or update records, send
a notification, run another Action, or run an AI prompt. New typed steps have
stable IDs and can read literal values, immutable run input, the trigger
payload, or a previous step result. Older step entries containing only an
`actionId`, optional input, and `continueOnError` are normalised as run-action
steps.

The optional trigger can listen for a workspace event, an interval or cron
schedule, or a form submission. An AI step stores `text`, `chatId`,
`toolCalls`, and `blocked`; if it pauses for approval, the program remains
started rather than reporting success. The program result contains the
step-owned results. Recursion and nested execution are guarded by the runner.

### HTTP request `http_request`

Calls a guarded URL with GET, POST, PUT, PATCH, or DELETE. Configure URL,
headers, query, optional string body, optional Connection, timeout, and maximum
response bytes. Defaults are GET, a 15-second timeout, and the product response
limit. A connection can add secret headers and query values without saving
credentials in the Action.

The result contains status, `ok`, content type, byte count, truncation flag,
final URL, and response body. Secrets are redacted, the body is capped, guarded
egress rules apply, and an invocation key is sent as `Idempotency-Key` when the
Action did not set one. It does not parse the response into a declared token
shape.

### Connector operation `connector_operation`

Runs a legacy typed connector operation. Configure connector, operation,
Connection ID, and operation settings; runtime input supplies the operation's
input fields. The raw parsed connector response becomes the Action result.
Required settings and inputs come from the connector catalog, and the action is
available only while the connection and operation remain available. See
[Connector and provider operations](https://snoze.dev/help/integrations/).

### Provider operation `provider_operation`

Runs an operation from the integration-provider registry. Configure a
Connection, operation, optional external resource, base input, and confirmation
flag. Runtime input is merged over configured input. The result includes
`providerOperationRunId` plus the provider operation's output; declared output
shapes drive named downstream tokens. Mutating or confirmation-required
operations keep those safety requirements.

### Code `code`

Executes saved JavaScript, TypeScript, or Python in the configured code
execution service. Runtime input is supplied to the execution, and
`timeoutMs` defaults to 10 seconds. The execution service's structured result
becomes the Action result. This kind depends on that service being configured;
it is not page Code block rendering and it does not bypass permissions or the
execution sandbox.

## Buttons and automation nodes

A Button block stores an Action ID; a Button database field stores button
settings on the field and resolves the current record as context. An Automation
Action node stores `actionId` plus an expression map for runtime input. All
three invoke the saved Action rather than copying its configuration, so edits
to the Action apply everywhere it is reused.

An Action is best for a reusable operation or ordered program. Use an
[Automation](https://snoze.dev/help/automations/) when the work needs the graph trigger catalog,
branches, loops, durable delays, approvals, or multiple graph paths.