HTTP / REST APIs

The api.call connector makes HTTP requests to external APIs. It supports authentication, template expressions, and batch execution over tables.

Basic config

fetch-users:
  type: service
  op: api.call
  params:
    url: https://api.example.com/users
    method: GET
    headers:
      Accept: application/json
    auth:
      type: bearer
      token: "{{ secrets.API_TOKEN }}"
  outputs:
    response: { type: Table }

Template expressions

URL, headers, and body fields support {{ field }} templates. Values are interpolated from the input record at execution time.

params:
  url: "https://api.example.com/users/{{ user_id }}/profile"
  headers:
    Authorization: "Bearer {{ secrets.TOKEN }}"

Authentication

# API key
auth:
  type: api_key
  header: X-API-Key
  key: "{{ secrets.SERVICE_KEY }}"

# Bearer token
auth:
  type: bearer
  token: "{{ secrets.ACCESS_TOKEN }}"

# OAuth 2.0
auth:
  type: oauth
  client_id: "{{ secrets.OAUTH_CLIENT_ID }}"
  client_secret: "{{ secrets.OAUTH_CLIENT_SECRET }}"
  token_url: https://auth.example.com/oauth/token
  scopes: [read, write]

Input modes

When the input is a Record, api.call makes a single request. When the input is a Table, it makes one request per row. Templates resolve against each row.

enrich-contacts:
  type: service
  op: api.call
  params:
    url: "https://api.clearbit.com/v1/people/find?email={{ email }}"
    method: GET
    auth:
      type: api_key
      header: Authorization
      key: "Bearer {{ secrets.CLEARBIT_KEY }}"
  inputs:
    contacts: { type: Table, from: ref(read-csv.rows) }
  outputs:
    enriched: { type: Table }

Response parsing

Each response produces: status_code (number), body (parsed JSON), headers (object). Use extract to pull fields into flat output columns. Use artifact to download binary responses to disk.

params:
  extract:
    name: body.user.name
    plan: body.account.plan
  artifact:
    path: "artifacts/{{ report_id }}.pdf"
    content_type: application/pdf

Presets

Preset	Method	Description
rest.fetch	GET	Generic REST fetch. Sets JSON accept header.
llm.generate	POST	Calls Claude or GPT. Expects prompt, returns text.
tts.generate	POST	Text-to-speech. Returns audio artifact.
video.generate	POST	Video generation. Returns video artifact.

Config reference

Field	Required	Default	Description
url	Yes	—	Request URL. Supports {{ }} templates.
method	No	GET	HTTP method: GET, POST, PUT, PATCH, DELETE.
headers	No	{}	Request headers. Supports templates.
body	No	—	Request body (POST/PUT/PATCH). Supports templates.
auth	No	—	Authentication config.
extract	No	—	Dot-path mappings from response body to output fields.
artifact	No	—	Download binary responses to disk.
preset	No	—	Shorthand preset name.