HTTP Actions

HTTP actions call external REST API endpoints. Use them to integrate with any system that has an API — CRMs, ERPs, payment processors, notification services.

Registration

bash

curl -X POST http://localhost:3009/actions \
  -H "X-Org-Id: acme-corp" \
  -H "Content-Type: application/json" \
  -d '{
    "action_name": "create_salesforce_lead",
    "kind": "http",
    "description": "Create a new lead in Salesforce",
    "url": "https://api.salesforce.com/services/data/v58.0/sobjects/Lead",
    "http_method": "POST",
    "headers": {
      "Authorization": "Bearer orgconfig:api:salesforce_token",
      "Content-Type": "application/json"
    },
    "passthrough": true,
    "outputKey": "new_lead"
  }'

Properties

Property	Type	Required	Description
`action_name`	string	Yes	Unique name for this action
`kind`	`"http"`	Yes
`url`	string	Yes	Endpoint URL. Supports `{{ }}` template syntax for path parameters
`http_method`	string	Yes	`"GET"`, `"POST"`, `"PUT"`, `"PATCH"`, `"DELETE"`
`headers`	object	No	Request headers. Values support `orgconfig:` prefix for secrets
`content_type`	string	No	Request content type (default: `"application/json"`)
`passthrough`	boolean	No	If true, the full response body is available in context
`outputKey`	string	No	Context key for the response

URL Templates

Use {{ }} syntax for dynamic URL segments:

json

{
  "action_name": "get_order",
  "kind": "http",
  "url": "https://api.store.com/orders/{{order_id}}",
  "http_method": "GET"
}

When used in a workflow step, the order_id comes from the step properties:

json

{ "type": "get_order", "properties": { "order_id": "@input.order_id" } }

Secret References

Use orgconfig: to reference encrypted secrets stored in org config:

json

{
  "headers": {
    "Authorization": "Bearer orgconfig:api:stripe_key",
    "X-Custom-Token": "orgconfig:api:vendor_token"
  }
}

The execution engine resolves orgconfig: references at runtime. The actual secret value never appears in the workflow definition or reasoning traces.

Usage in a Workflow

json

{
  "type": "create_salesforce_lead",
  "properties": {
    "FirstName": "@input.first_name",
    "LastName": "@input.last_name",
    "Email": "@input.email",
    "Company": "@input.company"
  },
  "outputKey": "new_lead"
}

With passthrough: true, the full API response is available at @new_lead for subsequent steps.

Usage as an Agent Tool

List the action name in the agent's tools array:

json

{
  "mode": "react",
  "objective": "Look up customer and update their record",
  "tools": [{ "type": "action", "name": "create_salesforce_lead" }, { "type": "action", "name": "get_order" }]
}

The agent can call create_salesforce_lead with the required parameters. The action schema is included in the agent's prompt so it knows what parameters are needed.

Error Handling

If the HTTP request fails (non-2xx status, timeout, connection error), the action returns an error result. In a workflow step, this fails the run. In a ReAct agent, the error is returned as an observation and the agent can decide how to proceed.

HTTP timeouts default to 30 seconds. For long-running API calls, consider using an async pattern with polling.

→ Next: LLM Actions