Tools

​

Common Patterns

​

GET /api/tools

response = requests.get(f"{BASE_URL}/api/tools", headers=headers)

const res = await fetch(`${BASE_URL}/api/tools`, { headers });

curl '{BASE_URL}/api/tools' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

​

POST /api/tools

{
  "name": "weather_lookup",
  "description": "Get current weather for a city",
  "type": "http",
  "input_schema": {
    "type": "object",
    "properties": { "city": { "type": "string" } },
    "required": ["city"]
  },
  "config": {
    "endpoint": "https://api.weather.com/v1/current",
    "method": "GET"
  }
}

response = requests.post(f"{BASE_URL}/api/tools", headers=headers, json={
    "name": "weather_lookup",
    "description": "Get current weather",
    "type": "http",
    "input_schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
    "config": {"endpoint": "https://api.weather.com/v1/current", "method": "GET"},
})

const res = await fetch(`${BASE_URL}/api/tools`, { method: "POST", headers, body: JSON.stringify({
  name: "weather_lookup",
  description: "Get current weather",
  type: "http",
  input_schema: { type: "object", properties: { city: { type: "string" } }, required: ["city"] },
  config: { endpoint: "https://api.weather.com/v1/current", method: "GET" },
}) });

curl -X POST '{BASE_URL}/api/tools' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" -H "Content-Type: application/json" -d '{"name": "weather_lookup", "description": "...", "type": "http", "input_schema": {"type": "object"}, "config": {"endpoint": "https://api.weather.com/v1/current"}}'

​

GET /api/tools/

response = requests.get(f"{BASE_URL}/api/tools/{tool_id}", headers=headers)

const res = await fetch(`${BASE_URL}/api/tools/${toolId}`, { headers });

curl '{BASE_URL}/api/tools/{id}' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

​

PUT /api/tools/

response = requests.put(f"{BASE_URL}/api/tools/{tool_id}", headers=headers, json={"description": "Updated"})

await fetch(`${BASE_URL}/api/tools/${toolId}`, { method: "PUT", headers, body: JSON.stringify({ description: "Updated" }) });

curl -X PUT '{BASE_URL}/api/tools/{id}' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" -H "Content-Type: application/json" -d '{"description": "Updated"}'

​

DELETE /api/tools/

response = requests.delete(f"{BASE_URL}/api/tools/{tool_id}", headers=headers)

await fetch(`${BASE_URL}/api/tools/${toolId}`, { method: "DELETE", headers });

curl -X DELETE '{BASE_URL}/api/tools/{id}' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

​

Data tool access and limits

​

Database tools

• Configured tables are the whole reach. The table list in the tool assignment’s config_override.schemas (set with PATCH /api/agents/{id}/tools/{assignment_id}; see Tool assignments) is everything the tool can read or write. An agent with no table list reaches nothing.
• Only tables and security_invoker views. You may configure plain tables, partitioned tables, and views created WITH (security_invoker = true). Naming a view without security_invoker, a materialized view, or a foreign table answers 400 when you assign or update the tool, and the check runs again at run time. A table that doesn’t exist yet may be configured.
• database_query is parsed, not trusted. It accepts one SELECT that writes and locks nothing and references only the configured tables. It may call only a fixed allowlist of built-in functions, matched as Postgres resolves them (a quoted "Sum" is not sum), use only allowlisted operators, and cast only to built-in types. Functions that change or read settings or run a SQL string, your own functions, operators written in SQL or PL/pgSQL in your schemas, and casts to domains are rejected. An operator an installed extension defines is accepted when its symbol is on the list (pgvector’s distances <->, <=>, <#> and <+>, and symbols such as &&, @> or ->) and the extension lives in one of the agent’s configured schemas; an extension installed in a schema the agent isn’t configured with, such as the default extensions schema, isn’t visible to its queries. Functions that extensions add are rejected. The allowlists are fixed and can’t be configured. A rejected query returns an error to the agent naming what was refused:
  Function <name> is not allowed: only a fixed set of built-in functions may be called
  Operator <operator> is not allowed
  
• Timeouts. Every tool transaction has a 30-second statement timeout and a 5-second lock timeout, whatever timeout the authenticated role has elsewhere.
• Logins. End-user runs use one shared login, powabase_agent_user, which can only become authenticated and carries the user’s JWT claims. Each agent that has a database tool gets its own login, powabase_agent_<agent id without dashes>, which is a member of no other role; an agent without database tools gets none. None of these logins is a superuser, and deleting an agent drops its login.
• Expired tokens. Tool calls on an end user’s run are refused once that user’s token has expired.

​

Storage tools

• On an end user’s run, the tools call Storage with the user’s own token, so your Storage policies for that user apply. On a service-role run they use the service role key.
• Bucket names must match ^[A-Za-z0-9_-]+$, which is stricter than Storage itself: a bucket whose name contains a . or a space can’t be used from a tool.
• Each /-separated part of a path must be a name: not empty, . or .., and without %, \, ?, # or control characters.
• The internal sources bucket, which holds the original files of ingested sources, is never reachable from a tool.
• Errors come back to the agent as short messages: not found, access denied, or failed with a status.

​

Error Responses