Quickstart - Powabase

In this guide you will upload a document, create a knowledge base, index the document into it, spin up an agent backed by that knowledge base, and run a streaming conversation, all through the REST API. By the end you will have a RAG agent that answers questions grounded in your own content.

Prerequisites:

A Powabase project — grab your Project URL and Service Role (Secret) Key from the Connect modal in the Studio (click the Connect button in your project header, or append ?showConnect=true to any project URL). See the Auth & Connection guide for the full walkthrough.

Authenticate

Set up your base URL and authentication headers. Copy Project URL and Service Role (Secret) Key from the Studio’s Connect modal. Every /api/* request needs the service role key in both the apikey and Authorization headers.Endpoint: Headers: apikey + Authorization

import requests

BASE_URL = "{BASE_URL}"   # Connect modal -> Project URL
API_KEY = "{API_KEY}"     # Connect modal -> Service Role (Secret) Key

headers = {
    "apikey": API_KEY,
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

const BASE_URL = "{BASE_URL}";  // Connect modal -> Project URL
const API_KEY = "{API_KEY}";    // Connect modal -> Service Role (Secret) Key

const headers = {
  apikey: API_KEY,
  Authorization: `Bearer ${API_KEY}`,
  "Content-Type": "application/json",
};

# Set these variables for the rest of the guide.
# Both values come from the Studio's Connect modal:
#   BASE_URL = Project URL
#   API_KEY  = Service Role (Secret) Key
BASE_URL="{BASE_URL}"
API_KEY="{API_KEY}"

Upload a document

Upload a file to create a Source. The platform automatically extracts its text content for indexing.Endpoint: POST /api/sources/upload

with open("product-docs.pdf", "rb") as f:
    response = requests.post(
        f"{BASE_URL}/api/sources/upload",
        headers={"apikey": API_KEY, "Authorization": f"Bearer {API_KEY}"},
        files={"file": ("product-docs.pdf", f, "application/pdf")},
    )
source = response.json()
source_id = source["id"]
print(f"Source created: {source_id}, status: {source['extraction_status']}")

# Poll until extraction completes
import time
TERMINAL = {"extracted", "attention_required", "failed", "cancelled"}
while True:
    res = requests.get(f"{BASE_URL}/api/sources/{source_id}", headers=headers)
    status = res.json()["extraction_status"]
    if status in TERMINAL:
        print(f"Extraction ended with status: {status}")
        break
    time.sleep(2)

const formData = new FormData();
formData.append("file", fileBlob, "product-docs.pdf");

const uploadRes = await fetch(`${BASE_URL}/api/sources/upload`, {
  method: "POST",
  headers: { apikey: API_KEY, Authorization: `Bearer ${API_KEY}` },
  body: formData,
});
const source = await uploadRes.json();
const sourceId = source.id;
console.log("Source created:", sourceId);

// Poll until extraction reaches a terminal state
const TERMINAL = new Set(["extracted", "attention_required", "failed", "cancelled"]);
let status = "pending";
while (!TERMINAL.has(status)) {
  await new Promise((r) => setTimeout(r, 2000));
  const res = await fetch(`${BASE_URL}/api/sources/${sourceId}`, { headers });
  status = (await res.json()).extraction_status;
}
console.log("Extraction ended with status:", status);

# Upload the document
curl -X POST '{BASE_URL}/api/sources/upload' \
  -H "apikey: {API_KEY}" \
  -H "Authorization: Bearer {API_KEY}" \
  -F "file=@product-docs.pdf"

# Poll extraction status (replace {source_id})
curl '{BASE_URL}/api/sources/{source_id}' \
  -H "apikey: {API_KEY}" \
  -H "Authorization: Bearer {API_KEY}"

Response:

{
  "id": "source-uuid",
  "name": "product-docs.pdf",
  "file_type": "application/pdf",
  "storage_path": "sources-{org}-{project}/{source_id}/product-docs.pdf",
  "extraction_status": "pending",
  "task_id": "celery-task-uuid"
}

Create a knowledge base and index the document

Create a knowledge base, then add the source to it. Adding a source triggers chunking and vector indexing automatically.Endpoint: POST /api/knowledge-bases

# Create the knowledge base
response = requests.post(
    f"{BASE_URL}/api/knowledge-bases",
    headers=headers,
    json={
        "name": "Product Docs",
        "description": "Product documentation knowledge base",
    },
)
kb = response.json()
kb_id = kb["id"]
print(f"Knowledge base created: {kb_id}")

# Add the source to trigger indexing
response = requests.post(
    f"{BASE_URL}/api/knowledge-bases/{kb_id}/sources",
    headers=headers,
    json={"source_id": source_id},
)
print(f"Source added, indexing started: {response.json()}")

// Create the knowledge base
const kbRes = await fetch(`${BASE_URL}/api/knowledge-bases`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    name: "Product Docs",
    description: "Product documentation knowledge base",
  }),
});
const kb = await kbRes.json();
const kbId = kb.id;
console.log("Knowledge base created:", kbId);

// Add the source to trigger indexing
await fetch(`${BASE_URL}/api/knowledge-bases/${kbId}/sources`, {
  method: "POST",
  headers,
  body: JSON.stringify({ source_id: sourceId }),
});
console.log("Source added, indexing started");

# Create the knowledge base
curl -X POST '{BASE_URL}/api/knowledge-bases' \
  -H "apikey: {API_KEY}" \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Docs",
    "description": "Product documentation knowledge base"
  }'

# Add source to trigger indexing (replace {kb_id})
curl -X POST '{BASE_URL}/api/knowledge-bases/{kb_id}/sources' \
  -H "apikey: {API_KEY}" \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"source_id": "{source_id}"}'

Create an agent with the knowledge base

Create an agent and link the knowledge base to it. The agent automatically gets a search tool for each linked knowledge base.Endpoint: POST /api/agents

# Create the agent
response = requests.post(
    f"{BASE_URL}/api/agents",
    headers=headers,
    json={
        "name": "Docs Assistant",
        "model": "gpt-4o",
        "system_prompt": "You are a helpful assistant. Use the knowledge base to answer questions about our product documentation.",
        "settings": {"temperature": 0.7},
    },
)
agent = response.json()
agent_id = agent["id"]
print(f"Agent created: {agent_id}")

# Link the knowledge base
response = requests.post(
    f"{BASE_URL}/api/agents/{agent_id}/knowledge-bases",
    headers=headers,
    json={"knowledge_base_id": kb_id},
)
print(f"Knowledge base linked: {response.json()}")

// Create the agent
const agentRes = await fetch(`${BASE_URL}/api/agents`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    name: "Docs Assistant",
    model: "gpt-4o",
    system_prompt: "You are a helpful assistant. Use the knowledge base to answer questions about our product documentation.",
    settings: { temperature: 0.7 },
  }),
});
const agent = await agentRes.json();
const agentId = agent.id;
console.log("Agent created:", agentId);

// Link the knowledge base
await fetch(`${BASE_URL}/api/agents/${agentId}/knowledge-bases`, {
  method: "POST",
  headers,
  body: JSON.stringify({ knowledge_base_id: kbId }),
});
console.log("Knowledge base linked");

# Create the agent
curl -X POST '{BASE_URL}/api/agents' \
  -H "apikey: {API_KEY}" \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Docs Assistant",
    "model": "gpt-4o",
    "system_prompt": "You are a helpful assistant.",
    "settings": {"temperature": 0.7}
  }'

# Link knowledge base (replace {agent_id})
curl -X POST '{BASE_URL}/api/agents/{agent_id}/knowledge-bases' \
  -H "apikey: {API_KEY}" \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"knowledge_base_id": "{kb_id}"}'

Chat with your agent (streaming)

Send a message and consume the SSE stream. The agent will search the knowledge base, reason about the results, and stream back an answer.Endpoint: POST /api/agents/{id}/run/stream

The agent will emit tool_call and tool_result events as it searches the knowledge base, followed by chunk events containing the streamed answer.

response = requests.post(
    f"{BASE_URL}/api/agents/{agent_id}/run/stream",
    headers=headers,
    json={"message": "How do I get started with the product?"},
    stream=True,
)

import json

session_id = None
for line in response.iter_lines():
    if not line:
        continue
    text = line.decode("utf-8")
    if text.startswith("data: "):
        event = json.loads(text[6:])
        if event["event"] == "start":
            session_id = event["session_id"]
        elif event["event"] == "chunk":
            print(event["content"], end="")
        elif event["event"] == "tool_call":
            print(f"\n[Searching: {event['tool_name']}]")
        elif event["event"] == "tool_result":
            print(f"[Results received]")
        elif event["event"] == "complete":
            print(f"\n\nDone! Session: {session_id}")

const response = await fetch(`${BASE_URL}/api/agents/${agentId}/run/stream`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    message: "How do I get started with the product?",
  }),
});

const reader = response.body!.getReader();
const decoder = new TextDecoder();
let sessionId: string | null = null;

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  const text = decoder.decode(value);
  for (const line of text.split("\n")) {
    if (line.startsWith("data: ")) {
      const event = JSON.parse(line.slice(6));
      if (event.event === "start") sessionId = event.session_id;
      if (event.event === "chunk") process.stdout.write(event.content);
      if (event.event === "tool_call") console.log(`\n[Searching: ${event.tool_name}]`);
      if (event.event === "tool_result") console.log("[Results received]");
      if (event.event === "complete") console.log(`\nDone! Session: ${sessionId}`);
    }
  }
}

curl -N -X POST '{BASE_URL}/api/agents/{agent_id}/run/stream' \
  -H "apikey: {API_KEY}" \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"message": "How do I get started with the product?"}'

What’s Next

Agents & Tools

Understand the ReAct loop, tool types, and how agents reason.

Streaming Responses

Deep dive into SSE event handling and multi-turn sessions.

Agents API Reference

Full endpoint documentation for agents.

​What’s Next

Agents & Tools

Streaming Responses

Agents API Reference

What’s Next