Register Tool
curl --request POST \
--url https://api.truthlocks.com/v1/tools \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"display_name": "<string>",
"name": "<string>",
"scope_required": "<string>"
}
'const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({display_name: '<string>', name: '<string>', scope_required: '<string>'})
};
fetch('https://api.truthlocks.com/v1/tools', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.truthlocks.com/v1/tools"
payload = {
"display_name": "<string>",
"name": "<string>",
"scope_required": "<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"
payload := strings.NewReader("{\n \"display_name\": \"<string>\",\n \"name\": \"<string>\",\n \"scope_required\": \"<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))
}{
"tool_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"description": "<string>",
"schema": {},
"agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"created_at": "2023-11-07T05:31:56Z"
}{
"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
}Agent Sessions & Tools
Register Tool
Register a tool in the MAIP tool registry with scope requirements, risk classification, and rate limits
POST
/
v1
/
tools
Register Tool
curl --request POST \
--url https://api.truthlocks.com/v1/tools \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"display_name": "<string>",
"name": "<string>",
"scope_required": "<string>"
}
'const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({display_name: '<string>', name: '<string>', scope_required: '<string>'})
};
fetch('https://api.truthlocks.com/v1/tools', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.truthlocks.com/v1/tools"
payload = {
"display_name": "<string>",
"name": "<string>",
"scope_required": "<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"
payload := strings.NewReader("{\n \"display_name\": \"<string>\",\n \"name\": \"<string>\",\n \"scope_required\": \"<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))
}{
"tool_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"description": "<string>",
"schema": {},
"agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"created_at": "2023-11-07T05:31:56Z"
}{
"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
}Register Tool
POST /v1/tools
Registers a new tool in the tenant’s MAIP tool registry. Tools represent external capabilities (APIs, functions, services) that machine agents can invoke. Each tool is associated with a required scope, risk level, and optional approval gate.
The platform automatically elevates the risk level to "high" if the tool name or required scope contains dangerous action verbs (write, delete, send, execute, deploy, destroy, drop, truncate).
Tool names must be unique per tenant. Attempting to register a tool with a
name that already exists returns
409 Conflict.Authentication
RequiresX-API-Key header or Bearer JWT token. The workspace is derived from the authenticated credential; do not send X-Tenant-ID.
Response
string
UUID of the newly registered tool.
string
UUID of the owning tenant.
string
Machine-readable tool name.
string
Human-readable tool name.
string
Tool description.
string
Required scope for invocation.
string
Effective risk classification (may be auto-elevated).
boolean
Whether human approval is required.
integer
Per-agent rate limit.
string
Tool category.
string
Tool status. Always
"active" on creation.object
Tool metadata.
string
ISO 8601 creation timestamp.
string
ISO 8601 last-updated timestamp.
Example
curl -X POST https://api.truthlocks.com/v1/tools \
-H "X-API-Key: tl_live_..." \
-H "Content-Type: application/json" \
-d '{
"name": "search.web",
"display_name": "Web Search",
"description": "Performs web searches via SerpAPI and returns structured results",
"scope_required": "tool:search.web",
"risk_level": "low",
"rate_limit_per_minute": 30,
"category": "search",
"metadata": {
"endpoint_url": "https://serpapi.com/search",
"auth_type": "api_key",
"max_results": 10
}
}'
Risk Level Auto-Elevation
The platform scans tool names and scope requirements for dangerous action verbs. If detected, the risk level is automatically elevated:| Detected Verb | Auto-Elevation |
|---|---|
write, delete, send | Elevated to "high" |
execute, deploy, destroy | Elevated to "high" |
drop, truncate | Elevated to "high" |
"critical" risk level always require human approval regardless of the requires_approval setting.Authorizations
API key for machine-to-machine authentication
Body
application/json