Invoke Tool

curl --request POST \
  --url https://api.truthlocks.com/v1/tools/{toolName}/invoke \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "agent_id": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({agent_id: '<string>'})
};

fetch('https://api.truthlocks.com/v1/tools/{toolName}/invoke', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.truthlocks.com/v1/tools/{toolName}/invoke"

payload = { "agent_id": "<string>" }
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.truthlocks.com/v1/tools/{toolName}/invoke"

	payload := strings.NewReader("{\n  \"agent_id\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "result": {},
  "receipt_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "execution_ms": 123
}

{
  "code": "AUTH_REQUIRED",
  "message": "Authentication required",
  "http_status": 401
}

{
  "code": "AUTH_REQUIRED",
  "message": "Authentication required",
  "http_status": 401
}

{
  "code": "AUTH_REQUIRED",
  "message": "Authentication required",
  "http_status": 401
}

{
  "code": "AUTH_REQUIRED",
  "message": "Authentication required",
  "http_status": 401
}

POST

tools

{toolName}

invoke

Invoke Tool

curl --request POST \
  --url https://api.truthlocks.com/v1/tools/{toolName}/invoke \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "agent_id": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({agent_id: '<string>'})
};

fetch('https://api.truthlocks.com/v1/tools/{toolName}/invoke', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.truthlocks.com/v1/tools/{toolName}/invoke"

payload = { "agent_id": "<string>" }
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.truthlocks.com/v1/tools/{toolName}/invoke"

	payload := strings.NewReader("{\n  \"agent_id\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "result": {},
  "receipt_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "execution_ms": 123
}

{
  "code": "AUTH_REQUIRED",
  "message": "Authentication required",
  "http_status": 401
}

{
  "code": "AUTH_REQUIRED",
  "message": "Authentication required",
  "http_status": 401
}

{
  "code": "AUTH_REQUIRED",
  "message": "Authentication required",
  "http_status": 401
}

{
  "code": "AUTH_REQUIRED",
  "message": "Authentication required",
  "http_status": 401
}

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:

Agent status — agent must be "active"
Scope check — agent must hold the tool’s required scope
Rate limit — agent must not exceed the tool’s per-minute rate limit
Approval gate — if the tool requires approval, the response is pending_approval; the current handler does not create an approval request

If all checks pass, the invocation is recorded. Current tool receipts use a system marker rather than a cryptographic signature. They are audit records, not independently verifiable signed proofs.

This endpoint performs the access control decision and records the decision. 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. The workspace is derived from the authenticated credential; do not send X-Tenant-ID.

Response

boolean

Whether the invocation was authorized. true if all access control checks passed.

string

Invocation status. One of: "allowed", "denied", "pending_approval".

string

Human-readable explanation when the invocation is denied or pending. Not present when allowed.

string

Unique receipt identifier for the invocation, linking to the audit trail. Only present when status is "allowed".

boolean

true when the tool requires human approval. The invocation is not automatically queued for approval. 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 only if explicitly 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

toolName

string

required

Registered tool name.

Body

application/json

agent_id

string

required

session_id

string<uuid>

Active session to invoke under

Response

Tool invocation result

result

object

receipt_id

string<uuid>

execution_ms

integer

​Invoke Tool

​Authentication

​Response

​Example: Allowed Invocation

​Access Control Flow

​Integration Pattern

Authorizations

Path Parameters

Body

Response

Invoke Tool

Authentication

Response

Example: Allowed Invocation

Access Control Flow

Integration Pattern