### List Available Extensions

Source: https://docs.powabase.ai/api-reference/extensions

This SQL query shows extensions that are available to be installed in your project but are not yet installed. You can install them using `CREATE EXTENSION`.

```sql
SELECT name, default_version
FROM pg_available_extensions
WHERE installed_version IS NULL
ORDER BY name;
```

--------------------------------

### Verify API Setup with a Request

Source: https://docs.powabase.ai/guides/auth-connection

Confirm your authentication setup by making a request to a simple endpoint like /api/agents. This verifies that your credentials and headers are correctly configured.

```Python
response = requests.get(
    f"{BASE_URL}/api/agents",
    headers=headers,
)
print(response.json())
```

```TypeScript
const response = await fetch(`${BASE_URL}/api/agents`, { headers });
const agents = await response.json();
console.log(agents);
```

```cURL
curl '{BASE_URL}/api/agents' \
  -H "apikey: {API_KEY}" \
  -H "Authorization: Bearer {API_KEY}"
```

--------------------------------

### Create pg_net Extension

Source: https://docs.powabase.ai/concepts/schemas

Example of how to create the pg_net extension within the extensions schema. This is a common operation when installing new Postgres extensions.

```sql
CREATE EXTENSION IF NOT EXISTS pg_net SCHEMA extensions;
```

--------------------------------

### Deploy or Arm a Workflow (cURL)

Source: https://docs.powabase.ai/guides/workflows-programmatic

Deploy or arm a workflow using cURL. This example shows the POST request for deployment and a GET request to read the workflow graph to extract webhook credentials.

```bash
# Deploy (or arm)
curl -X POST '{BASE_URL}/api/workflows/{wf_id}/deploy' \
  -H "apikey: {API_KEY}" \
  -H "Authorization: Bearer {API_KEY}"

# Read graph and pull webhook_id / webhook_secret from the block whose type=="webhook"
curl '{BASE_URL}/api/workflows/{wf_id}' \
  -H "apikey: {API_KEY}" \
  -H "Authorization: Bearer {API_KEY}"
```

--------------------------------

### Signup Request Body Example

Source: https://docs.powabase.ai/api-reference/auth

Example JSON payload for creating a new user via email and password. The 'data' field can include arbitrary user-defined metadata.

```json
{
  "email": "alice@example.com",
  "password": "correcthorsebatterystaple",
  "data": { "display_name": "Alice" }
}
```

--------------------------------

### List Installed Extensions

Source: https://docs.powabase.ai/api-reference/extensions

Use this SQL query to view extensions currently installed in your Powabase project, including their schema and version.

```sql
SELECT extname, nspname AS schema, extversion
FROM pg_extension e
JOIN pg_namespace n ON n.oid = e.extnamespace
ORDER BY extname;
```

--------------------------------

### Install pg_trgm and citext Extensions

Source: https://docs.powabase.ai/api-reference/extensions

Installs the pg_trgm and citext extensions into the 'extensions' schema. Requires connection as 'supabase_admin'.

```sql
CREATE EXTENSION IF NOT EXISTS pg_trgm SCHEMA extensions;
CREATE EXTENSION IF NOT EXISTS citext SCHEMA extensions;
```

--------------------------------

### Agent Run Request Example

Source: https://docs.powabase.ai/api-reference/agents

Example JSON payload for running an agent synchronously. It includes the user's message, an optional session ID, and knowledge base retrieval parameters.

```json
{
  "message": "Hello",
  "session_id": "optional-session-uuid",
  "knowledge_bases": [{ "id": "kb-uuid", "top_k": 5 }],
  "max_context_tokens": 8000,
  "citations_enabled": false
}
```

--------------------------------

### Realtime WebSocket Connection Setup

Source: https://docs.powabase.ai/guides/realtime-subscriptions

Establishes a WebSocket connection to Powabase Realtime. Requires an API key and uses a specific protocol version. This setup is common for all realtime recipes.

```typescript
const BASE_URL = "wss://{ref}.p.powabase.ai";
const ANON_KEY = "<your anon key>";

function connect(token: string = ANON_KEY): WebSocket {
  const url = `${BASE_URL}/realtime/v1/websocket?apikey=${token}&vsn=1.0.0`;
  return new WebSocket(url);
}
```

--------------------------------

### String Substitution Example

Source: https://docs.powabase.ai/concepts/workflows-concept

When used inside a string configuration, placeholders like '<fetch.output.name>' are substituted with their resolved string values.

```text
"Hello <fetch.output.name>!"
```

--------------------------------

### User Signup with Email and Password

Source: https://docs.powabase.ai/api-reference/auth

Demonstrates how to sign up a new user using email and password. The Python, TypeScript, and cURL examples show how to make the POST request with the necessary headers and JSON body.

```python
requests.post(
    f"{BASE_URL}/auth/v1/signup",
    headers={"apikey": ANON_KEY, "Authorization": f"Bearer {ANON_KEY}", "Content-Type": "application/json"},
    json={"email": "alice@example.com", "password": "correcthorsebatterystaple"},
)
```

```typescript
await fetch(`${BASE_URL}/auth/v1/signup`, {
    method: "POST",
    headers: { apikey: ANON_KEY, Authorization: `Bearer ${ANON_KEY}`, "Content-Type": "application/json" },
    body: JSON.stringify({ email: "alice@example.com", password: "correcthorsebatterystaple" }),
  });
```

```bash
curl -X POST '{BASE_URL}/auth/v1/signup' \
    -H "apikey: <ANON_KEY>" -H "Authorization: Bearer <ANON_KEY>" -H "Content-Type: application/json" \
    -d '{"email": "alice@example.com", "password": "correcthorsebatterystaple"}'
```

--------------------------------

### Get Agent Run Record

Source: https://docs.powabase.ai/concepts/common-pitfalls

Retrieve the full details of an agent run, including status, errors, and events. The 'error' field is the primary starting point for debugging.

```bash
GET /api/agents/runs/{run_id}
```

--------------------------------

### Create Knowledge Base with Full Document Strategy (TypeScript)

Source: https://docs.powabase.ai/concepts/knowledge-bases-indexing

This TypeScript example demonstrates how to initialize a knowledge base using the 'full_document' indexing strategy. It includes configurations for the name, indexing, and retrieval settings, including a specific top_k value.

```typescript
const res = await fetch(`${BASE_URL}/api/knowledge-bases`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    name: "Case Law",
    indexing_config: {
      strategy: "full_document",
      summary_model: "gpt-5-mini",
      embedding_model: "text-embedding-3-small",
    },
    retrieval_config: {
      method: "hybrid",
      top_k: 3,
    },
  }),
});

```

--------------------------------

### Create Knowledge Base with Hybrid Search (Python)

Source: https://docs.powabase.ai/concepts/knowledge-bases-indexing

Demonstrates how to create a new knowledge base using Python, configuring it to use the hybrid retrieval method with a specified vector weight.

```python
import requests

BASE_URL = "YOUR_BASE_URL"
API_KEY = "YOUR_API_KEY"

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

# Create a KB with hybrid search retrieval
response = requests.post(
    f"{BASE_URL}/api/knowledge-bases",
    headers=headers,
    json={
        "name": "Product Docs",
        "indexing_config": {
            "strategy": "chunk_embed",
            "chunk_size": 2000,
            "overlap": 50,
        },
        "retrieval_config": {
            "method": "hybrid",
            "top_k": 10,
            "vector_weight": 0.6,
        },
    },
)

print(response.json())
```

--------------------------------

### List Entities in Orchestration (Python, TypeScript, cURL)

Source: https://docs.powabase.ai/api-reference/orchestrations

Examples for listing all entities within a specific orchestration using Python, TypeScript, and cURL. These snippets demonstrate the GET request with necessary headers.

```python
requests.get(f"{BASE_URL}/api/orchestrations/{orch_id}/entities", headers=headers)
```

```typescript
await fetch(`${BASE_URL}/api/orchestrations/${orchId}/entities`, { headers });
```

```bash
curl '{BASE_URL}/api/orchestrations/{id}/entities' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"
```

--------------------------------

### Create Bucket with Python

Source: https://docs.powabase.ai/api-reference/storage

Example of creating a storage bucket using Python's requests library. Ensure you provide the correct API keys and content type.

```python
requests.post(
    f"{BASE_URL}/storage/v1/bucket",
    headers={"apikey": SERVICE_ROLE_KEY, "Authorization": f"Bearer {SERVICE_ROLE_KEY}", "Content-Type": "application/json"},
    json={"id": "avatars", "public": True, "allowed_mime_types": ["image/png", "image/jpeg"]},
)
```

--------------------------------

### User Signup with Email and Password (cURL)

Source: https://docs.powabase.ai/guides/auth-signup-signin

Creates a new user with email and password using cURL. This command-line example demonstrates the request structure for signup.

```cURL
curl -X POST 'https://{ref}.p.powabase.ai/auth/v1/signup' \
    -H "apikey: <ANON_KEY>" \
    -H "Authorization: Bearer <ANON_KEY>" \
    -H "Content-Type: application/json" \
    -d '{"email": "alice@example.com", "password": "correcthorsebatterystaple"}'

```

--------------------------------

### Get Context Handler Result by ID

Source: https://docs.powabase.ai/api-reference/context-handlers

Get a context handler result by ID.

```APIDOC
## GET /api/context-handlers/{id}

### Description
Get a context handler result by ID.

### Method
GET

### Endpoint
/api/context-handlers/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - Handler ID

### Response
#### Success Response (200)
- **result** (object) - The result of the context handler execution.
```

--------------------------------

### Create a Knowledge Base

Source: https://docs.powabase.ai/guides/create-knowledge-base

Use this endpoint to create a new knowledge base. Provide a name and description. The default indexing strategy is used unless specified.

```Python
response = requests.post(
    f"{BASE_URL}/api/knowledge-bases",
    headers=headers,
    json={
        "name": "Product Docs",
        "description": "Product documentation and guides",
    },
)
kb = response.json()
kb_id = kb["id"]
print(f"KB created: {kb_id}")
```

```TypeScript
const response = await fetch(`${BASE_URL}/api/knowledge-bases`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    name: "Product Docs",
    description: "Product documentation and guides",
  }),
});
const kb = await response.json();
console.log("KB created:", kb.id);
```

```cURL
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 and guides"}'
```

--------------------------------

### SQLAlchemy Async Engine Setup

Source: https://docs.powabase.ai/guides/orm-sqlalchemy

Sets up an asynchronous SQLAlchemy engine using `psycopg`'s async driver. It configures the engine with `NullPool` and `prepare_threshold=None` for pooler compatibility, suitable for async web frameworks.

```python
from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker

async_engine = create_async_engine(
    DATABASE_URL.replace("postgresql://", "postgresql+psycopg_async://", 1),
    poolclass=NullPool,
    connect_args={"prepare_threshold": None},
)

AsyncSessionLocal = async_sessionmaker(async_engine, expire_on_commit=False)

async def list_posts(user_id):
    async with AsyncSessionLocal() as session:
        result = await session.scalars(select(Post).where(Post.author_id == user_id))
        return result.all()
```

--------------------------------

### Agentic Webhook Example

Source: https://docs.powabase.ai/concepts/common-pitfalls

Example of an agentic webhook endpoint for triggering external systems. This is distinct from database webhooks.

```http
POST /api/webhooks/{id}
```

--------------------------------

### Deploy or Arm a Workflow (Python)

Source: https://docs.powabase.ai/guides/workflows-programmatic

Deploy or arm a workflow programmatically. This example shows how to initiate deployment and then retrieve webhook credentials from the workflow graph.

```python
# Deploy (or arm) the workflow
requests.post(f"{BASE_URL}/api/workflows/{wf_id}/deploy", headers=headers)
# OR: requests.post(f"{BASE_URL}/api/workflows/{wf_id}/arm", headers=headers)

# Look up webhook credentials from the saved graph (assumes one webhook block)
wf = requests.get(f"{BASE_URL}/api/workflows/{wf_id}", headers=headers).json()
webhook_block = next(b for b in wf["blocks"] if b["type"] == "webhook")
webhook_id = webhook_block["config"]["webhook_id"]
webhook_secret = webhook_block["config"]["webhook_secret"]
```

--------------------------------

### Webhook Request Body Example

Source: https://docs.powabase.ai/api-reference/webhooks

This is an example of the JSON body that can be sent to trigger a webhook. It includes variables that will be passed as input to the workflow.

```json
{
  "customer_email": "user@example.com",
  "amount_cents": 4900
}
```

--------------------------------

### Get Source Details (TypeScript)

Source: https://docs.powabase.ai/api-reference/sources

Fetch source details using its ID via a GET request. Ensure BASE_URL and headers are configured.

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

--------------------------------

### Sign in with Email and Password (cURL)

Source: https://docs.powabase.ai/guides/auth-signup-signin

A command-line interface example for signing in with email and password. It demonstrates the necessary HTTP method, endpoint, headers, and JSON payload for authentication.

```bash
curl -X POST 'https://{ref}.p.powabase.ai/auth/v1/token?grant_type=password' \
  -H "apikey: <ANON_KEY>" \
  -H "Authorization: Bearer <ANON_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"email": "alice@example.com", "password": "correcthorsebatterystaple"}'
```

--------------------------------

### Create Bucket with TypeScript

Source: https://docs.powabase.ai/api-reference/storage

Example of creating a storage bucket using TypeScript's fetch API. Authentication is handled via headers.

```typescript
await fetch(`${BASE_URL}/storage/v1/bucket`, {
    method: "POST",
    headers: { apikey: SERVICE_ROLE_KEY, Authorization: `Bearer ${SERVICE_ROLE_KEY}`, "Content-Type": "application/json" },
    body: JSON.stringify({ id: "avatars", public: true, allowed_mime_types: ["image/png", "image/jpeg"] }),
});
```

--------------------------------

### Get Source Details (Python)

Source: https://docs.powabase.ai/api-reference/sources

Retrieve details for a specific source using its ID via a GET request. Ensure BASE_URL and headers are configured.

```python
response = requests.get(f"{BASE_URL}/api/sources/{source_id}", headers=headers)
```

--------------------------------

### User Signup with Email and Password

Source: https://docs.powabase.ai/guides/auth-signup-signin

Creates a new user with email and password. If autoConfirm is true, a session is returned immediately. Otherwise, the user must verify their email first.

```Python
import requests

ANON_KEY = "<your anon key>"
BASE_URL = "https://{ref}.p.powabase.ai"

response = requests.post(
    f"{BASE_URL}/auth/v1/signup",
    headers={
        "apikey": ANON_KEY,
        "Authorization": f"Bearer {ANON_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "email": "alice@example.com",
        "password": "correcthorsebatterystaple",
    },
)
result = response.json()

# autoConfirm: true → session present
if "access_token" in result:
    access_token = result["access_token"]
    refresh_token = result["refresh_token"]
    print(f"Signed in. User id: {result['user']['id']}")
else:
    # autoConfirm: false → user must verify email first
    print(f"User created, verification email sent. User id: {result['id']}")

```

--------------------------------

### Update Entity in Orchestration Request Example

Source: https://docs.powabase.ai/api-reference/orchestrations

Example JSON payload for updating an entity within an orchestration. Only 'role_description', 'config', and 'position' are writable fields.

```json
{ "role_description": "Updated role" }
```

--------------------------------

### Create Schema Migrations Table

Source: https://docs.powabase.ai/guides/migrations

Bootstrap a table to track applied database migrations. This should be run once.

```sql
CREATE TABLE IF NOT EXISTS public.schema_migrations (
  version text PRIMARY KEY,
  applied_at timestamptz NOT NULL DEFAULT now()
);
```

--------------------------------

### Search Knowledge Base Request Example

Source: https://docs.powabase.ai/api-reference/knowledge-bases

Example JSON payload for searching a knowledge base. Includes query, top_k, retrieval_method, filter_metadata, similarity_threshold, and source_ids.

```json
{
  "query": "search text",
  "top_k": 5,
  "retrieval_method": "hybrid",
  "filter_metadata": { "topic": "billing" },
  "similarity_threshold": 0.3,
  "source_ids": ["src-uuid-1", "src-uuid-2"]
}
```

--------------------------------

### Create an Agent

Source: https://docs.powabase.ai/guides/build-agent

Define an agent with a name, LLM model, and system prompt. Use this to set up the agent's core behavior and identity.

```Python
response = requests.post(
    f"{BASE_URL}/api/agents",
    headers=headers,
    json={
        "name": "Support Bot",
        "model": "gpt-4o",
        "system_prompt": "You are a helpful support assistant. Answer questions using the knowledge base when available.",
        "settings": {"temperature": 0.7},
    },
)
agent = response.json()
agent_id = agent["id"]
print(f"Agent created: {agent_id}")
```

```TypeScript
const response = await fetch(`${BASE_URL}/api/agents`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    name: "Support Bot",
    model: "gpt-4o",
    system_prompt: "You are a helpful support assistant. Answer questions using the knowledge base when available.",
    settings: { temperature: 0.7 },
  }),
});
const agent = await response.json();
console.log("Agent created:", agent.id);
```

```cURL
curl -X POST '{BASE_URL}/api/agents' \
  -H "apikey: {API_KEY}" \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{ \
    "name": "Support Bot", \
    "model": "gpt-4o", \
    "system_prompt": "You are a helpful support assistant.", \
    "settings": {"temperature": 0.7} \
  }'
```

--------------------------------

### TypeORM QueryBuilder Example

Source: https://docs.powabase.ai/guides/orm-typeorm

Utilize TypeORM's QueryBuilder for complex queries, including joins, filtering, and ordering. This example fetches recent published posts with their authors.

```typescript
const recentPosts = await postRepo
  .createQueryBuilder("post")
  .innerJoinAndSelect("post.author", "author")
  .where("post.published = :published", { published: true })
  .andWhere("post.created_at > :since", { since: thirtyDaysAgo })
  .orderBy("post.created_at", "DESC")
  .take(50)
  .getMany();
```

--------------------------------

### Get KB Defaults (Python)

Source: https://docs.powabase.ai/api-reference/knowledge-bases

Fetches KB creation defaults and prints available strategies and extraction options. Use this to dynamically populate UI elements.

```python
defaults = requests.get(f"{BASE_URL}/api/config/kb-defaults", headers=headers).json()
print(list(defaults["strategies"].keys()))
print([opt["value"] for opt in defaults["extraction"]["options"]])
```

--------------------------------

### Get KB Creation Defaults

Source: https://docs.powabase.ai/api-reference/knowledge-bases

Returns the platform's KB-creation defaults. This is useful for UI flows to present valid options without hardcoding them. The Studio's KB-create wizard uses this exact endpoint.

```APIDOC
## GET /api/config/kb-defaults

### Description
Returns the platform's KB-creation defaults so a UI or self-service KB-creation flow can present valid options without hardcoding them. The Studio's KB-create wizard uses this exact endpoint.

### Method
GET

### Endpoint
/api/config/kb-defaults

### Response
#### Success Response (200)
- **strategies** (map) - map of strategy name → `{ label, compatible_retrievers, retriever_labels, default_retrieval_method, supports_reranker, default_indexing_config, default_retrieval_config }`
- **reranker** (object) - `{ default_model, candidate_count, options }`
- **query_enrichment** (object) - `{ model }`
- **enrichment** (object) - `{ model, max_tokens }`
- **hybrid_vector_weight** (number) - default weight for hybrid search
- **extraction** (object) - `{ default_method, fallback_chain, options }`

### Response Example
```json
{
  "strategies": {
    "graph-enrichment": {
      "label": "Graph Enrichment",
      "compatible_retrievers": ["hybrid", "vector", "sparse"],
      "retriever_labels": {"hybrid": "Hybrid Search", "vector": "Vector Search", "sparse": "Sparse Search"},
      "default_retrieval_method": "hybrid",
      "supports_reranker": true,
      "default_indexing_config": {"strategy": "graph-enrichment", "chunking": {"strategy": "by_document"}, "embedding": {"model": "all-MiniLM-L6-v2"}, "enrichment": {"model": "gpt-3.5-turbo"}},
      "default_retrieval_config": {"strategy": "hybrid", "reranker": {"model": "Cohere v3"}, "hybrid_weight": 0.5}
    }
  },
  "reranker": {
    "default_model": "Cohere v3",
    "candidate_count": 3,
    "options": ["Cohere v3", "Jina v2", "Voyage 2.5", "ZeroEntropy zerank-2"]
  },
  "query_enrichment": {"model": "gpt-3.5-turbo"},
  "enrichment": {"model": "gpt-3.5-turbo", "max_tokens": 1000},
  "hybrid_vector_weight": 0.5,
  "extraction": {
    "default_method": "auto",
    "fallback_chain": ["mistral", "fitz"],
    "options": [
      {"value": "auto", "label": "Automatic (recommended)", "description": "Automatically select the best extraction method based on the document type."}, 
      {"value": "mistral", "label": "Mistral", "description": "Use the Mistral LLM for extraction."}, 
      {"value": "paddleocr", "label": "PaddleOCR", "description": "Use PaddleOCR for text extraction from images."}, 
      {"value": "lighton", "label": "LightOn", "description": "Use LightOn for extraction."}, 
      {"value": "opendataloader", "label": "OpenDataLoader", "description": "Use OpenDataLoader for extraction."}, 
      {"value": "fitz", "label": "Fitz", "description": "Use Fitz (PyMuPDF) for PDF extraction."}, 
      {"value": "pdfplumber", "label": "PDFPlumber", "description": "Use PDFPlumber for PDF extraction."} 
    ]
  }
}
```

### Error Responses
KB routes return `{"error": "<message>"}` (no structured error code field).

| Status | Description                                                                                                     |
| ------ | --------------------------------------------------------------------------------------------------------------- |
| 400    | Invalid chunking, embedding, or enrichment field configuration                                                  |
| 400    | Endpoint requires a specific `indexing_config.strategy` (e.g. graph-enrichment endpoints require `graph_index`) |
| 404    | No knowledge base or indexed source exists with the given ID                                                    |
| 404    | No enrichment config exists (DELETE `/enrichment`, GET `/enrichment/results`)                                   |
| 409    | Indexing for this source has already finished or been cancelled (`/sources/{id}/cancel`)                        |
| 409    | Cannot update or delete enrichment config while a run is active                                                 |
| 503    | Failed to dispatch the indexing task (worker unavailable)                                                       |
```

--------------------------------

### Create Custom Tool (Python)

Source: https://docs.powabase.ai/api-reference/tools

Programmatically create a custom tool using Python. This example demonstrates sending the tool definition, including name, description, type, input schema, and configuration, via a POST request.

```Python
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"},
  })
```

--------------------------------

### Create Agent and Link Knowledge Base

Source: https://docs.powabase.ai/guides/quickstart

Create an agent and link the knowledge base to it. The agent automatically gets a search tool for each linked knowledge base.

```cURL
# 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}" \

```

--------------------------------

### GET /api/orchestrations

Source: https://docs.powabase.ai/api-reference/orchestrations

Retrieves a list of all available orchestrations.

```APIDOC
## GET /api/orchestrations

### Description
List all orchestrations.

### Method
GET

### Endpoint
/api/orchestrations

### Parameters
(No parameters specified in source)

### Request Example
(Request example not provided in source)

### Response
(Success response details not provided in source)

### Response Example
(Response example not provided in source)
```

--------------------------------

### Create Agent and Link Knowledge Base

Source: https://docs.powabase.ai/guides/quickstart

Create an agent and link the knowledge base to it. The agent automatically gets a search tool for each linked knowledge base.

```Python
# 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()}")
```

--------------------------------

### GET /auth/v1/admin/users

Source: https://docs.powabase.ai/api-reference/auth

List all users in the project. Supports pagination.

```APIDOC
## GET /auth/v1/admin/users

### Description
List all users in the project. Supports pagination via `page` and `per_page` (default 50).

### Method
GET

### Endpoint
/auth/v1/admin/users

### Parameters
#### Query Parameters
- **page** (integer) - Optional - The page number to retrieve.
- **per_page** (integer) - Optional - The number of users per page (default 50).

### Response
#### Success Response (200)
- **users** (array) - An array of user objects.
- **total_pages** (integer) - The total number of pages available.
```

--------------------------------

### Set Up Authentication Headers

Source: https://docs.powabase.ai/guides/quickstart

Configure base URL and authentication headers required for all API requests. Ensure your Project URL and Service Role Key are correctly set.

```Python
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",
}
```

--------------------------------

### GET /api/workflows

Source: https://docs.powabase.ai/api-reference/workflows

Lists all available workflows with pagination support.

```APIDOC
## GET /api/workflows

### Description
List workflows.

### Method
GET

### Endpoint
/api/workflows

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Max results
- **offset** (integer) - Optional - Pagination offset

### Response
#### Success Response (200)
- **field1** (type) - Description
```

--------------------------------

### GET /api/agents/{id}/mcp-servers

Source: https://docs.powabase.ai/api-reference/agents

List MCP servers for the agent.

```APIDOC
## GET /api/agents/{id}/mcp-servers

### Description
List MCP servers for the agent.

### Method
GET

### Endpoint
/api/agents/{id}/mcp-servers

### Parameters
#### Path Parameters
- **id** (string) - Required - Agent ID

### Response
#### Success Response (200)
- (No specific response fields documented)
```

--------------------------------

### Deploy or Arm a Workflow (TypeScript)

Source: https://docs.powabase.ai/guides/workflows-programmatic

Deploy or arm a workflow using TypeScript. This example demonstrates initiating deployment and fetching webhook credentials from the workflow's graph configuration.

```typescript
// Deploy (or arm) the workflow
await fetch(`${BASE_URL}/api/workflows/${wfId}/deploy`, { method: "POST", headers });

// Look up webhook credentials from the saved graph (assumes one webhook block)
const wf = await fetch(`${BASE_URL}/api/workflows/${wfId}`, { headers }).then(r => r.json());
const webhookBlock = wf.blocks.find((b: { type: string }) => b.type === "webhook");
const webhookId = webhookBlock.config.webhook_id;
const webhookSecret = webhookBlock.config.webhook_secret;
```

--------------------------------

### GET /api/agents/{id}/knowledge-bases

Source: https://docs.powabase.ai/api-reference/agents

List knowledge base assignments for the agent.

```APIDOC
## GET /api/agents/{id}/knowledge-bases

### Description
List knowledge base assignments for the agent.

### Method
GET

### Endpoint
/api/agents/{id}/knowledge-bases

### Parameters
#### Path Parameters
- **id** (string) - Required - Agent ID

### Response
#### Success Response (200)
- (No specific response fields documented)
```

--------------------------------

### Deploy Workflow using Python, TypeScript, or cURL

Source: https://docs.powabase.ai/api-reference/workflows

Examples for deploying a workflow, which enables webhook triggering, using Python, TypeScript, or cURL.

```python
requests.post(f"{BASE_URL}/api/workflows/{wf_id}/deploy", headers=headers)
```

```typescript
await fetch(`${BASE_URL}/api/workflows/${wfId}/deploy`, { method: "POST", headers });
```

```bash
curl -X POST '{BASE_URL}/api/workflows/{id}/deploy' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"
```

--------------------------------

### Create Knowledge Base and Index Document

Source: https://docs.powabase.ai/guides/quickstart

Create a knowledge base and add a source to it. Adding a source automatically triggers chunking and vector indexing.

```cURL
# 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}"}'
```

--------------------------------

### Get Copilot Model Configuration

Source: https://docs.powabase.ai/api-reference/copilot

Retrieve the current model configuration for the copilot.

```APIDOC
## GET /api/copilot/settings/model

### Description
Get copilot model configuration.

### Method
GET

### Endpoint
/api/copilot/settings/model

### Response
#### Success Response (200)
- **model** (string) - The name of the currently configured copilot model.
```

--------------------------------

### GET /storage/v1/bucket/{id}

Source: https://docs.powabase.ai/api-reference/storage

Retrieves the metadata for a specific storage bucket identified by its ID.

```APIDOC
## GET /storage/v1/bucket/{id}

### Description
Get a specific bucket's metadata.

### Method
GET

### Endpoint
/storage/v1/bucket/{id}
```

--------------------------------

### List Agent Runs from AI Schema

Source: https://docs.powabase.ai/concepts/ai-schema-postgrest

This example demonstrates how to fetch a list of agent runs from the 'ai' schema using PostgREST. Ensure you set the 'Accept-Profile' header to 'ai' to target the correct schema. The 'apikey' and 'Authorization' headers are also required for authentication.

```bash
curl '{BASE_URL}/rest/v1/agent_runs?limit=10' \
  -H "Accept-Profile: ai" \
  -H "apikey: {API_KEY}" \
  -H "Authorization: Bearer {API_KEY}"
```

--------------------------------

### GET /api/workflows/{id}

Source: https://docs.powabase.ai/api-reference/workflows

Retrieves a specific workflow, including its blocks and edges, by its ID.

```APIDOC
## GET /api/workflows/{id}

### Description
Get workflow with blocks and edges.

### Method
GET

### Endpoint
/api/workflows/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - Workflow ID

### Response
#### Success Response (200)
- **field1** (type) - Description
```

--------------------------------

### Create Bucket with MIME Type and File Size Limits

Source: https://docs.powabase.ai/concepts/storage-model

Use this to create a new bucket and specify which MIME types are allowed and set a custom file size limit. Uploads violating these rules will be rejected.

```bash
POST /storage/v1/bucket
{
  "name": "avatars",
  "public": true,
  "allowed_mime_types": ["image/png", "image/jpeg", "image/webp"],
  "file_size_limit": 5242880
}
```

--------------------------------

### User Signup

Source: https://docs.powabase.ai/api-reference/auth

Creates a new user account using email and password. If `autoConfirm` is true, it returns a session immediately. Otherwise, the user must verify their email.

```APIDOC
## POST /auth/v1/signup

### Description
Create a new user with email + password (or phone + password if phone auth is enabled). On default `autoConfirm: true`, returns a session immediately. On `autoConfirm: false`, returns the user record only; the user must verify their email via the link sent by GoTrue.

### Method
POST

### Endpoint
/auth/v1/signup

### Parameters
#### Request Body
- **email** (string) - Email address. Either `email` or `phone` is required.
- **phone** (string) - E.164 phone number (e.g., `+14155552671`). Requires `GOTRUE_EXTERNAL_PHONE_ENABLED=true` and an SMS provider configured.
- **password** (string) - Required - At least 6 characters by GoTrue default.
- **data** (object) - Arbitrary key/value pairs to store in `user_metadata`. User-editable.
- **gotrue_meta_security** (object) - `{ captcha_token: "..." }` if CAPTCHA is enabled.

### Request Example
```json
{
  "email": "alice@example.com",
  "password": "correcthorsebatterystaple",
  "data": { "display_name": "Alice" }
}
```

### Response
#### Success Response (200)
**Response (autoConfirm: true):**
```json
{
  "access_token": "eyJ...",
  "token_type": "bearer",
  "expires_in": 3600,
  "expires_at": 1748563200,
  "refresh_token": "v1.MzQ1...",
  "user": {
    "id": "...",
    "aud": "authenticated",
    "role": "authenticated",
    "email": "alice@example.com",
    "user_metadata": {"display_name": "Alice"},
    "app_metadata": {"provider": "email", "providers": ["email"]},
    "created_at": "2026-05-29T00:00:00Z"
  }
}
```
**Response (autoConfirm: false):** the user object only, no tokens.
```

--------------------------------

### GET /api/orchestrations/{id}

Source: https://docs.powabase.ai/api-reference/orchestrations

Retrieves a specific orchestration by its ID, including its associated entities.

```APIDOC
## GET /api/orchestrations/{id}

### Description
Get orchestration with its entities.

### Method
GET

### Endpoint
/api/orchestrations/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - Orchestration ID

### Request Example
(Request example not provided in source)

### Response
(Success response details not provided in source)

### Response Example
(Response example not provided in source)
```

--------------------------------

### GET /api/tools/{id}

Source: https://docs.powabase.ai/api-reference/tools

Retrieves the definition of a specific tool using its unique identifier.

```APIDOC
## GET /api/tools/{id}

### Description
Get a tool definition by ID.

### Method
GET

### Endpoint
/api/tools/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - Tool ID

### Response
#### Success Response (200)
- **Tool Definition** (object) - The definition of the tool.

### Response Example
```json
{
  "id": "tool_id_example",
  "name": "Example Tool",
  "description": "This is an example tool.",
  "input_schema": {}
}
```

### Error Responses
- **404** - No tool exists with the given ID.
- **500** - Internal Server Error.
```

--------------------------------

### Create Orchestration and Add Entities (Python)

Source: https://docs.powabase.ai/concepts/orchestrations-concept

Use Python to create a new orchestration with the 'supervisor' strategy and add entity agents with specific roles. Ensure you have the 'requests' library installed.

```python
# Create an orchestration with the supervisor strategy
response = requests.post(
    f"{BASE_URL}/api/orchestrations",
    headers=headers,
    json={
        "name": "Customer Support Team",
        "strategy": "supervisor",
    },
)
orch = response.json()
orch_id = orch["id"]

# Add entity agents with clear role descriptions
requests.post(
    f"{BASE_URL}/api/orchestrations/{orch_id}/entities",
    headers=headers,
    json={
        "agent_id": billing_agent_id,
        "role": "Handles billing inquiries, invoices, payments, and refund requests",
    },
)

requests.post(
    f"{BASE_URL}/api/orchestrations/{orch_id}/entities",
    headers=headers,
    json={
        "agent_id": tech_agent_id,
        "role": "Handles technical issues, API errors, integration problems, and setup questions",
    },
)
```

--------------------------------

### Supabase Database URL Format

Source: https://docs.powabase.ai/guides/migrating-from-supabase

Example of the database URL format used by Supabase.

```text
postgresql://postgres.<ref>:<password>@aws-0-us-east-1.pooler.supabase.com:6543/postgres
```

--------------------------------

### Create Knowledge Base and Index Document

Source: https://docs.powabase.ai/guides/quickstart

Create a knowledge base and add a source to it. Adding a source automatically triggers chunking and vector indexing.

```Python
# 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()}")
```

--------------------------------

### GET /auth/v1/admin/users/{user_id}

Source: https://docs.powabase.ai/api-reference/auth

Fetch a specific user's details using their user ID.

```APIDOC
## GET /auth/v1/admin/users/{user_id}

### Description
Fetch a specific user, including the fields `GET /user` doesn't return (banned status, last sign-in, MFA factors, identities).

### Method
GET

### Endpoint
/auth/v1/admin/users/{user_id}

### Parameters
#### Path Parameters
- **user_id** (string) - Required - The ID of the user to fetch.
```

--------------------------------

### List Storage Buckets (Python)

Source: https://docs.powabase.ai/api-reference/auth-storage

Use this snippet to list all storage buckets for a given project reference. Requires your Studio app base URL, project reference, and a platform JWT.

```Python
response = requests.get(
    f"{PLATFORM_URL}/api/platform/storage/{REF}/buckets",
    headers={"Authorization": "Bearer YOUR_PLATFORM_JWT"},
)
```

--------------------------------

### Create a Knowledge Base

Source: https://docs.powabase.ai/guides/quickstart

This snippet shows how to create a new knowledge base using a cURL command. Ensure you have the correct API key and content type headers.

```bash
curl -X POST "{BASE_URL}/api/knowledge-bases" \
    -H "apikey: {API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{"name": "My New Knowledge Base"}'
```

--------------------------------

### Get Workflow Execution Logs

Source: https://docs.powabase.ai/api-reference/workflows

Retrieves the per-block execution logs for a specific workflow execution.

```APIDOC
## GET /api/workflows/{id}/executions/{eid}/logs

### Description
Get per-block execution logs.

### Method
GET

### Endpoint
/api/workflows/{id}/executions/{eid}/logs

### Parameters
#### Path Parameters
- **id** (string) - Required - Workflow ID
- **eid** (string) - Required - Execution ID

### Response
Workflow routes return one of two body shapes:

* Plain `{"error": "<message>"}` — list/create/patch/delete and the deploy/undeploy/arm endpoints.
* Structured `{"error": "<message>", "error_code": "<UPPER_SNAKE_CODE>"}` (via the shared `error_response` helper) — `GET /workflows/{id}`, `PUT /workflows/{id}/graph`, and the synchronous `/execute` endpoint.
```

--------------------------------

### GET /api/sources/{id}

Source: https://docs.powabase.ai/api-reference/sources

Retrieve details for a specific source, including its current extraction status.

```APIDOC
## GET /api/sources/{id}

### Description
Get source details including extraction status.

### Method
GET

### Endpoint
/api/sources/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - Source ID

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the source.
- **name** (string) - The display name of the source.
- **metadata** (object) - Additional metadata associated with the source.
- **extraction_status** (string) - The current status of the extraction process (e.g., 'pending', 'processing', 'completed', 'failed').
```

--------------------------------

### Simulate PostgREST Session Setup

Source: https://docs.powabase.ai/guides/rls-testing

Mimics how PostgREST sets the role and JWT claims before executing a query. Use `SET LOCAL` within a `BEGIN...ROLLBACK` block for transactional testing.

```sql
SET LOCAL ROLE authenticated;   -- or anon, or service_role
SET LOCAL request.jwt.claims = '{"sub":"<user-uuid>","role":"authenticated","email":"u@x"}';
```

--------------------------------

### Get Copilot model configuration

Source: https://docs.powabase.ai/api-reference/copilot

Retrieve the current model configuration for the Copilot. This is a read-only operation.

```Python
requests.get(f"{BASE_URL}/api/copilot/settings/model", headers=headers)
```

```TypeScript
await fetch(`${BASE_URL}/api/copilot/settings/model`, { headers });
```

```cURL
curl '{BASE_URL}/api/copilot/settings/model' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"
```

--------------------------------

### Run Your Own Postgres Snapshot

Source: https://docs.powabase.ai/concepts/backups-and-dr

This bash command allows you to create your own daily `pg_dump` of your project's database. It connects via PgBouncer and streams the gzipped output to a local file. This provides a faster restore option under your control.

```bash
pg_dump "postgresql://<ref>:<password>@db.p.powabase.ai:5432/<ref>" \
  --no-owner --no-privileges \
  | gzip \
  > backup-$(date +%Y%m%d).sql.gz
```

--------------------------------

### Get Tool Definition

Source: https://docs.powabase.ai/api-reference/tools

Retrieve a tool definition by its ID using Python, TypeScript, or cURL.

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

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

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

--------------------------------

### Create Orchestration and Add Entity (cURL)

Source: https://docs.powabase.ai/concepts/orchestrations-concept

Use cURL to create an orchestration with the 'supervisor' strategy and add a single entity agent. Replace placeholders like {BASE_URL}, {API_KEY}, and {billing_agent_id} with your actual values.

```bash
# Create orchestration
curl -X POST '{BASE_URL}/api/orchestrations' \
  -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"name": "Customer Support Team", "strategy": "supervisor"}'

# Add billing agent entity
curl -X POST '{BASE_URL}/api/orchestrations/{orch_id}/entities' \
  -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "{billing_agent_id}", "role": "Handles billing inquiries, invoices, and payments"}'
```

--------------------------------

### User Signup with Email and Password

Source: https://docs.powabase.ai/guides/auth-signup-signin

Creates a new user with email and password. If autoConfirm is true, a session is returned immediately. Otherwise, the user must verify their email first. Tokens are persisted to local storage.

```TypeScript
const ANON_KEY = "<your anon key>";
const BASE_URL = "https://{ref}.p.powabase.ai";

const res = await fetch(`${BASE_URL}/auth/v1/signup`, {
  method: "POST",
  headers: {
    apikey: ANON_KEY,
    Authorization: `Bearer ${ANON_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    email: "alice@example.com",
    password: "correcthorsebatterystaple",
  }),
});
const result = await res.json();

if (result.access_token) {
  // Persist these — see "Storing tokens" below
  localStorage.setItem("powabase_access_token", result.access_token);
  localStorage.setItem("powabase_refresh_token", result.refresh_token);
  console.log("Signed in as", result.user.email);
} else {
  console.log("Confirmation email sent. User id:", result.id);
}

```