Docs · Reference

Project API

Each project has its own address, and supabase-js connects to it unchanged. Every route below is a list held to the server’s router by a test.

Address and keys

A project lives at https://<ref>.<zone>. Send a key with every request in the apikey header (or Authorization: Bearer). The publishable key is for browsers and follows the access rules (RLS). The secret key bypasses every rule, so use it only on a server. A signed-in user’s token in Authorization: Bearer runs the request as that user. The keys are on the API keys screen.

curl "https://abcdefghijklmnopqrst.end.blackall.ai/rest/v1/notes?select=id,title" \
  -H "apikey: <publishable key>"

supabase-js compatibility

Paths, query strings, headers and responses are Supabase’s, so @supabase/supabase-js works as it is: change only the address and the key. The supabase-js column of each table is the call that reaches that route.

import { createClient } from '@supabase/supabase-js'

const supabase = createClient('https://abcdefghijklmnopqrst.end.blackall.ai', '<publishable key>')

Data (/rest/v1)

The PostgREST query language. The table name is the path and column names are query parameters. Every request runs with the caller’s role and the access rules (RLS).

Query parameters

Filter operators

Only these operators are accepted. An unknown one is refused, not silently ignored. Prefix any of them with not. to negate it.

Headers

Calling functions (rpc)

/rest/v1/rpc/<function> runs a SQL function in the project schema with the caller’s role. With POST the body is the arguments; with GET, query parameters named like an argument are arguments and the rest filter the result.

const { data, error } = await supabase
  .from('notes')
  .select('id, title, author(name)')
  .eq('done', false)
  .order('created_at', { ascending: false })
  .range(0, 19)

await supabase.from('notes').insert({ title: 'Hello' }).select().single()
await supabase.rpc('search_notes', { query: 'hello' })

curl "https://abcdefghijklmnopqrst.end.blackall.ai/rest/v1/notes?select=id,title&done=eq.false&order=created_at.desc&limit=20" \
  -H "apikey: <publishable key>" \
  -H "Prefer: count=exact"

Not supported

• Aggregate (count(), sum() and so on) and spread (...rel(*)) selects
• Schemas other than public
• Reading more than 1000 rows at once (limit is capped at 1000)

Auth (/auth/v1)

GoTrue’s paths and responses. Email and password, magic links, anonymous sign-in, social sign-in (with PKCE), TOTP two-factor authentication and user management with the secret key.

Token grants (grant_type): password, refresh_token, pkce, id_token (an ID token from Google or Apple).

Social sign-in providers: google, kakao, naver, apple, github, gitlab, microsoft, facebook, line, discord, x, bitbucket, figma, linkedin_oidc, notion, twitch, slack_oidc, spotify, zoom, azure, keycloak, workos, twitter, slack. Configure them in the console or with the management API’s set_auth_provider.

await supabase.auth.signUp({ email: '[email protected]', password: 'a-long-passphrase' })
await supabase.auth.signInWithPassword({ email: '[email protected]', password: 'a-long-passphrase' })
await supabase.auth.signInWithOAuth({ provider: 'google', options: { redirectTo: 'https://app.example.com' } })
const { data: { user } } = await supabase.auth.getUser()

Not supported

• Second factors other than TOTP (WebAuthn, phone)
• Reauthentication (reauthenticate) and linking an identity (linkIdentity); only unlinking is supported
• auth.admin.inviteUserByEmail; use generateLink({ type: 'invite' }) instead

Storage (/storage/v1)

Supabase Storage’s paths. Files are recorded in a table of the project, so the access rules on that table decide who may read and write each file.

A file is accepted up to 50MB by default (a bucket can set a lower limit). A signed URL lasts at most 7 days, and a signed upload URL two hours. Bucket names use lowercase letters, digits, ., _ and -.

Upload the file as the body (with its Content-Type) or as multipart/form-data. POST refuses an existing name unless x-upsert: true; PUT replaces.

Image transformation

Pass the options as query parameters to /render/image/{public|authenticated|sign}/<bucket>/<path>. A server without an image transformer serves the original and says so in the x-blackwall-transform header.

const bucket = supabase.storage.from('avatars')
await bucket.upload('me.png', file, { upsert: true })
const { data } = bucket.getPublicUrl('me.png', { transform: { width: 200, height: 200 } })
const { data: signed } = await bucket.createSignedUrl('me.png', 3600)

Not supported

• A per-file cache setting (the cacheControl option) is not stored

Realtime (/realtime/v1)

wss://<ref>.<zone>/realtime/v1/websocket?apikey=<key>&vsn=1.0.0 speaks Phoenix channels, which is what supabase-js uses. vsn=2.0.0 uses array messages and binary broadcasts. /realtime/v1 (without websocket) is a plain JSON protocol for the same features.

A channel’s topic is realtime:<name>. Clients that join the same name share broadcasts and presence.

Events a client sends

Events the server sends

postgres_changes arrive only from tables with realtime turned on in the console or with set_realtime. Each row is checked against the receiver’s access rules before it is sent. Filters are column=eq|neq|lt|lte|gt|gte|in.value.

supabase
  .channel('room-1')
  .on('broadcast', { event: 'cursor' }, ({ payload }) => console.log(payload))
  .on('presence', { event: 'sync' }, () => console.log('online'))
  .on('postgres_changes', { event: 'INSERT', schema: 'public', table: 'notes', filter: 'done=eq.false' }, (change) => console.log(change.new))
  .subscribe()

wss://abcdefghijklmnopqrst.end.blackall.ai/realtime/v1/websocket?apikey=<publishable key>&vsn=1.0.0

{"topic":"realtime:room-1","event":"phx_join","payload":{"config":{"broadcast":{"self":false},"presence":{"key":"me"},"postgres_changes":[{"event":"*","schema":"public","table":"notes"}]}},"ref":"1","join_ref":"1"}
{"topic":"realtime:room-1","event":"broadcast","payload":{"type":"broadcast","event":"cursor","payload":{"x":1}},"ref":"2","join_ref":"1"}
{"topic":"phoenix","event":"heartbeat","payload":{},"ref":"3"}

Not supported

• Private channels (config.private: true)
• The previous values of an UPDATE (old is empty)

Functions (/functions/v1)

/functions/v1/<name> calls a deployed function. Every HTTP method is passed through, and the body may be up to 2MB. A private function (the default) needs a key of this project: the publishable key (anon), a signed-in user's token (authenticated) or the secret key (service_role). A function deployed as public can be called with no key. The function receives the verified claims, never the token. Names start with a lowercase letter and use lowercase letters, digits and -.

const { data, error } = await supabase.functions.invoke('hello', { body: { name: 'world' } })

curl -X POST "https://abcdefghijklmnopqrst.end.blackall.ai/functions/v1/hello" \
  -H "Authorization: Bearer <user token or secret key>" \
  -H "content-type: application/json" \
  -d '{"name":"world"}'

Other routes

Errors

Errors have the shape each Supabase client reads on that route. Data errors are PostgREST’s: code (PGRST…), message, details, hint. Auth errors are GoTrue’s: code, error_code, msg (and OAuth’s error and error_description from the token endpoint). Storage errors are storage-js’s: statusCode, error, message. Messages follow Accept-Language (Korean, English, Japanese).

{ "code": "PGRST116", "message": "…", "hint": null, "details": "…" }