Troubleshooting
If requests fail, run zero doctor check-connector --env-name SUPABASE_PUBLISHABLE_KEY or zero doctor check-connector --url https://your-project.supabase.co/rest/v1/ --method GET
How to Use
Base URL: ${SUPABASE_URL}/rest/v1
All requests require the apikey header with your API key.
1. Read All Rows
Get all rows from a table:
curl -s "$SUPABASE_URL/rest/v1/users?select=*" -H "apikey: $SUPABASE_PUBLISHABLE_KEY"2. Select Specific Columns
Get only specific columns:
curl -s "$SUPABASE_URL/rest/v1/users?select=id,name,email" -H "apikey: $SUPABASE_PUBLISHABLE_KEY"3. Filter with Operators
Filter rows using PostgREST operators.
Equal to:
curl -s "$SUPABASE_URL/rest/v1/users?status=eq.active" -H "apikey: $SUPABASE_PUBLISHABLE_KEY"Greater than:
curl -s "$SUPABASE_URL/rest/v1/products?price=gt.100" -H "apikey: $SUPABASE_PUBLISHABLE_KEY"Multiple conditions (AND):
curl -s "$SUPABASE_URL/rest/v1/users?age=gte.18&status=eq.active" -H "apikey: $SUPABASE_PUBLISHABLE_KEY"Available Operators:
| Operator | Meaning | Example |
|---|---|---|
eq | Equals | ?status=eq.active |
neq | Not equals | ?status=neq.deleted |
gt | Greater than | ?age=gt.18 |
gte | Greater than or equal | ?age=gte.21 |
lt | Less than | ?price=lt.100 |
lte | Less than or equal | ?price=lte.50 |
like | Pattern match (use * for %) | ?name=like.*john* |
ilike | Case-insensitive pattern | ?name=ilike.*john* |
in | In list | ?id=in.(1,2,3) |
is | Is null/true/false | ?deleted_at=is.null |
4. OR Conditions
Use or for OR logic:
curl -s "$SUPABASE_URL/rest/v1/users?or=(status.eq.active,status.eq.pending)" -H "apikey: $SUPABASE_PUBLISHABLE_KEY"5. Ordering
Sort results.
Ascending:
curl -s "$SUPABASE_URL/rest/v1/users?order=created_at.asc" -H "apikey: $SUPABASE_PUBLISHABLE_KEY"Descending:
curl -s "$SUPABASE_URL/rest/v1/users?order=created_at.desc" -H "apikey: $SUPABASE_PUBLISHABLE_KEY"Multiple columns:
curl -s "$SUPABASE_URL/rest/v1/users?order=status.asc,created_at.desc" -H "apikey: $SUPABASE_PUBLISHABLE_KEY"6. Pagination
Use limit and offset.
First 10 rows:
curl -s "$SUPABASE_URL/rest/v1/users?limit=10" -H "apikey: $SUPABASE_PUBLISHABLE_KEY"Page 2 (rows 11-20):
curl -s "$SUPABASE_URL/rest/v1/users?limit=10&offset=10" -H "apikey: $SUPABASE_PUBLISHABLE_KEY"7. Get Row Count
Use Prefer: count=exact header:
curl -s "$SUPABASE_URL/rest/v1/users?select=*" -H "apikey: $SUPABASE_PUBLISHABLE_KEY" -H "Prefer: count=exact" -I | grep -i "content-range"8. Insert Single Row
Write to /tmp/supabase_request.json:
{
"name": "John Doe",
"email": "john@example.com"
}Then run:
curl -s -X POST "$SUPABASE_URL/rest/v1/users" -H "apikey: $SUPABASE_TOKEN" -H "Content-Type: application/json" -H "Prefer: return=representation" -d @/tmp/supabase_request.json9. Insert Multiple Rows
Write to /tmp/supabase_request.json:
[
{"name": "John", "email": "john@example.com"},
{"name": "Jane", "email": "jane@example.com"}
]Then run:
curl -s -X POST "$SUPABASE_URL/rest/v1/users" -H "apikey: $SUPABASE_TOKEN" -H "Content-Type: application/json" -H "Prefer: return=representation" -d @/tmp/supabase_request.json10. Update Rows
Update rows matching a filter.
Write to /tmp/supabase_request.json:
{
"status": "inactive"
}Then run:
curl -s -X PATCH "$SUPABASE_URL/rest/v1/users?id=eq.1" -H "apikey: $SUPABASE_TOKEN" -H "Content-Type: application/json" -H "Prefer: return=representation" -d @/tmp/supabase_request.json11. Upsert (Insert or Update)
Use Prefer: resolution=merge-duplicates.
Write to /tmp/supabase_request.json:
{
"id": 1,
"name": "John Updated",
"email": "john@example.com"
}Then run:
curl -s -X POST "$SUPABASE_URL/rest/v1/users" -H "apikey: $SUPABASE_TOKEN" -H "Content-Type: application/json" -H "Prefer: resolution=merge-duplicates,return=representation" -d @/tmp/supabase_request.json12. Delete Rows
Delete rows matching a filter:
curl -s -X DELETE "$SUPABASE_URL/rest/v1/users?id=eq.1" -H "apikey: $SUPABASE_TOKEN" -H "Prefer: return=representation"13. Query Related Tables
Embed related data using foreign keys.
Get posts with their author:
curl -s "$SUPABASE_URL/rest/v1/posts?select=*,author:users(*)" -H "apikey: $SUPABASE_PUBLISHABLE_KEY"Get users with their posts:
curl -s "$SUPABASE_URL/rest/v1/users?select=*,posts(*)" -H "apikey: $SUPABASE_PUBLISHABLE_KEY"14. Full-Text Search
Search text columns:
curl -s "$SUPABASE_URL/rest/v1/posts?title=fts.hello" -H "apikey: $SUPABASE_PUBLISHABLE_KEY"15. Call RPC Functions
Call PostgreSQL functions.
Write to /tmp/supabase_request.json:
{
"param1": "value1"
}Then run:
curl -s -X POST "$SUPABASE_URL/rest/v1/rpc/my_function" -H "apikey: $SUPABASE_TOKEN" -H "Content-Type: application/json" -d @/tmp/supabase_request.jsonResponse Headers
| Header | Description |
|---|---|
Content-Range | Row range and total count (e.g., 0-9/100) |
Preference-Applied | Confirms applied preferences |
Guidelines
- Use publishable key for read operations with RLS enabled
- Use secret key only server-side for write operations or admin access
- Enable RLS on tables for security when using publishable key
- Use
selectto limit returned columns for better performance - Add indexes on frequently filtered columns
- Use
Prefer: return=representationto get inserted/updated rows back - Avoid full-table operations without filters to prevent accidental data loss
API Reference
- Supabase API Docs: https://supabase.com/docs/guides/api
- API Keys Guide: https://supabase.com/docs/guides/api/api-keys
- PostgREST Docs: https://postgrest.org/en/stable/
- API Settings: https://supabase.com/dashboard/project/_/settings/api-keys