Connect a step to your API

Bind a step's tool-id to a real HTTP endpoint with a connector, map inputs, and control shadowing of irreversible tools.

A connector binds a step's abstract tool-id to a real HTTP API. Until a tool-id has a connector, the step runs against the shadow (dry-run) implementation. This guide covers creating, mapping, testing, and safely un-shadowing a connector.

Create or update a connector

Connectors are keyed by tool_id and created with PUT /connectors/{tool_id} — the call is idempotent, so the same request creates or updates.

curl -s -X PUT "$API/connectors/screening" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_url": "https://screening.vendor.com",
    "method": "POST",
    "path": "/v1/screen",
    "auth_type": "bearer",
    "auth_token": "<vendor-api-key>",
    "reversible": false
  }'

Config fields

Field	Meaning
`base_url`	Base URL of the API this tool-id calls. Required.
`method`	HTTP method: `GET` \| `POST` \| `PUT` \| `PATCH` \| `DELETE`. Default `GET`.
`path`	Path appended to `base_url`. No placeholders — values come from the maps below.
`auth_type`	`none` \| `bearer` \| header-based. Pairs with `auth_token` / `auth_header`.
`query_map`	Maps run-state keys → query-string params.
`body_map`	Maps run-state keys → JSON body fields.
`signal_rule`	Rule that turns the response into a governance signal (e.g. a hit/no-hit flag).
`reversible`	`false` keeps the tool shadowed; `true` opts into live, irreversible calls.

Map run state into the request

The path holds no placeholders. Instead, map keys from the run's state into the request with query_map (query string) and body_map (JSON body):

curl -s -X PUT "$API/connectors/screening" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_url": "https://screening.vendor.com",
    "method": "POST",
    "path": "/v1/screen",
    "body_map": { "subject_id": "member_id", "code": "procedure_code" }
  }'

Here the run-state key member_id is sent as the request field subject_id.

Test before you wire it into a run

Validate a config against the live endpoint without starting a run:

curl -s -X POST "$API/connectors/screening/test" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "base_url": "https://screening.vendor.com", "method": "POST", "path": "/v1/screen" }'

Shadowing irreversible tools

Irreversible tools stay shadowed by default

Any tool that mutates the outside world (submits a claim, sends a payment, files a report) is shadowed until you set reversible: false deliberately off — i.e. you must opt in to live calls. While shadowed, the step executes a dry-run: the run proceeds and records what would have happened, but no real call is made. Un-shadow only once the connector is tested and the governance gates around it are in place.

Manage connectors

# list connectors for your company
curl -s "$API/connectors/" -H "Authorization: Bearer $TOKEN"

# delete one
curl -s -X DELETE "$API/connectors/screening" -H "Authorization: Bearer $TOKEN"

See the Connectors reference for the full schema and every field.