Supabase

Supabase API integration with managed authentication. Access database tables via PostgREST, manage auth users, and handle storage buckets. Use this skill when users want to interact with Supabase projects - querying database tables, managing users, or working with storage. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway).

Access the Supabase API with managed authentication. Query database tables via PostgREST, manage auth users, and handle storage buckets.

Quick Start

# List storage buckets
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/supabase/storage/v1/bucket')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Base URL

https://api.maton.ai/supabase/

Only the endpoints listed in the API Reference section below are supported. Maton proxies requests to your connected Supabase project using these service prefixes:

• rest/v1 - PostgREST API (database tables)
• auth/v1 - GoTrue authentication API
• storage/v1 - Storage API

Authentication

All requests require the Maton API key in the Authorization header:

Authorization: Bearer $MATON_API_KEY

Environment Variable: Set your API key as MATON_API_KEY:

export MATON_API_KEY="YOUR_API_KEY"

Getting Your API Key

1. Sign in or create an account at maton.ai
2. Go to maton.ai/settings
3. Copy your API key

Connection Management

Manage your Supabase connections at https://api.maton.ai.

List Connections

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections?app=supabase&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Create Connection

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'supabase'}).encode()
req = urllib.request.Request('https://api.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Get Connection

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

{
  "connection": {
    "connection_id": "{connection_id}",
    "status": "ACTIVE",
    "creation_time": "2026-03-29T22:47:35.570344Z",
    "last_updated_time": "2026-03-29T22:48:23.435225Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "supabase",
    "metadata": {}
  }
}

Open the returned url in a browser to complete authentication setup.

Delete Connection

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Specifying Connection

If you have multiple Supabase connections, specify which one to use with the Maton-Connection header:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/supabase/storage/v1/bucket')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '{connection_id}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

If you have multiple connections, always include this header to ensure requests go to the intended project.

Security & Permissions

• Access is scoped to database tables, auth users, and storage buckets within the connected Supabase project.
• All write operations require explicit user approval. Before executing any POST, PATCH, or DELETE call, confirm the target table/resource, filter conditions, and intended effect with the user. DELETE and PATCH without narrow filters can affect many rows.
• Production data scope: Database mutations, auth user changes, and storage operations directly affect the connected project's live data. Prefer staging/test projects for exploratory work.

API Reference

Database (PostgREST)

The PostgREST API auto-generates endpoints based on your database schema. Access tables and views in the public schema.

Get OpenAPI Schema

GET /supabase/rest/v1/

Returns the OpenAPI specification describing all available tables and endpoints.

List Records from Table

GET /supabase/rest/v1/{table_name}

Query Parameters:

• select - Columns to return (e.g., select=id,name,email)
• order - Sort order (e.g., order=created_at.desc)
• limit - Maximum records to return
• offset - Number of records to skip

Example:

GET /supabase/rest/v1/users?select=id,email&order=created_at.desc&limit=10

Get Single Record

GET /supabase/rest/v1/{table_name}?id=eq.{id}&select=*

Insert Records

POST /supabase/rest/v1/{table_name}
Content-Type: application/json
Prefer: return=representation

{
  "name": "John Doe",
  "email": "[e-mail]"
}

Update Records

PATCH /supabase/rest/v1/{table_name}?id=eq.{id}
Content-Type: application/json
Prefer: return=representation

{
  "name": "Jane Doe"
}

Delete Records

DELETE /supabase/rest/v1/{table_name}?id=eq.{id}

Filtering Operators

Operator	Meaning	Example
eq	Equals	?status=eq.active
neq	Not equals	?status=neq.deleted
gt	Greater than	?age=gt.18
gte	Greater than or equal	?age=gte.18
lt	Less than	?age=lt.65
lte	Less than or equal	?age=lte.65
like	Pattern match	?name=like.*john*
ilike	Case-insensitive pattern	?name=ilike.*john*
in	In list	?status=in.(active,pending)
is	Is null/true/false	?deleted_at=is.null

Auth (GoTrue)

Get Auth Health

GET /supabase/auth/v1/health

Response:

{
  "version": "v2.188.1",
  "name": "GoTrue",
  "description": "GoTrue is a user registration and authentication API"
}

Get Auth Settings

GET /supabase/auth/v1/settings

Response:

{
  "external": {
    "email": true,
    "phone": false,
    "google": false,
    "github": false
  },
  "disable_signup": false,
  "mailer_autoconfirm": false
}

List Users (Admin)

GET /supabase/auth/v1/admin/users

Response:

{
  "users": [
    {
      "id": "8974a9fa-95c4-4839-8d50-76f4666d2113",
      "email": "[e-mail]",
      "email_confirmed_at": "2026-03-29T23:01:46.718322Z",
      "created_at": "2026-03-29T23:01:46.689584Z"
    }
  ],
  "aud": "authenticated"
}

Get User (Admin)

GET /supabase/auth/v1/admin/users/{user_id}

Create User (Admin)

POST /supabase/auth/v1/admin/users
Content-Type: application/json

{
  "email": "[e-mail]",
  "password": "securepassword123",
  "email_confirm": true
}

Response:

{
  "id": "8974a9fa-95c4-4839-8d50-76f4666d2113",
  "email": "[e-mail]",
  "email_confirmed_at": "2026-03-29T23:01:46.718322Z",
  "role": "authenticated",
  "app_metadata": {
    "provider": "email",
    "providers": ["email"]
  }
}

Update User (Admin)

PUT /supabase/auth/v1/admin/users/{user_id}
Content-Type: application/json

{
  "email": "[e-mail]",
  "user_metadata": {
    "name": "Updated Name"
  }
}

Delete User (Admin)

DELETE /supabase/auth/v1/admin/users/{user_id}

Storage

List Buckets

GET /supabase/storage/v1/bucket

Response:

[
  {
    "id": "avatars",
    "name": "avatars",
    "public": true,
    "created_at": "2026-03-29T23:01:06.638Z",
    "updated_at": "2026-03-29T23:01:06.638Z"
  }
]

Get Bucket

GET /supabase/storage/v1/bucket/{bucket_id}

Create Bucket

POST /supabase/storage/v1/bucket
Content-Type: application/json

{
  "id": "documents",
  "name": "documents",
  "public": false,
  "file_size_limit": 10485760,
  "allowed_mime_types": ["application/pdf", "image/png"]
}

Update Bucket

PUT /supabase/storage/v1/bucket/{bucket_id}
Content-Type: application/json

{
  "public": true
}

Delete Bucket

DELETE /supabase/storage/v1/bucket/{bucket_id}

List Objects in Bucket

POST /supabase/storage/v1/object/list/{bucket_id}
Content-Type: application/json

{
  "prefix": "",
  "limit": 100,
  "offset": 0
}

Upload Object

POST /supabase/storage/v1/object/{bucket_id}/{path}
Content-Type: {mime_type}

{binary_data}

Download Object

GET /supabase/storage/v1/object/{bucket_id}/{path}

Delete Object

DELETE /supabase/storage/v1/object/{bucket_id}/{path}

Pagination

PostgREST Pagination

Use limit and offset query parameters:

GET /supabase/rest/v1/users?limit=10&offset=20

Use the Range header for range-based pagination:

GET /supabase/rest/v1/users
Range: 0-9

Auth User Pagination

GET /supabase/auth/v1/admin/users?page=1&per_page=50

Code Examples

JavaScript

// List storage buckets
const response = await fetch(
  'https://api.maton.ai/supabase/storage/v1/bucket',
  {
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`
    }
  }
);
const buckets = await response.json();

Python

import os
import requests

# Query database table
response = requests.get(
    'https://api.maton.ai/supabase/rest/v1/users',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'},
    params={'select': 'id,email', 'limit': 10}
)
users = response.json()

Create User and Storage Bucket

import os
import requests

headers = {
    'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}',
    'Content-Type': 'application/json'
}

# Create auth user
user_resp = requests.post(
    'https://api.maton.ai/supabase/auth/v1/admin/users',
    headers=headers,
    json={
        'email': '[e-mail]',
        'password': 'securepass123',
        'email_confirm': True
    }
)
user = user_resp.json()

# Create storage bucket
bucket_resp = requests.post(
    'https://api.maton.ai/supabase/storage/v1/bucket',
    headers=headers,
    json={
        'id': 'user-uploads',
        'name': 'user-uploads',
        'public': False
    }
)
bucket = bucket_resp.json()

Notes

• The connection routes to a specific Supabase project configured during setup
• PostgREST endpoints are auto-generated from your database schema
• Use Prefer: return=representation header to get created/updated records back
• Storage bucket names must be unique within the project
• Auth admin endpoints require service role permissions
• Database queries support complex filtering, ordering, and joins via PostgREST syntax
• IMPORTANT: When using curl commands, use curl -g when URLs contain brackets or special characters
• IMPORTANT: When piping curl output to jq, environment variables may not expand correctly in some shells

Error Handling

Status	Meaning
400	Missing Supabase connection or invalid request
401	Invalid or missing Maton API key
404	Table or resource not found
409	Conflict (e.g., duplicate bucket name)
429	Rate limited
4xx/5xx	Passthrough error from Supabase API

PostgREST Errors

{
  "code": "PGRST205",
  "details": null,
  "hint": null,
  "message": "Could not find the table 'public.users' in the schema cache"
}

Resources

• Supabase REST API Guide
• PostgREST Documentation
• Supabase Auth API
• Supabase Storage API
• Maton Community
• Maton Support