Skip to main content
POST
/
v1
/
tools
/
{toolId}
/
invoke
Invoke Tool
curl --request POST \
  --url https://api.truthlocks.com/v1/tools/{toolId}/invoke \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "session_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "arguments": {}
}
'
{
  "result": {},
  "receipt_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "execution_ms": 123
}

​
Invoke Tool

POST /v1/tools/{toolName}/invoke Requests invocation of a registered tool on behalf of a machine agent. The platform performs a multi-layer access control check before granting access:
  1. Agent status — agent must be "active"
  2. Scope check — agent must hold the tool’s required scope
  3. Rate limit — agent must not exceed the tool’s per-minute rate limit
  4. Approval gate — if the tool requires approval, invocation is deferred to the approval queue
If all checks pass, the invocation is recorded with a cryptographic receipt linking the agent, tool, and session for full audit traceability.
This endpoint performs the access control decision and generates an audit receipt. It does not proxy the actual tool execution. Your application is responsible for calling the tool’s underlying endpoint after receiving an "allowed" response.

​
Authentication

Requires X-API-Key header or Bearer JWT token. Tenant-scoped via X-Tenant-ID.

​
Path Parameters

​
toolName
string
required
The registered tool name (e.g., "search.web", "crm-contact-lookup").

​
Request Body

​
agent_id
string
required
The MAIP agent identifier requesting the tool invocation (e.g., maip:t1234567:01HYX3KPZQ7RJGBN0WFMV8SDEH).
​
session_id
string
The active session ID, if the invocation is scoped to a session. Optional but recommended for full audit trail linkage.

​
Response

​
allowed
boolean
Whether the invocation was authorized. true if all access control checks passed.
​
status
string
Invocation status. One of: "allowed", "denied", "pending_approval".
​
reason
string
Human-readable explanation when the invocation is denied or pending. Not present when allowed.
​
receipt_id
string
Unique receipt identifier for the invocation, linking to the audit trail. Only present when status is "allowed".
​
requires_approval
boolean
true when the tool requires human approval and the invocation is queued. Only present when status is "pending_approval".
​
approval_id
string
Identifier for the pending approval request. Use this to check approval status or to approve/reject via the approvals API. Only present when status is "pending_approval".

​
Example: Allowed Invocation

curl -X POST https://api.truthlocks.com/v1/tools/search.web/invoke \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "maip:t1234567:01HYX3KPZQ7RJGBN0WFMV8SDEH",
    "session_id": "maip-sess:a1b2c3d4:9f8e7d6c5b4a3210"
  }'

​
Access Control Flow

POST /v1/tools/{name}/invoke
  |
  +-- Is agent active?
  |     No  --> { allowed: false, status: "denied", reason: "agent is not active" }
  |
  +-- Does agent have required scope?
  |     No  --> { allowed: false, status: "denied", reason: "agent lacks required scope: ..." }
  |
  +-- Is rate limit exceeded?
  |     Yes --> { allowed: false, status: "denied", reason: "rate limit exceeded" }
  |
  +-- Does tool require approval?
  |     Yes --> { allowed: false, status: "pending_approval", requires_approval: true }
  |
  +-- Create receipt + record invocation
        --> { allowed: true, status: "allowed", receipt_id: "..." }

​
Integration Pattern

After receiving an "allowed" response, execute the tool and optionally record the outcome: 
# 1. Request invocation authorization
RESPONSE=$(curl -s -X POST https://api.truthlocks.com/v1/tools/search.web/invoke \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "maip:t1234567:01HYX3KPZQ7RJGBN0WFMV8SDEH"}')

ALLOWED=$(echo "$RESPONSE" | jq -r '.allowed')
RECEIPT_ID=$(echo "$RESPONSE" | jq -r '.receipt_id')

# 2. Execute the tool if authorized
if [ "$ALLOWED" = "true" ]; then
  RESULT=$(curl -s "https://serpapi.com/search?q=example&api_key=...")
  echo "Tool executed. Receipt: $RECEIPT_ID"
fi

Authorizations

​
X-API-Key
string
header
required

API key for machine-to-machine authentication

Path Parameters

​
toolId
string<uuid>
required

Tool identifier

Body

application/json
​
session_id
string<uuid>
required

Active session to invoke under

​
arguments
object
required

Tool input arguments matching the tool schema

Response

Tool invocation result

​
result
object
​
receipt_id
string<uuid>
​
execution_ms
integer