ドキュメント · リファレンス

プロジェクト API

プロジェクトごとに専用のアドレスがあり、supabase-js がそのまま接続します。下のルートはすべて、サーバーのルーターとテストで照合している一覧です。

アドレスとキー

プロジェクトのアドレスは https://<ref>.<zone> です。リクエストごとに apikey ヘッダー（または Authorization: Bearer）でキーを送ります。公開キー（publishable）はブラウザー用で、アクセスルール（RLS）に従います。シークレットキー（secret）はすべてのルールを迂回するため、サーバーでだけ使います。ログインしたユーザーのトークンを Authorization: Bearer で送ると、そのユーザーとして実行されます。キーはAPI キー画面にあります。

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

supabase-js との互換性

パス、クエリ、ヘッダー、レスポンスの形が Supabase と同じなので、@supabase/supabase-js をそのまま使えます。変えるのはアドレスとキーだけです。各表の supabase-js 列は、そのルートを呼び出す関数です。

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

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

データ（/rest/v1）

PostgREST と同じクエリ言語です。テーブル名がパスで、列名がクエリパラメーターです。すべてのリクエストは、呼び出した人のロールとアクセスルール（RLS）で実行されます。

クエリパラメーター

フィルター演算子

次の演算子だけを受け付けます。知らない演算子は黙って無視せず、拒否します。先頭に not. を付けると否定になります。

ヘッダー

関数の呼び出し（rpc）

/rest/v1/rpc/<関数> は、プロジェクトのスキーマにある SQL 関数を呼び出した人のロールで実行します。POST では本文が引数です。GET では関数の引数と同じ名前のクエリパラメーターが引数になり、残りは結果へのフィルターです。

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"

未対応のもの

• 集計（count()、sum() など）とスプレッド（...rel(*)）の select
• public 以外のスキーマ
• 一度に 1000 行を超える読み取り（limit は 1000 で切り詰められます）

認証（/auth/v1）

GoTrue と同じパスとレスポンスです。メールとパスワード、マジックリンク、匿名ログイン、ソーシャルログイン（PKCE を含む）、TOTP による二段階認証、シークレットキーによるユーザー管理に対応しています。

トークンの発行（grant_type）: password、refresh_token、pkce、id_token（Google と Apple の ID トークン）。

ソーシャルログインのプロバイダー: 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。設定はコンソールか、管理 API の 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()

未対応のもの

• TOTP 以外の二段階認証（WebAuthn、電話）
• 再認証（reauthenticate）と ID の連携（linkIdentity）。連携の解除だけに対応しています
• auth.admin.inviteUserByEmail。代わりに generateLink({ type: 'invite' }) を使います

ストレージ（/storage/v1）

Supabase Storage と同じパスです。ファイルの記録はプロジェクトのテーブルにあるため、誰がファイルを読み書きできるかは、そのテーブルのアクセスルールが決めます。

ファイル 1 つは既定で 50MB まで受け付けます（バケットごとにより低く設定できます）。署名付き URL は最長 7 日、アップロード用の署名付き URL は 2 時間有効です。バケット名には小文字、数字、.、_、- を使います。

アップロードは、本文そのまま（Content-Type がファイルの形式）か multipart/form-data で送ります。POST は同じ名前があれば拒否し（x-upsert: true なら上書き）、PUT は上書きします。

画像の変換

/render/image/{public|authenticated|sign}/<バケット>/<パス> にクエリで指定します。画像変換サーバーがない環境では元の画像をそのまま返し、x-blackwall-transform ヘッダーで知らせます。

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)

未対応のもの

• ファイルごとのキャッシュ設定（cacheControl オプション）は保存しません

リアルタイム（/realtime/v1）

wss://<ref>.<zone>/realtime/v1/websocket?apikey=<キー>&vsn=1.0.0 は Phoenix チャネル（supabase-js が使うもの）です。vsn=2.0.0 は配列形式のメッセージとバイナリのブロードキャストです。/realtime/v1（websocket なし）は同じ機能のシンプルな JSON プロトコルです。

チャネルのトピックは realtime:<名前> です。同じ名前に参加したクライアント同士で、ブロードキャストとプレゼンスを共有します。

クライアントが送るイベント

サーバーが送るイベント

postgres_changes は、コンソールか set_realtime でリアルタイムを有効にしたテーブルからだけ届きます。各行は受け取る人のアクセスルールで確認してから送られます。フィルターは 列=eq|neq|lt|lte|gt|gte|in.値 です。

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

未対応のもの

• 非公開チャネル（config.private: true）
• UPDATE の変更前の値（old は空です）

関数（/functions/v1）

/functions/v1/<名前> はデプロイした関数を呼び出します。すべての HTTP メソッドをそのまま渡し、本文は 2MB までです。非公開（既定）の関数には、このプロジェクトのキーが必要です: 公開キー（anon）、ログインしたユーザーのトークン（authenticated）、シークレットキー（service_role）。公開としてデプロイした関数はキーなしで呼び出せます。関数にはトークンではなく、検証済みのクレームが渡されます。名前は小文字で始まり、小文字、数字、- を使います。

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"}'

そのほかのルート

エラー

エラーは、ルートごとに Supabase のクライアントが読む形のままです。データは PostgREST と同じく code（PGRST…）、message、details、hint、認証は GoTrue と同じく code、error_code、msg（トークン発行では OAuth の error、error_description も）、ストレージは storage-js と同じく statusCode、error、message です。メッセージは Accept-Language（韓国語、英語、日本語）に従います。

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