Skip to main content

​
Base URL

All API requests are sent to a single endpoint on your Supabase project: 
POST https://<your-project>.supabase.co/functions/v1/api
Every request uses the POST method with a JSON body that specifies the resource, action, and any required parameters.

​
Authentication

Include a Supabase session access token in the Authorization header of every request. 
Authorization: Bearer <session_access_token>
Content-Type: application/json
Obtain a token through Supabase Auth: 
const {
  data: { session },
} = await supabase.auth.getSession();
const accessToken = session?.access_token;
Requests without a valid token return a 401 UNAUTHORIZED error.

​
Request format

All requests share the same shape: 
{
  "resource": "genies",
  "action": "list",
  "id": "optional-resource-id",
  "data": {
    // action-specific parameters
  }
}
​
resource
string
required
The API resource to operate on. One of genies, documents, document-folders, or genie-groups.
​
action
string
required
The action to perform on the resource (for example list, get, create, update, delete).
​
id
string
The resource identifier, required for actions that target a specific record such as get, update, and delete.
​
data
object
Action-specific parameters such as filters, pagination options, or field values.

​
Response envelope

Every response follows a consistent envelope. Success (2xx): 
{
  "success": true,
  "data": {
    // action-specific response data
  }
}
Error (4xx / 5xx): 
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "status": 400
  }
}

​
Error codes

CodeStatusDescription
UNAUTHORIZED401Missing or invalid Authorization header
INVALID_TOKEN401Token is invalid or expired
FORBIDDEN403User lacks permission for the resource
NOT_FOUND404Resource not found
AGENT_NOT_FOUND404Genie not found or access denied
VALIDATION_ERROR400Invalid request format or data
INVALID_ACTION400Action not supported for the resource
RATE_LIMIT_EXCEEDED429Too many requests
INTERNAL_ERROR500Server error

​
Access control

User roles determine what data is accessible:
  • internal_admin — Full access to all resources across all users.
  • standard_user — Access only to their own genies, documents, and related data.
  • consumer — Limited read-only access to assigned genies.
Admin users can pass adminMode: true or a userId parameter to operate on resources owned by other users.

​
Resources

Genies

Create, update, list, and delete voice AI genies

Knowledge base

Manage documents and attach them to genies

Document folders

Organize knowledge base documents into folders

Genie groups

Group and organize genies