HTTP Actions

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

Registration

bash

curl -X POST https://your-hyphen.example.com/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
  }'

Properties

Property	Type	Required	Description
`action_name`	string	Yes	Unique name for this action
`kind`	`"http"`	Yes
`url`	string	Yes	Endpoint URL. Use an `@path` reference when the complete URL comes from workflow context
`http_method`	string	Yes	`"GET"`, `"POST"`, `"PUT"`, `"PATCH"`, `"DELETE"`
`headers`	object	No	Request headers. Values support `orgconfig:` prefix for secrets
`properties.keys`	string[]	No	Workflow-step request body field names
`properties.values`	array	No	Workflow-step values paired with `keys`. Entries may be literals or `@path` references
`query`	object	No	Query parameters used when the action is called as an agent tool
`content_type`	string	No	Request content type (default: `"application/json"`)
`passthrough`	boolean	No	If true, the full response body is available in context

Dynamic URLs

For a workflow action whose complete URL changes at runtime, point url at a context value:

json

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

Override the full URL on the workflow step when needed:

json

{
  "type": "get_order",
  "properties": {
    "url": "@input.order_url"
  }
}

Keep URL construction in your application when path segments come from untrusted input. Hyphen validates outbound destinations before making the request.

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 engine resolves orgconfig: references at runtime without writing the resolved value back into the workflow definition. Recorded action data also passes through sensitive-field redaction. Keep credentials in organization configuration rather than objectives, prompts, or ordinary input fields.

Usage in a Workflow

json

{
  "type": "create_salesforce_lead",
  "properties": {
    "keys": ["FirstName", "LastName", "Email", "Company"],
    "values": ["@input.first_name", "@input.last_name", "@input.email", "@input.company"]
  }
}

The step's keys and values build the request body from workflow context.

With passthrough: true, fields from an object response are merged into workflow context for subsequent steps. Use stable, namespaced response fields when the downstream workflow depends on them.

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 a JSON object. For a non-GET action, that object becomes the request body. For GET and HEAD actions, it becomes query parameters. The action description tells the agent what fields the endpoint expects.

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