---

name: supabase-api description: Supabase JavaScript client API and REST API usage. Use when integrating Supabase, setting up clients, or using REST endpoints directly.

Supabase API Skill

JavaScript client and REST API reference.

Installation

Copynpm install @supabase/supabase-js

Client Initialization

Browser Client

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

const supabase = createClient(
  'https://your-project.supabase.co',
  'your-anon-key'
)

With TypeScript Types

Copyimport { createClient } from '@supabase/supabase-js'
import { Database } from './database.types'

const supabase = createClient<Database>(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
)

Server Client (Service Role)

Copyconst supabaseAdmin = createClient(
  process.env.SUPABASE_URL,
  process.env.SUPABASE_SERVICE_ROLE_KEY,
  {
    auth: {
      autoRefreshToken: false,
      persistSession: false
    }
  }
)

Custom Options

Copyconst supabase = createClient(url, key, {
  auth: {
    persistSession: true,
    autoRefreshToken: true,
    storage: localStorage,
    storageKey: 'supabase-auth'
  },
  global: {
    headers: { 'x-custom-header': 'value' }
  },
  db: {
    schema: 'public'
  },
  realtime: {
    params: {
      eventsPerSecond: 10
    }
  }
})

REST API Direct

API URL Format

Copyhttps://<project-ref>.supabase.co/rest/v1/<table>

Headers

Copyconst headers = {
  'apikey': 'your-anon-key',
  'Authorization': 'Bearer your-anon-key',
  'Content-Type': 'application/json',
  'Prefer': 'return=representation'  // Return data after mutation
}

Select (GET)

Copy# All rows
curl 'https://xxx.supabase.co/rest/v1/users' \
  -H "apikey: $SUPABASE_KEY" \
  -H "Authorization: Bearer $SUPABASE_KEY"

# Specific columns
curl 'https://xxx.supabase.co/rest/v1/users?select=id,name,email' \
  -H "apikey: $SUPABASE_KEY"

# With filter
curl 'https://xxx.supabase.co/rest/v1/users?status=eq.active' \
  -H "apikey: $SUPABASE_KEY"

# With pagination (query params)
curl 'https://xxx.supabase.co/rest/v1/users?limit=10&offset=0' \
  -H "apikey: $SUPABASE_KEY"

# With pagination (Range header - alternative)
curl 'https://xxx.supabase.co/rest/v1/users' \
  -H "apikey: $SUPABASE_KEY" \
  -H "Range: 0-9"

# With ordering
curl 'https://xxx.supabase.co/rest/v1/users?order=created_at.desc' \
  -H "apikey: $SUPABASE_KEY"

# Get count with results
curl 'https://xxx.supabase.co/rest/v1/users?select=*' \
  -H "apikey: $SUPABASE_KEY" \
  -H "Prefer: count=exact"

Insert (POST)

Copycurl -X POST 'https://xxx.supabase.co/rest/v1/users' \
  -H "apikey: $SUPABASE_KEY" \
  -H "Authorization: Bearer $SUPABASE_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: return=representation" \
  -d '{"name": "John", "email": "john@example.com"}'

Update (PATCH)

Copycurl -X PATCH 'https://xxx.supabase.co/rest/v1/users?id=eq.123' \
  -H "apikey: $SUPABASE_KEY" \
  -H "Authorization: Bearer $SUPABASE_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: return=representation" \
  -d '{"name": "John Doe"}'

Upsert (POST with Resolution)

Copycurl -X POST 'https://xxx.supabase.co/rest/v1/users' \
  -H "apikey: $SUPABASE_KEY" \
  -H "Authorization: Bearer $SUPABASE_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: return=representation,resolution=merge-duplicates" \
  -d '{"id": 123, "name": "John"}'

Delete (DELETE)

Copycurl -X DELETE 'https://xxx.supabase.co/rest/v1/users?id=eq.123' \
  -H "apikey: $SUPABASE_KEY" \
  -H "Authorization: Bearer $SUPABASE_KEY"

Filter Operators (REST)

JavaScript Client Quick Reference

Database Operations

Copy// Select
const { data, error } = await supabase.from('table').select('*')

// Select with filter
const { data } = await supabase.from('table').select('*').eq('id', 1)

// Insert
const { data } = await supabase.from('table').insert({ col: 'value' }).select()

// Update
const { data } = await supabase.from('table').update({ col: 'new' }).eq('id', 1)

// Upsert
const { data } = await supabase.from('table').upsert({ id: 1, col: 'value' })

// Delete
const { error } = await supabase.from('table').delete().eq('id', 1)

// RPC (function call)
const { data } = await supabase.rpc('function_name', { param: 'value' })

Auth Operations

Copy// Sign up
await supabase.auth.signUp({ email, password })

// Sign in
await supabase.auth.signInWithPassword({ email, password })

// Sign out
await supabase.auth.signOut()

// Get user
const { data: { user } } = await supabase.auth.getUser()

// Get session
const { data: { session } } = await supabase.auth.getSession()

// Auth state listener
supabase.auth.onAuthStateChange((event, session) => { })

Storage Operations

Copy// Upload
await supabase.storage.from('bucket').upload('path', file)

// Download
const { data } = await supabase.storage.from('bucket').download('path')

// Get public URL
const { data } = supabase.storage.from('bucket').getPublicUrl('path')

// Get signed URL
const { data } = await supabase.storage.from('bucket').createSignedUrl('path', 3600)

// Delete
await supabase.storage.from('bucket').remove(['path'])

// List
const { data } = await supabase.storage.from('bucket').list('folder')

Realtime Operations

Copy// Subscribe to database changes
const channel = supabase
  .channel('changes')
  .on('postgres_changes', { event: '*', schema: 'public', table: 'posts' }, callback)
  .subscribe()

// Broadcast
channel.send({ type: 'broadcast', event: 'message', payload: data })

// Presence
await channel.track({ user_id: '123' })
const state = channel.presenceState()

// Unsubscribe
await supabase.removeChannel(channel)

Edge Functions

Copyconst { data, error } = await supabase.functions.invoke('function-name', {
  body: { key: 'value' }
})

Error Handling

Copyconst { data, error } = await supabase.from('users').select('*')

if (error) {
  console.error('Error code:', error.code)
  console.error('Error message:', error.message)
  console.error('Error details:', error.details)
  console.error('Error hint:', error.hint)
  return
}

// data is safe to use
console.log(data)

Common Error Codes

TypeScript Types

Generate Types

Copysupabase gen types typescript --local > database.types.ts

Type Helpers

Copyimport { Database } from './database.types'

// Table row type
type User = Database['public']['Tables']['users']['Row']

// Insert type
type NewUser = Database['public']['Tables']['users']['Insert']

// Update type
type UpdateUser = Database['public']['Tables']['users']['Update']

// Query result type
import { QueryData } from '@supabase/supabase-js'

const usersQuery = supabase.from('users').select('id, name, posts(title)')
type UsersWithPosts = QueryData<typeof usersQuery>

References

• client-patterns.md - Common client patterns