Supabase

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:

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

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:

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

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

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

# 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