Actions and the catalog

An action block declares a provider API operation: HTTP transport, input and output JSON schemas, and required OAuth scopes. It pairs with a connection for credentials at runtime.

Call actions from type: integration nodes to validate requests and responses against their schemas. Install actions with swirls add, generate them from an API specification, or write them by hand.

The integration catalog

The catalog at swirls.ai/catalog lists installable provider actions. Check it for current coverage. Action availability and managed OAuth support are separate: generated actions can also use a self-managed connection.

Install actions with one command:

swirls add slack                # every curated Slack action
swirls add linear create_issue  # one Linear action
swirls add microsoft send_mail list_calendar_events

swirls add writes action blocks to swirls/integrations/<provider>/ and records source, version, and checksum in swirls.lock.json. Override the registry with --registry or SWIRLS_REGISTRY_URL.

Action blocks

Installed actions are ordinary .swirls blocks. You can read them, review them in a PR, and write your own by hand.

action slack_post_message {
  label: "Post message"
  provider: slack
  method: POST
  path: "/chat.postMessage"
  encoding: form
  scopes: ["chat:write"]
  input: @json { { "type": "object", "required": ["channel", "text"], "properties": { "channel": { "type": "string" }, "text": { "type": "string" } } } }
  output: @json { { "type": "object", "required": ["ok"], "properties": { "ok": { "type": "boolean" } } } }
}

raw encoding sends the content input verbatim as the request body, with an optional contentType input setting the MIME type. The Microsoft Graph file-upload actions use it.

GraphQL actions carry a pre-authored document instead of input and output schemas; the LSP types them from the schema.graphql sidecar that swirls add writes beside the actions.

Using an action in a workflow

A type: integration node names a connection and an action. Deploy inlines the transport and schemas from the action block, so params: and the node output are checked against them.

connection team_slack {
  label: "Team Slack"
  provider: slack
}

Inside a workflow:

node post_slack {
  type: integration
  label: "Post to Slack"
  connection: team_slack
  action: slack_post_message
  params: @ts {
    return {
      channel: context.nodes.root.output.channel,
      text: context.nodes.root.output.text,
    }
  }
}

For a managed connection, the platform resolves the bound account's provider credentials and proxies the call. For a self-managed connection, it resolves the declared auth profile from the project vault. Full node reference: integration nodes.

Generate actions from an API specification

swirls add also accepts a URL. Point it at an OpenAPI or GraphQL spec and it generates the same typed action artifacts the catalog ships:

swirls add https://api.linear.app/graphql --only viewer
swirls add https://petstore.example.com/openapi.json

URL imports scaffold a connection file once if one is missing. Pair the generated actions with a self-managed connection (base_url plus auth) and the runtime calls your API with credentials from the project vault.

Request a provider

To request managed OAuth support, email [email protected] with the provider and required scopes or operations. Unknown managed providers can produce a local validation warning, but deployment rejects unsupported managed connections. Use a self-managed connection with base_url and auth when you hold the API credentials.

Common mistakes

• Setting method: or path: on a node that uses action:. The action block owns the transport.
• Editing installed action files in place and re-running swirls add. The checksum in swirls.lock.json tracks the installed version; copy the block out under a new name if you want to customize it.
• Combining document with input/output. GraphQL actions type through the schema.graphql sidecar, not inline schemas.
• Calling the provider with fetch from a code node. Code nodes never see connection credentials; use an integration node.

Further reading

• Connection blocks: the credential slots actions pair with
• Integration nodes: full node reference
• Channels: connections behind chat platforms