Skip to main content
The typed /api/* surface gives you RPC-style access to the AI features. Underneath, the state those endpoints manage lives in a single Postgres schema, ai: sources, knowledge bases, chunks, agents, runs, sessions, workflows and the rest. The ai schema is backend-only. Only the project service, using the Service Role, touches it. It isn’t exposed through PostgREST, and signed-in users and the Anon key have no access to it. Earlier versions of this page described querying ai.* via /rest/v1/*; that no longer works.

​
How ai.* is locked down

Since project-service migration 0025_lock_ai_schema_class_b:
  • ai is not in PostgREST’s exposed schemas (PGRST_DB_SCHEMAS), so /rest/v1/* requests with Accept-Profile: ai or Content-Profile: ai are rejected, whichever key you use.
  • Every authenticated and anon grant on the schema, its tables, sequences and RPC functions is revoked, and every authenticated / anon RLS policy on ai.* is dropped.
  • RLS stays enabled with no client policies, so access is deny-by-default. The service role bypasses RLS, which is how the project service reads and writes.
There are no per-user or per-tenant database policies on ai.*.

​
Reaching AI resources

Use the typed /api/* endpoints. Almost all of them require the Service Role (Secret) Key. A signed-in user’s JWT from the project’s GoTrue works only on the conversation routes: the user’s own agent and orchestration sessions, runs on them, and approvals of their own paused runs. The full list is in Which key for which route. Per-user scoping on those conversation routes is enforced in application code:
  • Reading a session, its messages or its runs returns 404 unless the caller owns the session.
  • A run continues only an existing session that belongs to the caller, and an end user can’t name a new session id.
  • Session listings are scoped to the caller.
  • An end user’s run uses the knowledge bases configured on the agent; it can’t name other knowledge bases or stored context.
Service Role callers bypass these checks. Knowledge bases, knowledge-base search, sources, agent configuration and workflows answer an end user’s token with 403.
Multi-user projects: AI resources are project-wide.Every knowledge base, agent and workflow in a project is visible to anything holding the Service Role key, and an agent’s configured knowledge bases are searched the same way for every user who talks to it. If end users shouldn’t see each other’s documents or search results, enforce that in your backend (for example, one knowledge base per tenant, or tenant filters your backend adds to every search). For hard isolation between customers, give each customer its own project.

​
Your own tables

Tables you create in public work the normal way: PostgREST exposes them at /rest/v1/* and Row Level Security with auth.uid() / auth.jwt() protects them. See the RLS Model page and the RLS Cookbook.

​
Tables in the ai schema

For reference, the main tables: The schema grows as the platform adds features. Treat it as the platform’s internal storage, not a stable API.

​
Next steps

Agents Reference

The typed endpoints for agents, runs and sessions.

Knowledge Bases Reference

The typed endpoints for knowledge bases, indexing and search.

RLS Model

How roles, JWT claims, and auth.uid() compose to gate access to your own tables.

Database Access

The ways into your project’s Postgres: typed API, PostgREST, direct connection.