Supabase Tables API

openapi: 3.2.0
info:
  title: Supabase Database REST Tables API
  description: The Supabase Database REST API provides auto-generated RESTful endpoints for every table, view, and function in your PostgreSQL database. Powered by PostgREST, it supports full CRUD operations, complex filtering with horizontal and vertical filtering operators, pagination, sorting, and embedding of related resources via foreign key relationships. Row Level Security policies are enforced on all API requests. The schema is auto-generated from your database, so paths and schemas vary per project. This specification documents the common patterns and conventions.
  version: 1.0.0
  contact:
    name: Supabase Support
    url: https://supabase.com/support
  termsOfService: https://supabase.com/terms
servers:
- url: https://{project_ref}.supabase.co/rest/v1
  description: Supabase Project PostgREST Server
  variables:
    project_ref:
      description: Your Supabase project reference ID
      default: your-project-ref
security:
- apiKeyAuth: []
  bearerAuth: []
tags:
- name: Tables
  description: CRUD operations on database tables. Paths are auto-generated based on your database schema.
paths:
  /{table}:
    get:
      operationId: selectRows
      summary: Select rows from a table
      description: Retrieves rows from a database table with support for filtering, sorting, pagination, and column selection. PostgREST operators are used in query parameters for horizontal filtering (e.g. eq, neq, gt, lt, gte, lte, like, ilike, in, is, fts, plfts, phfts, wfts, cs, cd, ov, sl, sr, nxl, nxr, adj, not, or, and). Vertical filtering uses the select parameter.
      tags:
      - Tables
      parameters:
      - $ref: '#/components/parameters/TableName'
      - $ref: '#/components/parameters/Select'
      - $ref: '#/components/parameters/Order'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      - $ref: '#/components/parameters/RangeHeader'
      - $ref: '#/components/parameters/PreferCount'
      responses:
        '200':
          description: Rows retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
          headers:
            Content-Range:
              description: Range of returned rows and total count
              schema:
                type: string
        '400':
          description: Bad request - invalid filter or parameter
        '401':
          description: Unauthorized - missing or invalid API key
        '404':
          description: Table not found in schema
    post:
      operationId: insertRows
      summary: Insert rows into a table
      description: 'Inserts one or more rows into a database table. Use the Prefer header with return=representation to get the inserted rows in the response. Supports upsert with Prefer: resolution=merge-duplicates.'
      tags:
      - Tables
      parameters:
      - $ref: '#/components/parameters/TableName'
      - $ref: '#/components/parameters/PreferReturn'
      - name: Prefer
        in: header
        schema:
          type: string
          enum:
          - resolution=merge-duplicates
          - resolution=ignore-duplicates
        description: Upsert conflict resolution strategy
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - type: object
                description: Single row to insert
              - type: array
                items:
                  type: object
                description: Multiple rows to insert
      responses:
        '201':
          description: Rows inserted successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
        '400':
          description: Bad request - invalid data or constraint violation
        '401':
          description: Unauthorized
        '409':
          description: Conflict - duplicate key violation
    patch:
      operationId: updateRows
      summary: Update rows in a table
      description: Updates rows in a database table that match the specified filters. All PostgREST filter operators can be used as query parameters to select which rows to update.
      tags:
      - Tables
      parameters:
      - $ref: '#/components/parameters/TableName'
      - $ref: '#/components/parameters/PreferReturn'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Column values to update
      responses:
        '200':
          description: Rows updated successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
        '400':
          description: Bad request
        '401':
          description: Unauthorized
    delete:
      operationId: deleteRows
      summary: Delete rows from a table
      description: Deletes rows from a database table that match the specified filters. All PostgREST filter operators can be used as query parameters. It is strongly recommended to always include filters to avoid deleting all rows.
      tags:
      - Tables
      parameters:
      - $ref: '#/components/parameters/TableName'
      - $ref: '#/components/parameters/PreferReturn'
      responses:
        '200':
          description: Rows deleted successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
        '400':
          description: Bad request
        '401':
          description: Unauthorized
components:
  parameters:
    Offset:
      name: offset
      in: query
      description: Number of rows to skip before starting to return rows
      schema:
        type: integer
        minimum: 0
    Order:
      name: order
      in: query
      description: Comma-separated list of columns to sort by. Append .desc for descending, .asc for ascending. Use .nullsfirst or .nullslast to control null ordering.
      schema:
        type: string
    PreferReturn:
      name: Prefer
      in: header
      description: Control what is returned after a mutation. Use return=representation to get the affected rows, return=headers-only for just headers, or return=minimal for no body.
      schema:
        type: string
        enum:
        - return=representation
        - return=headers-only
        - return=minimal
    Limit:
      name: limit
      in: query
      description: Maximum number of rows to return
      schema:
        type: integer
        minimum: 0
    PreferCount:
      name: Prefer
      in: header
      description: Request a total row count. Use count=exact for precise count, count=planned for estimated count, or count=estimated for a combination.
      schema:
        type: string
        enum:
        - count=exact
        - count=planned
        - count=estimated
    Select:
      name: select
      in: query
      description: Comma-separated list of columns to return. Supports renaming (alias:column), casting (column::type), and embedding related resources via foreign keys (related_table(columns)).
      schema:
        type: string
    TableName:
      name: table
      in: path
      required: true
      description: Name of the database table or view
      schema:
        type: string
    RangeHeader:
      name: Range
      in: header
      description: Request a specific range of rows using HTTP Range header (e.g. 0-24 for first 25 rows).
      schema:
        type: string
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: apikey
      description: Supabase project API key. Use the anon key for client-side access (subject to RLS) or service_role key for server-side access (bypasses RLS).
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT access token from Supabase Auth for user-context requests.
externalDocs:
  description: Supabase Data REST API Documentation
  url: https://supabase.com/docs/guides/api