supabase-api（Supabase API 文档）

Supabase

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": "john@example.com"
}

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

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": "user@example.com",
      "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": "newuser@example.com",
  "password": "securepassword123",
  "email_confirm": true
}

Response:

{
  "id": "8974a9fa-95c4-4839-8d50-76f4666d2113",
  "email": "newuser@example.com",
  "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": "updated@example.com",
  "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': 'test@example.com',
        '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

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