Admin API

Everything the admin does goes through the Admin API, under /admin/api/*: creating tables, granting permissions, building DataViews and dashboards, managing users and settings. The admin is one client of it; a script and the MCP server are others.

Access

• Only members of the Administrators role, with a session or an Admin API token. See Tokens.
• Delegated administration never goes through it: a non-administrator managing users or files does it through the Data API, under their permissions. See Delegated administration.
• Some things can't be changed with a token, only by an administrator signed in to the admin: the MCP settings and Allow API tokens of the SQL Console.

The contract

The same as every TotalBase API:

• request bodies { "data": … }, answers { "data": …, "meta"? }, errors { "errors": [ … ] };
• 201 on create, 204 when there's nothing to return, 200 otherwise; an unknown id anywhere in the path is 404;
• camelCase keys.

See Errors.

Its OpenAPI document

The Admin API describes itself: GET /admin/api/openapi returns its OpenAPI 3.1 document, every route with its parameters, body and answers. Load it in any OpenAPI tool to browse it or generate a client.

curl -s https://ops.acme-field.example/admin/api/openapi \
  -H "Authorization: Bearer $TOTALBASE_TOKEN" > admin-api.json

GET /admin/api/openapi/data?role=<id> returns the Data API's document as a given role would see it, to check what a role can reach.

Example: create a table

The same table the table recipe builds through the MCP server, by HTTP. Save the body as work_orders.json; …/tables/preview takes the same body and answers the SQL without running it.

{ "data": {
  "name": "work_orders",
  "columns": [
    { "name": "id", "dataType": "uuid", "primaryKey": true, "default": "gen_random_uuid()" },
    { "name": "number", "dataType": "bigint", "identity": "ALWAYS" },
    { "name": "site", "dataType": "uuid", "nullable": false,
      "foreignKey": { "targetSchema": "public", "targetTable": "sites", "targetColumn": "id", "onDelete": "RESTRICT" } },
    { "name": "status", "dataType": "text", "nullable": false, "default": "'NEW'",
      "check": "status IN ('NEW','ASSIGNED','IN_PROGRESS','COMPLETED','CANCELLED')" },
    { "name": "resolution", "dataType": "text",
      "check": "status <> 'COMPLETED' OR resolution IS NOT NULL",
      "checkMessage": "Write the resolution before completing the order." }
  ]
} }

curl -s -X POST https://ops.acme-field.example/admin/api/schema/public/tables \
  -H "Authorization: Bearer $TOTALBASE_TOKEN" -H "Content-Type: application/json" \
  -d @work_orders.json

The answer is 201 with the new table's resource id. A new table is hidden; expose it with that id:

curl -s -X PATCH https://ops.acme-field.example/admin/api/resources/$RESOURCE_ID \
  -H "Authorization: Bearer $TOTALBASE_TOKEN" -H "Content-Type: application/json" \
  -d '{ "data": { "exposedMethods": ["GET", "POST", "PATCH", "DELETE"] } }'

The table is created in one transaction, audited, and checked by PostgreSQL, exactly as from the admin or the MCP server.

Prefer the Data API

Many administrative records are ordinary tables in the totalbase schema, readable and writable through the Data API under permissions: users, roles' members, files, templates. Use the Data API for plain reads and writes, and the Admin API for what isn't a row operation: creating a table, publishing a DataView, sending an invitation.

Next steps

• AI Agents.