Connector Reference

Connectors define the actions a step can perform. Actions use a connector/action naming convention. For AI tool use (function calling), see Tool Use.

http/request

Makes an HTTP request.

Params:

Output:

Example:

- name: create-item
  action: http/request
  params:
    method: POST
    url: https://api.example.com/items
    headers:
      Authorization: "Bearer {{ env.API_TOKEN }}"
      Content-Type: application/json
    body:
      name: "New Item"
      quantity: 5

ai/completion

Sends a prompt to an OpenAI-compatible chat completion API and returns the result. Requires a credential with an API key — see the Secrets Guide for setup.

Params:

Output:

Example — basic completion:

- name: summarize
  action: ai/completion
  credential: my-openai
  params:
    model: gpt-4o
    prompt: "Summarize this in 3 bullet points: {{ steps.fetch-data.output.body }}"

Example — with system prompt and structured output:

- name: extract-entities
  action: ai/completion
  credential: my-openai
  timeout: 60s
  params:
    model: gpt-4o
    system_prompt: "You are a data extraction assistant. Always respond with valid JSON."
    prompt: "Extract all person names and companies from: {{ steps.fetch-data.output.body }}"
    output_schema:
      type: object
      properties:
        people:
          type: array
          items:
            type: string
        companies:
          type: array
          items:
            type: string
      required:
        - people
        - companies
      additionalProperties: false

The structured output is available as steps.extract-entities.output.json.people and steps.extract-entities.output.json.companies in subsequent steps.

Example — custom base URL (Ollama):

- name: local-completion
  action: ai/completion
  params:
    model: llama3
    base_url: http://localhost:11434/v1
    prompt: "Explain this error: {{ steps.fetch-logs.output.body }}"

Example — AWS Bedrock:

- name: summarize
  action: ai/completion
  credential: aws-bedrock-creds
  params:
    provider: bedrock
    model: anthropic.claude-3-sonnet-20240229-v1:0
    region: us-east-1
    prompt: "Summarize: {{ steps.fetch.output.body }}"

When running on AWS infrastructure with an IAM role attached (IRSA, instance profile, etc.), the credential field can be omitted — the Bedrock provider uses the standard AWS credential chain automatically.

Authentication: The AI connector reads the credential’s api_key field (or token or key as fallbacks) and sends it as a Bearer token. If the credential includes an org_id field, it is sent as the OpenAI-Organization header. See the Secrets Guide for how to create an openai-type credential.

slack/send

Sends a message to a Slack channel via the chat.postMessage API. Requires a credential with a Slack Bot User OAuth Token.

Params:

Output:

Example:

- name: notify-team
  action: slack/send
  credential: slack-bot
  params:
    channel: "C01234ABCDE"
    text: "Deployment complete: {{ steps.deploy.output.body }}"

Authentication: The Slack connector reads the credential’s token field and sends it as a Bearer token. Create a credential of type bearer with a token field containing your Slack Bot User OAuth Token:

mantle secrets create --name slack-bot --type bearer --field token=xoxb-your-bot-token

slack/history

Reads recent messages from a Slack channel via the conversations.history API.

Params:

Output:

Example:

- name: read-channel
  action: slack/history
  credential: slack-bot
  params:
    channel: "C01234ABCDE"
    limit: 5

- name: summarize-messages
  action: ai/completion
  credential: my-openai
  params:
    model: gpt-4o
    prompt: "Summarize these Slack messages: {{ steps['read-channel'].output.messages }}"

postgres/query

Executes a parameterized SQL query against an external Postgres database. The connector opens a connection per step execution and closes it afterward. Supports both read queries (SELECT, WITH) and write statements (INSERT, UPDATE, DELETE).

Params:

Output (SELECT/WITH queries):

Output (INSERT/UPDATE/DELETE statements):

Example — read query:

- name: fetch-users
  action: postgres/query
  credential: my-database
  params:
    query: "SELECT id, email FROM users WHERE active = $1 LIMIT $2"
    args:
      - true
      - 100

Example — write statement:

- name: update-status
  action: postgres/query
  credential: my-database
  params:
    query: "UPDATE orders SET status = $1 WHERE id = $2"
    args:
      - "shipped"
      - "{{ steps['create-order'].output.json.order_id }}"

Authentication: The Postgres connector reads the database connection URL from the credential’s url field (or key as a fallback). Create a credential with the full Postgres connection string:

mantle secrets create --name my-database --type generic --field url=postgres://user:pass@host:5432/dbname?sslmode=require

email/send

Sends an email via SMTP. Supports plaintext and HTML content.

Params:

Output:

Example:

- name: send-report
  action: email/send
  credential: smtp-creds
  params:
    to:
      - "alice@example.com"
      - "bob@example.com"
    from: "reports@example.com"
    subject: "Daily Report — {{ steps.generate.output.json.date }}"
    body: "{{ steps.generate.output.json.html_report }}"
    html: true

Authentication: The email connector reads username, password, host, and port from the credential. If host or port are not in the credential, they fall back to the smtp_host and smtp_port params. Create a basic credential with SMTP fields:

mantle secrets create --name smtp-creds --type basic \
  --field username=apikey \
  --field password=SG.your-sendgrid-key \
  --field host=smtp.sendgrid.net \
  --field port=587

email/receive

Reads messages from an email mailbox. Supports filtering by folder and read status.

Params:

Output:

Authentication: Credentials are provided via the step-level credential field. The email connector reads username, password, host, and port from the credential (IMAP-compatible).

Example:

- name: read-inbox
  action: email/receive
  credential: company-inbox
  params:
    folder: INBOX
    filter: unseen
    limit: 20
    mark_seen: true

email/move

Moves an email message to a different folder.

Params:

Output:

Authentication: Credentials are provided via the step-level credential field.

Note: Gmail’s “archive” action is implemented as a move to [Gmail]/All Mail.

Example:

- name: archive-message
  action: email/move
  credential: company-inbox
  params:
    uid: "{{ trigger.uid }}"
    source_folder: INBOX
    target_folder: Archive

email/delete

Deletes an email message.

Params:

Output:

Authentication: Credentials are provided via the step-level credential field.

Example:

- name: delete-spam
  action: email/delete
  credential: company-inbox
  params:
    uid: "{{ trigger.uid }}"
    folder: INBOX

email/flag

Adds or removes flags (labels) on an email message.

Params:

Standard IMAP Flags:

Custom Keywords: Most email providers support custom flag names beyond the standard set. These are often used as tags or labels (e.g., important, urgent, client-xyz).

Output:

Authentication: Credentials are provided via the step-level credential field.

Example:

- name: flag-important
  action: email/flag
  credential: company-inbox
  params:
    uid: "{{ trigger.uid }}"
    flags: ["flagged", "important"]
    action: add

s3/put

Uploads an object to an S3-compatible storage bucket.

Params:

Output:

Example:

- name: upload-report
  action: s3/put
  credential: aws-s3
  params:
    bucket: "my-reports"
    key: "reports/{{ steps.generate.output.json.date }}.json"
    content: "{{ steps.generate.output.json.report }}"
    content_type: "application/json"

s3/get

Downloads an object from an S3-compatible storage bucket.

Params:

Output:

Example:

- name: download-config
  action: s3/get
  credential: aws-s3
  params:
    bucket: "my-configs"
    key: "app/config.json"

s3/list

Lists objects in an S3-compatible storage bucket, with optional prefix filtering.

Params:

Output:

Example:

- name: list-reports
  action: s3/list
  credential: aws-s3
  params:
    bucket: "my-reports"
    prefix: "reports/2026/"

S3 Authentication

All S3 connectors (s3/put, s3/get, s3/list) read the following fields from the credential:

Create a credential for S3:

mantle secrets create --name aws-s3 --type generic \
  --field access_key=AKIA... \
  --field secret_key=wJalr... \
  --field region=us-west-2

For S3-compatible services, add an endpoint field:

mantle secrets create --name minio --type generic \
  --field access_key=minioadmin \
  --field secret_key=minioadmin \
  --field endpoint=http://localhost:9000

docker/run

Runs a Docker container to completion and captures its output. The container is created, started, waited on, and optionally removed. Non-zero exit codes do not constitute a step failure — use if conditions to branch on exit code.

Params:

Output:

Authentication: The Docker connector uses a docker credential type for daemon access. All fields are optional — an empty credential connects to the local Docker socket. For private images, use registry_credential with a basic credential type. Note that registry_credential is a step-level field (alongside credential), not a param.

Security: Containers run with all Linux capabilities dropped (CAP_DROP ALL), no-new-privileges, and a PID limit. Only bridge and none network modes are permitted.

Example:

- name: process-data
  action: docker/run
  credential: my-docker
  registry_credential: my-registry
  timeout: "2m"
  params:
    image: myorg/processor:latest
    cmd: ["process", "--format", "json"]
    stdin: "{{ steps['fetch-data'].output.body }}"
    memory: "512m"
    cpus: 1.0

browser/run

Runs browser automation scripts (JavaScript, TypeScript, or Python) using Playwright. Scripts run in a containerized browser environment and can interact with web pages, perform DOM queries, take screenshots, and generate structured output.

Params:

Output:

Container Images:

• JavaScript/TypeScript: mcr.microsoft.com/playwright:v1.52.0-noble
• Python: mcr.microsoft.com/playwright/python:v1.52.0-noble

Artifacts: Scripts can write files to /mantle/artifacts/ directory for screenshots, PDFs, HAR files, and other outputs. Declare artifacts in the step to register them with the execution.

Credentials: Secrets are injected as environment variables via the env param. Access them in scripts using process.env.VAR_NAME (JS/TS) or os.environ['VAR_NAME'] (Python).

Security: Containers run with all Linux capabilities dropped (CAP_DROP ALL), no-new-privileges, and a PID limit. Same security hardening as docker/run.

Example — JavaScript with login and screenshot:

- name: scrape-portal
  action: browser/run
  timeout: "2m"
  params:
    language: javascript
    output_format: json
    env:
      USERNAME: "{{ inputs.username }}"
      PASSWORD: "{{ inputs.password }}"
    script: |
      const page = await browser.newPage();
      await page.goto('https://portal.example.com/login');
      await page.fill('#username', process.env.USERNAME);
      await page.fill('#password', process.env.PASSWORD);
      await page.click('#login-button');
      await page.waitForSelector('.dashboard');

      const data = await page.evaluate(() => {
        const rows = document.querySelectorAll('.data-table tr');
        return Array.from(rows).map(row => ({
          name: row.querySelector('.name')?.textContent,
          value: row.querySelector('.value')?.textContent,
        }));
      });

      await page.screenshot({ path: '/mantle/artifacts/dashboard.png' });
      console.log(JSON.stringify({ records: data, count: data.length }));
  artifacts:
    - path: dashboard.png
      name: dashboard-screenshot

Example — TypeScript with form submission:

- name: submit-form
  action: browser/run
  timeout: "2m"
  params:
    language: typescript
    output_format: json
    script: |
      const page = await browser.newPage();
      await page.goto('https://portal.example.com/form');
      await page.fill('#email', 'user@example.com');
      await page.fill('#message', 'Automated submission');
      await page.click('#submit-button');
      await page.waitForSelector('.success-message');

      const confirmationId = await page.textContent('.confirmation-id');
      console.log(JSON.stringify({ submitted: true, confirmation_id: confirmationId }));

Example — Python with PDF generation:

- name: generate-pdf
  action: browser/run
  timeout: "2m"
  params:
    language: python
    output_format: json
    script: |
      import os
      import json

      page.goto('https://example.com/report')
      page.pdf(path='/mantle/artifacts/report.pdf')

      file_size = os.path.getsize('/mantle/artifacts/report.pdf')
      print(json.dumps({'generated': True, 'size_bytes': file_size}))
  artifacts:
    - path: report.pdf
      name: generated-report

Playwright API Reference:

Within browser/run scripts, use the standard Playwright API:

• Page navigation: page.goto(url), page.goBack(), page.goForward(), page.reload()
• Interactions: page.fill(selector, text), page.click(selector), page.selectOption(selector, value), page.press(key)
• Waiting: page.waitForSelector(selector), page.waitForNavigation(), page.waitForFunction(fn)
• DOM queries: page.textContent(selector), page.getAttribute(selector, name), page.evaluate(fn)
• Screenshots/exports: page.screenshot(options), page.pdf(options), page.recordHar(path)