Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.powabase.ai/llms.txt

Use this file to discover all available pages before exploring further.

Agents are the conversational core of the platform. Each agent wraps an LLM with a system prompt, tools, knowledge bases, and optional MCP servers. Agents use a ReAct loop to reason about user messages, call tools as needed, and generate streaming responses. Sessions maintain conversation history across multiple turns.

​
Common Patterns

Create an agent, assign tools and knowledge bases, then use the streaming endpoint for conversations. Pass session_id to continue multi-turn conversations. For human-in-the-loop workflows, configure hooks and use the approve endpoint when approval_requested events are received.

​
Agent CRUD

​
GET /api/agents

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

​
POST /api/agents

Create a new agent. 
{
  "name": "My Agent",
  "model": "gpt-4o",
  "system_prompt": "You are a helpful assistant.",
  "temperature": 0.7
}

response = requests.post(f"{BASE_URL}/api/agents", headers=headers, json={"name": "My Agent", "model": "gpt-4o", "system_prompt": "You are helpful.", "temperature": 0.7})

​
GET /api/agents/

Get an agent by ID.
​
id
string
required
Agent ID
response = requests.get(f"{BASE_URL}/api/agents/{agent_id}", headers=headers)

​
PATCH /api/agents/

Update an agent’s name, model, system prompt, or settings.
​
id
string
required
Agent ID
response = requests.patch(f"{BASE_URL}/api/agents/{agent_id}", headers=headers, json={"temperature": 0.5})

​
DELETE /api/agents/

Delete an agent.
​
id
string
required
Agent ID
response = requests.delete(f"{BASE_URL}/api/agents/{agent_id}", headers=headers)

​
Tool Assignments

​
POST /api/agents//tools

Assign a tool to the agent.
​
id
string
required
Agent ID
{ "tool_name": "database_query" }

response = requests.post(f"{BASE_URL}/api/agents/{agent_id}/tools", headers=headers, json={"tool_name": "database_query"})

​
GET /api/agents//tools

List tool assignments for the agent.
​
id
string
required
Agent ID
response = requests.get(f"{BASE_URL}/api/agents/{agent_id}/tools", headers=headers)

​
PATCH /api/agents//tools/

Update tool assignment configuration.
​
id
string
required
Agent ID
​
assignment_id
string
required
Assignment ID
response = requests.patch(f"{BASE_URL}/api/agents/{agent_id}/tools/{assignment_id}", headers=headers, json={"config": {"allowed_schemas": ["public", "ai"]}})

​
DELETE /api/agents//tools/

Remove a tool assignment from the agent.
​
id
string
required
Agent ID
​
assignment_id
string
required
Assignment ID
response = requests.delete(f"{BASE_URL}/api/agents/{agent_id}/tools/{assignment_id}", headers=headers)

​
Knowledge Base Assignments

​
POST /api/agents//knowledge-bases

Link a knowledge base to the agent. Creates a dynamic search tool.
​
id
string
required
Agent ID
{ "knowledge_base_id": "kb-uuid" }

response = requests.post(f"{BASE_URL}/api/agents/{agent_id}/knowledge-bases", headers=headers, json={"knowledge_base_id": kb_id})

​
GET /api/agents//knowledge-bases

List knowledge base assignments for the agent.
​
id
string
required
Agent ID
response = requests.get(f"{BASE_URL}/api/agents/{agent_id}/knowledge-bases", headers=headers)

​
DELETE /api/agents//knowledge-bases/

Remove a knowledge base from the agent.
​
id
string
required
Agent ID
​
assignment_id
string
required
Assignment ID
response = requests.delete(f"{BASE_URL}/api/agents/{agent_id}/knowledge-bases/{assignment_id}", headers=headers)

​
MCP Servers

​
POST /api/agents//mcp-servers

Add an MCP server to the agent.
​
id
string
required
Agent ID
{
  "url": "https://mcp.example.com",
  "transport": "sse",
  "name": "My MCP"
}

response = requests.post(f"{BASE_URL}/api/agents/{agent_id}/mcp-servers", headers=headers, json={"url": "https://mcp.example.com", "transport": "sse", "name": "My MCP"})

​
GET /api/agents//mcp-servers

List MCP servers for the agent.
​
id
string
required
Agent ID
response = requests.get(f"{BASE_URL}/api/agents/{agent_id}/mcp-servers", headers=headers)

​
PUT /api/agents//mcp-servers/

Update an MCP server configuration.
​
id
string
required
Agent ID
​
server_id
string
required
MCP Server ID
response = requests.put(f"{BASE_URL}/api/agents/{agent_id}/mcp-servers/{server_id}", headers=headers, json={"url": "https://new-url.com"})

​
DELETE /api/agents//mcp-servers/

Remove an MCP server from the agent.
​
id
string
required
Agent ID
​
server_id
string
required
MCP Server ID
response = requests.delete(f"{BASE_URL}/api/agents/{agent_id}/mcp-servers/{server_id}", headers=headers)

​
Hooks

​
POST /api/agents//hooks

Add a hook to the agent (pre/post execution events).
​
id
string
required
Agent ID
response = requests.post(f"{BASE_URL}/api/agents/{agent_id}/hooks", headers=headers, json={"event": "before_run", "type": "webhook", "config": {"url": "https://example.com/hook"}})

​
GET /api/agents//hooks

List hooks for the agent.
​
id
string
required
Agent ID
response = requests.get(f"{BASE_URL}/api/agents/{agent_id}/hooks", headers=headers)

​
DELETE /api/agents//hooks/

Remove a hook from the agent.
​
id
string
required
Agent ID
​
hook_id
string
required
Hook ID
response = requests.delete(f"{BASE_URL}/api/agents/{agent_id}/hooks/{hook_id}", headers=headers)

​
Execution

​
GET /api/agents//sessions

List chat sessions for the agent.
​
id
string
required
Agent ID
response = requests.get(f"{BASE_URL}/api/agents/{agent_id}/sessions", headers=headers)

​
POST /api/agents//run

Run agent synchronously (no tools, no streaming). Returns full response.
​
id
string
required
Agent ID
{ "message": "Hello" }

response = requests.post(f"{BASE_URL}/api/agents/{agent_id}/run", headers=headers, json={"message": "Hello"})

​
POST /api/agents//run/stream

Run agent with streaming SSE. Supports tools, ReAct loop, and multi-turn via session_id.
​
id
string
required
Agent ID
{
  "message": "Hello",
  "session_id": "optional-session-uuid"
}

response = requests.post(
    f"{BASE_URL}/api/agents/{agent_id}/run/stream",
    headers=headers,
    json={"message": "Hello"},
    stream=True,
)
for line in response.iter_lines():
    if line and line.decode().startswith("data: "):
        event = json.loads(line.decode()[6:])
        print(event)

​
POST /api/agents/runs//approve

Approve or deny a pending tool call (human-in-the-loop).
​
run_id
string
required
Run ID
{ "approved": true }

response = requests.post(f"{BASE_URL}/api/agents/runs/{run_id}/approve", headers=headers, json={"approved": True})

​
Error Responses

StatusCodeDescription
400invalid_configInvalid agent configuration (e.g., unsupported model, invalid temperature)
404agent_not_foundNo agent exists with the given ID
409tool_conflictThe tool is already assigned to this agent