REST reference - Duraton

Every project with the Data API switched on serves its database’s tables, views and functions over HTTP at https://<slug>.<project domain>/rest/v1. This page is the reference for that endpoint: what it accepts, what it refuses, and every error it answers with. It is current as of 2026-10-27. Before you start

The project has a database and the data_api module switched on: in the console (Data API, Turn on), or PATCH /projects/<project id> with the project’s whole services list including data_api. Turning it off answers service_not_enabled within about 30 seconds and keeps your table exposure and settings for when you turn it back on.
You have a project API key: a publishable key (dtn_pk_...) or a secret key (dtn_sk_...).
The table you call is exposed to the Data API (see Exposing tables).
The project’s Data API URL is the url of GET /databases/<database id>/data_api on the management API.

Keys and roles

Key	Runs as	Use it
Publishable (`dtn_pk_...`)	the `anon` role: sees only what you granted `anon`, filtered by your row-level security policies	in browsers and apps
Secret (`dtn_sk_...`)	the database owner: every table, row-level security not applied unless the table forces it	on servers only; never ship it to a browser

Send the key in the apikey header. A key in the query string (?apikey=) is refused with api_key_in_url.
Authorization: Bearer <the same key> is accepted and ignored. Any other bearer token is refused with user_token_invalid (401, with a WWW-Authenticate: Bearer error="invalid_token" challenge): the Data API takes project keys only.
Every answer carries an x-request-id header. Quote it when you contact support.

Exposing tables

A new table is not reachable through the Data API. A publishable call to it answers 403 data_access_denied; a secret call reads it as the owner. Expose a table with a schema change on the management API:

POST /databases/<database id>/schema_changes
Content-Type: application/json

{
  "changes": [
    {
      "kind": "set_table_exposure",
      "table": { "schema": "public", "name": "todos" },
      "exposure": "read"
    }
  ]
}

`exposure`	What `anon` and `authenticated` may do
`none`	nothing (every grant removed)
`read`	`SELECT`
`read_write`	`SELECT`, `INSERT`, `UPDATE`, `DELETE`, and use of the table’s own sequences

Exposing a table also turns its row-level security on. With no policy, an exposed table answers no rows to the publishable key: 200 []. Add a policy for anon to return rows, for example create policy "read open todos" on public.todos for select to anon using (not done);
create_table changes take the same optional exposure.
Functions: set_function_exposure with the function’s name, its argument types as signature, and exposed: true or false. A function is callable only in an exposed schema.
The table list and the table detail on the management API report each table’s exposure and policyCount; custom means grants that match none of the three, made over a direct connection. Setting an exposure replaces them.
Every exposure change is recorded in the database’s History like any other schema change.

Reading

Feature	Grammar
Tables and views	`GET` or `HEAD /rest/v1/<table>`
Columns	`select=id,title`; rename `select=label:title`; cast `select=id::text`
Related rows	`select=id,author(name)`; inner join `author!inner(name)`; left join `author!left(name)`; name the relationship when two match
Filters	`<column>=<operator>.<value>` with `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `like`, `ilike`, `in`, `is`; negate with `not.`; combine with `or=(...)` and `and=(...)`; `(any)` and `(all)` modifiers
Order	`order=title.asc,id.desc`, with `nullsfirst` or `nullslast`
Paging	`limit` and `offset`, or the `Range` and `Range-Unit` headers; a partial answer is `206` with `Content-Range`, a range past the end `416`
Totals	`Prefer: count=exact`, `count=planned` or `count=estimated`; the total is the number after `/` in `Content-Range`
One object	`Accept: application/vnd.pgrst.object+json` answers a single JSON object, or `406` when the result is not exactly one row

Lists are plain JSON arrays paged by offset and range. They are not the { data, nextCursor } envelope the management API uses.

Writing

Feature	Grammar
Insert	`POST /rest/v1/<table>` with one JSON object or an array; `columns=` limits the columns read from the body; `Prefer: missing=default` fills absent columns with their defaults
Upsert	`POST` with `Prefer: resolution=merge-duplicates` or `resolution=ignore-duplicates`, and `on_conflict=<columns>`; or `PUT /rest/v1/<table>?<primary key filters>`
Update	`PATCH /rest/v1/<table>?<filter>`
Delete	`DELETE /rest/v1/<table>?<filter>`
What comes back	`Prefer: return=minimal` (nothing), `return=headers-only` (`Location`), `return=representation` (the rows)

Updates and deletes need a filter. A PATCH or DELETE on a table whose query holds only select, order, limit, offset, columns or on_conflict is refused with filter_required before anything runs. limit alone is not a filter. Updates and deletes are bounded. Each runs with handling=strict and a max-affected cap, so a change that would touch more rows than the cap changes nothing and answers max_affected_exceeded. The cap is the project’s limit (1,000 rows by default), or your own lower Prefer: max-affected=<n>.

Functions

POST /rest/v1/rpc/<function> with the arguments as one JSON object.
GET /rest/v1/rpc/<function>?<argument>=<value> for functions declared stable or immutable.
A RAISE in your function answers data_function_raised with your message as detail. A status your function sets is answered with that status and the code in A status your function sets.

Schemas and the API description

The project’s exposed schemas default to public. Change the list with PATCH /databases/<database id>/data_api (exposedSchemas, at most 20). History, the system catalogs and schemas starting pg_ cannot be exposed.
Pick a schema per request with Accept-Profile (reads) or Content-Profile (writes).
GET /rest/v1/ with a secret key answers an OpenAPI 2.0 description of what the owner may reach. A publishable key is refused with api_key_kind_not_allowed.

Preferences

The Prefer header (RFC 7240) is read as a comma-separated list.

Preference	Handling
`tx=`	dropped on every request: a request cannot ask to be rolled back
`handling`, `max-affected` on `PATCH` and `DELETE`	replaced by `handling=strict` and the bounded `max-affected` (see Writing)
an unknown preference under `handling=strict`	refused with `data_request_invalid`
every other preference	passed on unchanged, in order

Limits

Limit	Default	Notes
Rows per read	1,000	Set lower for the project with `maxRows` on `PATCH /databases/<database id>/data_api`; it cannot exceed the ceiling the view reports as `maxRowsCeiling`. A read never returns more rows; use paging and `Prefer: count=exact` for the total
Rows per update or delete	1,000	`maxAffectedRows` in the view
Request body	1 MiB	`maxRequestBytes` in the view; a larger body is refused with `request_body_too_large` before it is read
Statement timeout, publishable key (`anon`)	3 s	Set by your operator for the database server; a change reaches the project’s Data API the next time it starts, after it was stopped for being idle or after its settings change
Statement timeout, signed-in users (`authenticated`)	8 s	as above
Request time	25 s	then `service_timeout`

The project’s Data API stops after 10 minutes without a request. The first request after that waits while it starts; if the start takes more than 2 seconds it answers unavailable with Retry-After: 1.

Idempotency

Send Idempotency-Key: <1 to 255 of A-Z a-z 0-9 _ -> on POST, PATCH or DELETE to make a retry safe. GET, HEAD and PUT are idempotent already, so the header is ignored on them.
A key is scoped to the project and the API key that sent it. The same key with the same request (method, path, query, Content-Type, Prefer and body) replays the first answer, for 24 hours.
The same key with a different request: 422 idempotency_key_reused. The same key while the first request still runs: 409 idempotency_request_in_progress.
Answers with a 2xx or 4xx status are kept for replay. A 5xx answer is not, so a retry under the same key runs again.
An answer body larger than 1 MiB is not kept: its replay has the same status and headers and an empty body.

CORS

Browsers may call the Data API only from origins on the project’s list: corsOrigins on PATCH /databases/<database id>/data_api, each exactly scheme://host[:port], at most 20. The list is empty by default, so no browser origin is allowed until you add one. * allows every origin and must be the only entry.
A preflight from a listed origin answers 204 with Access-Control-Allow-Methods: GET, HEAD, POST, PUT, PATCH, DELETE, the allowed request headers (including apikey, authorization and idempotency-key) and Access-Control-Max-Age: 600. From any other origin: 403 cors_origin_not_allowed.
Answers to a listed origin echo it in Access-Control-Allow-Origin with Vary: Origin, and expose Content-Range, Content-Location, Location, Preference-Applied, x-request-id and Retry-After.
Use the publishable key in browsers. A secret key works from a browser too, so never ship it in one.

Schema changes and reloads

The Data API reads your tables and functions once and keeps that picture. A change made through the management API, the console or the management MCP is picked up within about 2 seconds, with no action from you. A change made over a direct database connection is not. After one, ask for a reload:

POST /databases/<database id>/data_api/schema_reloads (answers 202), or
databases.dataApi.reloadSchema(<database id>) in the SDK, or
the project MCP’s data_api_run_schema_reload tool.

Paused databases

Database	Answer	What to do
Paused for being idle	503 `database_resuming` with `Retry-After: 3`; the request starts the database	retry after `Retry-After`; `@supabase/postgrest-js` retries reads on 503 by itself, up to 3 times
Paused by its owner, the operator, or for its storage limit	409 `database_paused`	resume it; a retry does not
Being created, restored or deleted	409 `database_not_ready`	retry once it is ready

Errors

Every refusal is an RFC 9457 problem, Content-Type: application/problem+json:

{
  "type": "https://duraton.dev/problems/row_conflict",
  "title": "row_conflict",
  "status": 409,
  "detail": "A row with the same unique value already exists, or a referenced row is missing.",
  "code": "row_conflict",
  "postgres": { "code": "23505" }
}

code is stable: it is never renamed or reused. Branch on it, not on detail.
postgres is present when the database itself refused the request and the status is below 500. It carries the database’s error code (SQLSTATE) as code. A secret key also gets message, details and hint; a publishable key gets code only.
With @supabase/postgrest-js, error.code is this code. Code written for a client that compared error.code with a SQLSTATE such as "23505" reads error.postgres.code instead.

Error codes

Code	Status	Detail	What it means
`api_key_required`	401	This request needs an API key.	No API key was sent. Send the project’s publishable or secret key in the `apikey` header.
`api_key_invalid`	401	The API key is not valid.	The `apikey` header holds no key of this project. Check the key and the project host.
`api_key_revoked`	401	The API key has been revoked. Use an active key.	The key was revoked. Issue a new key and send that one.
`api_key_kind_not_allowed`	403	This kind of API key cannot be used here.	This kind of key may not make this request: the API description at `/rest/v1/` needs a secret key.
`api_key_in_url`	400	Send the API key in the apikey header, never in the URL.	The key was sent in the query string, where logs and browser history keep it. Send it in the `apikey` header only.
`user_token_invalid`	401	The user token is not valid.	An `Authorization: Bearer` value that is not one of the project’s keys was sent. The Data API takes project keys only; send the key in `apikey` and no other bearer token.
`not_found`	404	The requested resource was not found.	No project answers at this host, or the path is not under `/rest/v1`.
`bad_request`	400	The request could not be understood.	The path holds an encoded `/` or `\` (`%2F`, `%5C`), which is refused; also the code of a 4xx status your function sets that has no code of its own.
`service_not_enabled`	404	This service is not enabled for the project.	The Data API is not switched on for this project, or the project has no database yet.
`cors_origin_not_allowed`	403	This origin is not allowed.	The browser’s origin is not on the project’s list of allowed origins. Add it in the Data API settings.
`request_body_too_large`	413	The request body is too large.	The request body is larger than the project’s request size limit. Send fewer rows per request.
`filter_required`	400	Updates and deletes need a filter.	An update or a delete on a table named no filter. Add a filter such as `id=eq.1`; `limit`, `order` and `select` do not count.
`data_request_invalid`	400	The request is not a valid query.	The query could not be read: a filter, `select`, body or preference is not valid, or names a column that does not exist.
`data_method_not_allowed`	405	This method is not allowed on this resource.	The table, view or function does not take this method, such as a write to a read-only view or a `GET` on a function that changes data.
`data_not_acceptable`	406	The requested representation is not available.	The `Accept` media type cannot be produced, or a single object was asked for and the result is not exactly one row.
`data_range_not_satisfiable`	416	The requested range is outside the result.	The requested range starts past the end of the result.
`data_reference_ambiguous`	300	More than one relationship or function matches. Name one.	More than one relationship or function overload matches. Name the one you mean.
`data_resource_not_found`	404	The table, view or function was not found, or is not exposed.	The table, view or function does not exist, or is in a schema the project does not expose.
`data_access_denied`	403	This key’s role may not do this.	The key’s role may not do this: the table is not exposed to the Data API for this operation, or a row-level security policy refused the row.
`row_conflict`	409	A row with the same unique value already exists, or a referenced row is missing.	A row with the same unique value already exists, or a referenced row is missing.
`row_invalid`	400	The row breaks a rule of the table.	A value breaks a rule of the table: a missing required value, a failed check, or a value of the wrong type.
`max_affected_exceeded`	400	The change would affect more rows than allowed.	The update or delete would change more rows than allowed, so nothing changed. Narrow the filter, or raise your own `max-affected` up to the project’s limit.
`data_function_raised`	400	The function raised an error.	Your function raised an error. The detail is your function’s own message.
`data_function_response_invalid`	500	The function set an invalid response status or headers.	Your function set an invalid response status or headers. Fix the function.
`idempotency_key_invalid`	400	The Idempotency-Key header is not in the accepted format.	The `Idempotency-Key` header is not 1 to 255 letters, digits, `_` or `-`, or was sent twice.
`idempotency_key_reused`	422	This Idempotency-Key was already used with a different request. Send a new key for a new request.	This `Idempotency-Key` was used for a different request. Send a new key for a new request.
`idempotency_request_in_progress`	409	A request with this Idempotency-Key is still in progress. Retry once it has finished.	A request with this `Idempotency-Key` is still running. Retry after it finishes.
`database_resuming`	503	The database is starting. Retry after the time in Retry-After.	The database was paused for being idle and is starting now. Retry after the seconds in `Retry-After`.
`database_paused`	409	The database is paused. Resume it first.	The database is paused by its owner, the operator, or for its storage limit. A retry does not resume it: resume it in the console.
`database_read_only`	409	The database is read-only: it is over its storage limit. Delete data or move to a plan with more storage; writes work again once it is under the limit.	The database is over its storage limit, so the Data API takes `GET` and `HEAD` only (call functions with `GET`). Delete data in the console’s table editor or over a direct connection, or move to a plan with more storage; writes work again once it is under the limit.
`database_not_ready`	409	The database is not ready for this. Check its state and try again.	The database is being created, restored or deleted, or cannot serve in its current state. Retry once it is ready.
`rate_limited`	429	Too many requests.	The key sent more requests than its rate allows. Retry after `Retry-After`.
`quota_exceeded`	429	The project has used its quota for this period. It resets at the time in Retry-After.	The project used its request quota for this period. It resets at the time in `Retry-After`.
`query_timeout`	504	The query took too long and was cancelled.	The query ran longer than its statement timeout and was cancelled. Narrow it, or add an index.
`service_timeout`	504	The service did not answer in time.	The request did not finish within the time allowed, or waited too long for a database connection. Retry, or make the query cheaper.
`not_implemented`	501	This feature is not implemented yet.	This operation is not available on this project’s Data API.
`unavailable`	503	The service is temporarily unavailable.	The Data API cannot serve the project right now, for example while it starts or reconnects. Retry after `Retry-After`.
`internal`	500	Something went wrong.	Something failed on our side. Retry; if it persists, contact support with the `x-request-id` of the answer.

A status your function sets

A function that sets its own response status gets that status and the code below, with your function’s message as detail. Any other 4xx status takes bad_request; any other status takes internal.

Status your function sets	Code
400	`bad_request`
401	`unauthenticated`
403	`forbidden`
404	`not_found`
409	`conflict`
422	`unprocessable`
429	`rate_limited`
500	`internal`
501	`not_implemented`
502	`provider_failure`
503	`unavailable`

Client example

The Data API speaks the grammar @supabase/postgrest-js writes; version 2.118.0 is the one our compatibility test runs. This snippet is run by that test as written here:

import { PostgrestClient } from "@supabase/postgrest-js";

const db = new PostgrestClient("https://<slug>.<project-domain>/rest/v1", {
  headers: { apikey: "dtn_pk_..." },
});

const { data, error } = await db
  .from("todos")
  .select("id,title")
  .eq("done", false)
  .limit(20);

Pass only the apikey header: the client then sends no Authorization header of its own.

Not supported

Feature	Answer
Aggregates (`count()`, `sum()` in `select`)	refused
Query plans (`Accept: application/vnd.pgrst.plan`)	refused
`Prefer: tx=`	dropped
Full-text and JSON path filters, other range and array operators	not part of this API yet
CSV and GeoJSON answers	not part of this API yet
The key in the URL	refused with `api_key_in_url`
User sign-in tokens	refused with `user_token_invalid`

Docs index

​Keys and roles

​Exposing tables

​Reading

​Writing

​Functions

​Schemas and the API description

​Preferences

​Limits

​Idempotency

​CORS

​Schema changes and reloads

​Paused databases

​Errors

​Error codes

​A status your function sets

​Client example

​Not supported

​Related