Three Ways In
The Project Service API (/api/) manages the ai schema — sources, knowledge bases, agents, and all other platform-managed data. You interact with this data through structured endpoints. PostgREST (/rest/v1/) gives you direct RESTful access to the public schema where your application tables live. And the Database URL is a standard Postgres connection string — drop it into psql, pg, psycopg2, JDBC, SQLAlchemy, or any tool that speaks the Postgres wire protocol for migrations, dashboards, or one-off queries. All three need credentials, and all three credentials live in the same place: open the Connect modal in the Studio by clicking the Connect button in the project header (or append ?showConnect=true to any project URL). The “API Keys” tab gives you Project URL, Anon (Publishable) Key, Service Role (Secret) Key, JWT Secret, and Database URL; the “Connection Strings” tab ships ready-to-paste Postgres snippets in nine formats (URI, PSQL, Node.js, Python, Golang, JDBC, .NET, PHP, SQLAlchemy).AI Schema (Managed)
The ai schema is fully managed by the platform. It contains tables for sources, page_texts, knowledge_bases, chunks (with pgvector embeddings), agents, tool_assignments, sessions, messages, runs, orchestrations, workflows, and more. You should never modify these tables directly — use the Project Service API instead.Public Schema (Your Tables)
The public schema is yours. Create tables, define relationships, and add indexes as needed. PostgREST automatically exposes all public schema tables as REST endpoints. You can read, insert, update, and delete rows using standard HTTP methods with powerful filtering operators.Row Level Security
PostgREST respects Row Level Security (RLS) policies on your tables. The Service Role (Secret) Key bypasses RLS entirely — use it only server-side. The Anon (Publishable) Key respects RLS policies, so users only see rows they’re authorized to access. This is the recommended pattern for client-side applications.Direct Postgres Connection
When you need raw SQL — running migrations, hooking up a BI tool, importing a CSV, or wiring an ORM — connect directly to Postgres using the Database URL from the Connect modal. The URL embeds host, port, database, user, and password; treat it like a credential and keep it server-side. The “Connection Strings” tab generates the equivalent snippet for psql, Node.js (pg), Python (psycopg2), Go (database/sql), JDBC, .NET, PHP, and SQLAlchemy so you don’t have to hand-assemble DSNs.| Use case | Best surface | Key from Connect modal |
|---|---|---|
| AI workflows (sources, KBs, agents, …) | /api/* (Project Service API) | Service Role (Secret) Key |
| Server-side CRUD on your tables | /rest/v1/* (PostgREST) | Service Role (Secret) Key |
| Client-side CRUD under RLS | /rest/v1/* (PostgREST) | Anon (Publishable) Key |
| Migrations, BI tools, ORMs, psql | Postgres wire protocol | Database URL |
| Verifying user-signed JWTs server-side | Your own service | JWT Secret |
PostgREST Operators
| Operator | Example | Description |
|---|---|---|
| eq | ?status=eq.active | Equal to |
| neq | ?status=neq.deleted | Not equal to |
| gt | ?age=gt.18 | Greater than |
| gte | ?age=gte.18 | Greater than or equal |
| lt | ?price=lt.100 | Less than |
| lte | ?price=lte.100 | Less than or equal |
| like | ?name=like.Smith | Pattern match (case-sensitive) |
| ilike | ?name=ilike.smith | Pattern match (case-insensitive) |
| is | ?deleted_at=is.null | IS check (null, true, false) |
| in | ?id=in.(1,2,3) | In a list of values |
Next Steps
Database (PostgREST) Reference
Auto-generated CRUD docs for your public tables.
Auth & Storage Reference
Manage users and files via GoTrue and Storage APIs.
Architecture
Understand the database schema layout.