API Reference
Complete reference for Postrust REST API endpoints, operators, and headers.
Endpoints
/api (e.g. GET /api/users). The root-level paths below work as-is when compatibility mode (PGRST_COMPAT_MODE=true) is enabled; otherwise prefix them with /api.| Method | Endpoint | Description |
|---|---|---|
GET | /{table} | Read rows from table |
POST | /{table} | Create new rows |
PATCH | /{table} | Update existing rows |
PUT | /{table} | Upsert rows |
DELETE | /{table} | Delete rows |
POST | /rpc/{function} | Call stored procedure |
Filtering Operators
| Operator | Description | Example |
|---|---|---|
| eq | Equals | ?status=eq.active |
| neq | Not equals | ?status=neq.deleted |
| gt | Greater than | ?price=gt.100 |
| gte | Greater than or equal | ?price=gte.100 |
| lt | Less than | ?price=lt.50 |
| lte | Less than or equal | ?price=lte.50 |
| like | Pattern match (case-sensitive) | ?name=like.*Widget* |
| ilike | Pattern match (case-insensitive) | ?name=ilike.*widget* |
| in | In list | ?id=in.(1,2,3) |
| is | Is null/true/false | ?deleted_at=is.null |
Resource Embedding
Embed related resources using foreign key relationships:
# Embed customer in orders
GET /orders?select=*,customer(name,email)
# Nested embedding
GET /orders?select=*,items(product(name,price))
# Filter on embedded resource
GET /orders?select=*,customer!inner(*)&customer.country=eq.USPrefer Headers
return=representationReturn created/updated records in responsereturn=headers-onlyNo body. The only case that gets a Location header naming the created row.count=exactInclude exact row count in responseresolution=merge-duplicatesUpsert (insert or update)Response Headers
| Header | When | Description |
|---|---|---|
Content-Range | Reads, and writes reporting a count | The window returned and the total: 0-24/100 |
Range-Unit | With Content-Range | Always items |
Location | POST with Prefer: return=headers-only | The created row's key: /users?id=eq.42 |
Preference-Applied | When a Prefer was honoured | The preferences actually applied |
Allow | OPTIONS | The methods this resource answers |
WWW-Authenticate | 401 | Bearer, plus what was wrong with a token that was read and refused |
OPTIONS and Allow
OPTIONS reports what a resource actually answers, derived from the schema rather than fixed. A table offers what its grants allow; a view offers what PostgreSQL can genuinely write through it, which is not the same as what it has been granted. PUT replaces one row named by its key, so a relation without a primary key does not offer it however writable it otherwise is. A VOLATILE function is OPTIONS,POST; a stable one adds GET,HEAD.
curl -i -X OPTIONS http://localhost:3000/api/users
# Allow: OPTIONS,GET,HEAD,POST,PUT,PATCH,DELETEGraphQL
Alongside the REST surface, Postrust serves a GraphQL API generated from the same schema, in the dialect Hasura speaks. A client generated against Hasura — its queries, its codegen output, its endpoint — points at this server unchanged.
| Method | Endpoint | Description |
|---|---|---|
POST | /v1/graphql | Execute a query or mutation |
GET | /v1/graphql | GraphQL Playground |
GET | /v1/graphql/ws | Subscriptions over WebSocket |
POST | /v1alpha1/graphql | The address Hasura served before /v1 |
POST | /api/graphql | The same surface, for anything already pointed here |
/v1/graphql is where a Hasura client sends its queries and, for most generated clients, the only address they can be told about. See GraphQL for the schema shape, filters and mutations, and Hasura conformance for how closely the two agree, measured.