VerityVerity
API Reference

Invoke agent tool

Invokes one high-level Verity tool through the controlled agent access layer. Use GET /agent/tools first to fetch the exact input schema for each tool.

Use response_format: "concise" for normal agent reasoning and response_format: "detailed" when the agent needs source metadata, code lists, or audit evidence. Policy search uses search_query, not a generic query field.

Write tools such as acknowledge_policy_change return 202 with approval_status: "required" unless the caller includes X-Verity-Approval: reviewed after authorized human or operator review. Read the response result_window fields before assuming a list is complete.

POST
/agent/tools/{tool}

Authorization

bearerAuth
AuthorizationBearer <token>

API keys are prefixed with vrt_live_ for production or vrt_test_ for testing. Example: vrt_live_abc123xyz

In: header

Path Parameters

tool*string

Agent tool ID

Value in"check_coverage" | "validate_claim" | "find_policies" | "check_updates" | "acknowledge_policy_change"

Header Parameters

X-Verity-Agent?string

Optional agent name recorded in the invocation ledger.

Lengthlength <= 120
X-Verity-Approval?string

Set to reviewed only after authorized review for tools that return approval_required=true.

Value in"reviewed"

Request Body

application/json

code*string
Match^[A-Z0-9.-]{2,20}$
state?string
Match^[A-Z]{2}$
response_format?string

Use concise for normal agent reasoning; use detailed only when source metadata, IDs, or audit evidence are needed.

Default"concise"
Value in"concise" | "detailed"
[key: string]?never

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://verity.backworkai.com/api/v1/agent/tools/check_coverage" \  -H "Content-Type: application/json" \  -d '{    "code": "string"  }'
{
  "success": true,
  "data": {},
  "meta": {
    "request_id": "string",
    "timestamp": "2019-08-24T14:15:22Z",
    "tool": "string",
    "actor_type": "api_client",
    "actor_name": "string",
    "approval_status": "not_required"
  }
}
{
  "success": true,
  "data": {},
  "meta": {
    "request_id": "string",
    "timestamp": "2019-08-24T14:15:22Z",
    "tool": "string",
    "actor_type": "api_client",
    "actor_name": "string",
    "approval_status": "not_required"
  }
}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": {
      "q": [
        "Search query is required"
      ]
    },
    "docUrl": "https://docs.verity.io/errors#validation-error"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid query parameters",
    "hint": "Check the 'code' parameter format",
    "details": {}
  },
  "meta": {
    "request_id": "req_abc123"
  }
}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid query parameters",
    "hint": "Check the 'code' parameter format",
    "details": {}
  },
  "meta": {
    "request_id": "req_abc123"
  }
}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid query parameters",
    "hint": "Check the 'code' parameter format",
    "details": {}
  },
  "meta": {
    "request_id": "req_abc123"
  }
}
{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded",
    "hint": "Upgrade to pay-as-you-go for higher limits",
    "docUrl": "https://docs.verity.io/errors#rate-limit-exceeded"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Last updated on

List agent tools

Previous Page

Research prior authorization requirements

Next Page