Overview

The Data API is the REST API over the tables, views and functions you expose. It lives under /api on the instance's address. It has no version prefix, and it's the same API the admin, the App and the MCP server use.

URLs

/api/{schema}/table/{name}            rows of a table
/api/{schema}/table/{name}/{id}       one row, by its primary key
/api/{schema}/view/{name}             rows of a view (read-only)
/api/{schema}/function/{name}         call a function

The table, view or function segment is always written out.

A method exists for a resource only if it's exposed. Otherwise the answer is 404, as for a table that doesn't exist.

Some routes aren't resources:

Every route, with its method and what it needs: Routes.

Request and response

Bodies use one envelope in both directions. What you send goes in data, what you get back comes in data, and information about the result comes in meta:

POST /api/public/table/customers
Authorization: Bearer <token>
Content-Type: application/json

{ "data": { "name": "Mercado del Norte S.A.", "status": "ACTIVE" } }

{ "data": { "id": "6a0f...", "name": "Mercado del Norte S.A.", "status": "ACTIVE" } }

Reads take their options as query parameters and have no body:

GET /api/public/table/customers?fields=id,name&where[status][_eq]=ACTIVE&count=true

{ "data": [ { "id": "6a0f...", "name": "Mercado del Norte S.A." } ], "meta": { "count": 38 } }

Errors come in errors:

{ "errors": [ { "source": "POSTGRESQL", "code": "UNIQUE_VIOLATION",
                "message": "A customer with this tax id already exists.", "field": "tax_id" } ] }

• source is POSTGRESQL when the database refused, and TOTALBASE for TotalBase's own checks.
• code is stable and safe to branch on. The full list is in Errors.
• field, when present, names the one column the error is about, so a form can show it there.

Column names keep their PostgreSQL spelling (reported_at). Keys TotalBase defines are camelCase (meta.count).

Status codes

What happens to a request

Raw SQL from clients is never accepted. Every request is processed the same way:

request  →  limits  →  parse the query  →  resolve the resource (exposed?)
         →  permissions (action, fields, row filter)  →  compile to parameterized SQL
         →  PostgreSQL: one transaction, with a statement timeout

• Values are always sent as bind parameters, and names come only from PostgreSQL's catalog, so a request can't inject SQL.
• Each request runs in one PostgreSQL transaction, reads included, with statement_timeout set to api.request_timeout_ms (30 s by default).
• Writes also record an audit entry and an event in the same transaction. See Audit and events.

What the Data API doesn't do

These are deliberate. Each has a PostgreSQL answer:

Next steps

• A client, end to end: every step below, in one small TypeScript client.
• Authentication.
• Reading and Filtering.
• Writing.