Supabase

Troubleshooting

If requests fail, run zero doctor check-connector --env-name SUPABASE_TOKEN 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_TOKEN"

2. Select Specific Columns

Get only specific columns:

curl -s "$SUPABASE_URL/rest/v1/users?select=id,name,email" -H "apikey: $SUPABASE_TOKEN"

3. Filter with Operators

Filter rows using PostgREST operators.

Equal to:

curl -s "$SUPABASE_URL/rest/v1/users?status=eq.active" -H "apikey: $SUPABASE_TOKEN"

Greater than:

curl -s "$SUPABASE_URL/rest/v1/products?price=gt.100" -H "apikey: $SUPABASE_TOKEN"

Multiple conditions (AND):

curl -s "$SUPABASE_URL/rest/v1/users?age=gte.18&status=eq.active" -H "apikey: $SUPABASE_TOKEN"

Available Operators:

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_TOKEN"

5. Ordering

Sort results.

Ascending:

curl -s "$SUPABASE_URL/rest/v1/users?order=created_at.asc" -H "apikey: $SUPABASE_TOKEN"

Descending:

curl -s "$SUPABASE_URL/rest/v1/users?order=created_at.desc" -H "apikey: $SUPABASE_TOKEN"

Multiple columns:

curl -s "$SUPABASE_URL/rest/v1/users?order=status.asc,created_at.desc" -H "apikey: $SUPABASE_TOKEN"

6. Pagination

Use limit and offset.

First 10 rows:

curl -s "$SUPABASE_URL/rest/v1/users?limit=10" -H "apikey: $SUPABASE_TOKEN"

Page 2 (rows 11-20):

curl -s "$SUPABASE_URL/rest/v1/users?limit=10&offset=10" -H "apikey: $SUPABASE_TOKEN"

7. Get Row Count

Use Prefer: count=exact header:

curl -s "$SUPABASE_URL/rest/v1/users?select=*" -H "apikey: $SUPABASE_TOKEN" -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.json

9. 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.json

10. 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.json

11. 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.json

12. 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_TOKEN"

Get users with their posts:

curl -s "$SUPABASE_URL/rest/v1/users?select=*,posts(*)" -H "apikey: $SUPABASE_TOKEN"

14. Full-Text Search

Search text columns:

curl -s "$SUPABASE_URL/rest/v1/posts?title=fts.hello" -H "apikey: $SUPABASE_TOKEN"

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.json

Response Headers

Guidelines

1. Use publishable key for read operations with RLS enabled 2. Use secret key only server-side for write operations or admin access 3. Enable RLS on tables for security when using publishable key 4. Use `select` to limit returned columns for better performance 5. Add indexes on frequently filtered columns 6. Use `Prefer: return=representation` to get inserted/updated rows back 7. 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