Invoke an agent tool

Endpoint: POST /api/v1/agent/tools/{tool}

Availability: Live in production.

Authentication: API key in Authorization: Bearer <key> with the read scope.

Invokes one high-level Backwork tool through the controlled agent access layer. Use GET /agent/tools first to fetch the exact input schema for each tool. Read tools accept read, admin, agent:tool:*, or the tool-specific agent:tool:<tool_id> scope; write tools require write, admin, agent:tool:*, or the tool-specific scope. A key that holds any agent:tool: scope is limited to its agent scopes. acknowledge_policy_change also requires a plan with compliance dashboard access. Requests containing patient-identifying field names are rejected with PHI_NOT_ALLOWED.

Parameters

• tool (path, required): Agent tool ID
• X-Backwork-Agent (header): Optional agent name recorded in the invocation ledger. Must not contain PHI.
• X-Backwork-Approval (header): Set to reviewed only after authorized review for tools that return approval_required=true.

Example request

curl -X POST "https://backworkhealth.com/api/v1/agent/tools/check_coverage" \
  -H "Authorization: Bearer $BACKWORK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "string"
}'

Example response (200)

{
  "success": true,
  "data": {},
  "meta": {
    "request_id": "string",
    "timestamp": "2026-01-15T10:30:00Z",
    "tool": "check_coverage",
    "actor_type": "api_client",
    "actor_name": "string",
    "approval_status": "not_required"
  }
}

curl -X POST "https://example.com/agent/tools/check_coverage" \  -H "Content-Type: application/json" \  -d '{    "code": "string"  }'

{  "success": true,  "data": {    "property1": null,    "property2": null  },  "meta": {    "request_id": "string",    "timestamp": "2019-08-24T14:15:22Z",    "tool": "check_coverage",    "actor_type": "api_client",    "actor_name": "string",    "approval_status": "not_required"  }}

Last updated on