api

147 notes in this subject, read out of this brain and free to use. This is page 3 of 3.

Connection logging Management API endpoints

The Management API provides endpoints to manage connection logging. GET https://api.supabase.com/v1/projects/{PROJECT_REF}/config/database/postgres retrieves the current Postgres config. PUT https://api.supabase.com/v1/projects/{PROJECT_REF}/config/database/postgres updates the config. Both endpoints require Authorization header with Bearer token.

Manage SSL enforcement via Management API

SSL enforcement can be managed using the Management API endpoints. To get current SSL enforcement status, send a GET request to https://api.supabase.com/v1/projects/{PROJECT_REF}/ssl-enforcement with Authorization header. To enable SSL enforcement, send a PUT request to the same endpoint with Content-Type: application/json and body containing requestedConfig.database set to true. To disable, set requestedConfig.database to false. Both PUT operations require a valid Management API access token.

Read Replica deletion API example

Delete a Read Replica using the Management API by POSTing to the remove endpoint with the database identifier: `curl -X POST "https://api.supabase.com/v1/projects/$PROJECT_REF/read-replicas/remove" -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN" -H "Content-Type: application/json" -d '{"database_identifier": "abcdefghijklmnopqrst"}'`

Read Replica creation API example

Create a Read Replica using the Management API by first exporting access token and project reference: `export SUPABASE_ACCESS_TOKEN="your-access-token"` and `export PROJECT_REF="your-project-ref"`. Then POST to the setup endpoint: `curl -X POST "https://api.supabase.com/v1/projects/$PROJECT_REF/read-replicas/setup" -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN" -H "Content-Type: application/json" -d '{"read_replica_region": "us-east-1"}'`

Creating Read Replicas via Management API

Read Replicas can be managed using the Management API (beta functionality). To create a new Read Replica, make a POST request to `https://api.supabase.com/v1/projects/{PROJECT_REF}/read-replicas/setup` with Authorization Bearer token and specify the `read_replica_region` in JSON body (e.g., 'us-east-1'). To delete a Read Replica, make a POST request to `https://api.supabase.com/v1/projects/{PROJECT_REF}/read-replicas/remove` with the `database_identifier` in the JSON body.

Queue API permissions required by operation

The permissions required for pgmq_public database functions by operation are: send and send_batch require Select and Insert; read and pop require Select and Update; archive and delete require Select and Delete.

Example: recommended pattern for database errors

const { data, error } = await supabase.from('users').select(); if (error) { console.error(error); if (error.code === '42501') { // Permission denied. error.hint usually contains the GRANT to run. } return; }

Example: Auth error handling

const { data, error } = await supabase.auth.signInWithPassword({ email: 'example@email.com', password: 'exa••••••rd', }); if (error) { console.error(error); return; }

Example: Realtime error handling

supabase.channel('room1').subscribe((status, err) => { if (status === 'CHANNEL_ERROR' || status === 'TIMED_OUT') { console.error(status, err); } });

supabase-js returns { data, error } pair instead of throwing

Every supabase-js call returns a { data, error } pair instead of throwing exceptions. When something fails, check the error object.

Always log error.hint first for Postgres errors

The single most useful field on a supabase-js error object is usually hint. Postgres returns the fix in the hint field, not only a description of the problem. Logging only error.message hides the hint. Always log the full error object, not only error.message.

PostgrestError fields ordered by usefulness

Database calls (select, insert, update, upsert, delete, rpc) return a PostgrestError with four fields, in order of usefulness: 1) hint - Always check first; when Postgres includes one, it's the actionable fix (a GRANT to run, a column name, a type). 2) code - When branching in code; codes are stable across versions while message text isn't. 3) details - When hint and message aren't enough; often contains the offending value, key, or row. 4) message - As the human summary; useful in UI strings, less useful for debugging.

Branch on error.code not error.message

Use error.code for programmatic branching instead of error.message. Error codes are stable across Postgres and PostgREST versions, but message text changes between versions.

PostgrestError response structure

A PostgrestError response body contains: code (string, e.g. '42501'), message (string describing the error reason), details (null or object with additional context), and hint (string with the SQL fix or actionable solution when available).

Example: handling permission denied error with hint

When a permission denied error occurs on a table, the error object contains: message 'permission denied for table users' and hint 'Grant the required privileges to the current role with: GRANT SELECT ON public.users TO anon;'. The hint contains the exact SQL statement to run in the dashboard SQL editor to fix it.

Recommended pattern for handling supabase-js errors

Read { data, error } from the response, check if error exists, log the whole error object, and return early. Example: const { data, error } = await supabase.from('users').select(); if (error) { console.error(error); return; }

AuthError fields

AuthError exposes error.code (e.g. 'invalid_credentials', 'email_not_confirmed') and error.status. Branch on code; log the whole error object.

Realtime subscribe callback error handling

The subscribe() callback receives a status and, on failure, an err argument. Log the whole err object — its cause field often holds the underlying reason. Check for status values 'CHANNEL_ERROR' or 'TIMED_OUT' to detect subscription failures.

Enable IPv4 add-on via Management API

To enable the IPv4 add-on using the Management API, send a PATCH request to https://api.supabase.com/v1/projects/$PROJECT_REF/billing/addons with addon_variant: "ipv4_default" and addon_type: "ipv4". Requires Authorization header with Bearer token.

Get IPv4 add-on status via Management API

To check current IPv4 add-on status, send a GET request to https://api.supabase.com/v1/projects/$PROJECT_REF/billing/addons with Authorization header containing Bearer token.

Disable IPv4 add-on via Management API

To disable the IPv4 add-on using the Management API, send a DELETE request to https://api.supabase.com/v1/projects/$PROJECT_REF/billing/addons/ipv4_default with Authorization header containing Bearer token.

Create new projects via Management API

Use the /v1/projects endpoint in the Management API to create new projects. When creating a project, either ask the user for a database password or generate a secure password, then securely store it to construct the Postgres URI.

Management API authentication with OAuth token

Use the supabase-management-js library for JavaScript/TypeScript to authenticate with the Management API: instantiate SupabaseManagementAPI with the accessToken parameter set to the OAuth access token obtained from the token endpoint.

Retrieve project API credentials via Management API

Use the /projects/{ref}/api-keys endpoint in the Management API to retrieve a project's API credentials, useful for integrations that want to provide convenient access to API URLs and keys.

Supabase CLI installation for type generation

The Supabase CLI can be installed via npm for type generation. The minimum required version is v2.66.0. Install with: npm i supabase --save-dev You can also install a specific minimum version with: npm i supabase@">=1.8.1" --save-dev

Manage connection logging via Management API

To manage connection logging using the Management API, send a PUT request to https://api.supabase.com/v1/projects/{PROJECT_REF}/config/database/postgres with an Authorization header containing a Bearer token. Set the JSON body to: - {"log_connections": true} to enable connection logging - {"log_connections": false} to disable connection logging

Find API credentials

Serverless API URL and publishable keys are available on the dashboard at /dashboard/project/_/settings/api.

Give your agent this brain