Skip to content

API and data

An API and everything around your data, inside Postgres

Every resource you describe gets a REST API and a typed client, and the plumbing an admin needs: events, webhooks, jobs, email and files. It all runs on your own Postgres, without an extra queue service.

Start in the cloud

Early accessSign up with GitHub or email. Your first app is live in a few minutes. Plans from €0.99 a month.

Or self-host it for free

REST API

Routes for every resource you describe

GET /api/v1/{resource}
A list, with a filter, an order and pages of 50, up to 500.
POST /api/v1/{resource}:search
The same list, with a JSON body for long filters.
GET · POST · PATCH · DELETE
One record. An update needs the record’s current ETag.
:facets · :series · :histogram
Counts per value, counts over time and histograms, for filters and charts.
:map · :seek
The records in a map’s view, and the page at any row position.
:upload · :reveal · :undelete
Files, sensitive fields, and soft-deleted records brought back.
POST /api/v1:batchWrite
Up to 500 writes across resources, in one transaction.
Terminal
# Print a token for a user, from your project
npx protobase token [email protected]

# Repairs that are ready but not paid, newest first
curl --get https://shop.example.com/api/v1/repairs \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode 'filter=status = "ready" AND paid = false' \
  --data-urlencode 'order_by=booked_on desc'
  • Google’s API design guides: AIPs 131 to 136, 158 and 160, with their rules for ordering, ETags, soft delete and undelete.
  • Errors as RFC 9457 problem details, with stable names you can match on.
  • OpenAPI 3.1 at /api/openapi.json and an interactive reference at /api/docs, both showing only what the caller may use.
  • Lists return the names of related records and up to 10 photos per record in the same request.
  • Web APIs only, so the server runs on Node and on Workers.
Read the API reference

Filters

One filter language, in the address and in the API

  • Filters are AIP-160 text, parsed by aip-parsers, the maintainer’s own open-source library.
  • Functions for lists of values, search, similarity, regular expressions, empty values and relative dates such as now() - 7d.
  • A filter error points at the part of the text that is wrong, with a hint.

Typed client

@protobase/client

  • Typed calls for lists, records, search, aggregates, maps, sensitive fields, files with upload progress, and your API functions.
  • Record types follow from the resource description, and filters can be built with a typed helper.

Safe by default

Fast and correct on real data

  • Transactions

    Every request runs in a transaction with a time limit, and reads run read-only.

  • Big tables

    A query that would scan a large table is refused, with the index to add. Counts on big tables come from the planner.

  • Writes

    Every write runs in one transaction with a row lock, the access check and your write hooks.

Events and webhooks

Every change, wherever it came from

  • Events

    Postgres triggers write each change to an outbox in the same transaction, so writes from psql, other services and cron jobs count too. API writes arrive in milliseconds, others within two seconds.

  • Webhooks

    Declared in code or created in the admin app. Signed per the Standard Webhooks spec and retried 10 times over about three days, honouring Retry-After.

  • Webhook tools

    Ordered delivery when you need it, full or thin payloads, your own body shape, a test event, resending failed ones and rotating secrets. Deliveries are kept for 30 days.

A webhook subscription named Orders to the warehouse, with its events, URL, filter and payload, and actions to send a test event, resend failed deliveries, rotate the secret and disable it.
A webhook subscription in the admin app, with a test event, resending and secret rotation.

Jobs and email

Background work, kept in your database

  • Jobs

    pg-boss in your own Postgres, enqueued in the same transaction as your write, even from SQL. Retries with backoff, timeouts, priorities and keys that prevent duplicates.

  • Schedules

    Cron schedules with time zones that handle daylight saving; missed runs collapse into one. Failed jobs get a page with Retry and Delete.

  • Email

    One SMTP server for sign-in mail and your own. Templates are React Email components, sent from jobs, write hooks or API functions.

Files and images

Uploads and images, handled

  • A file field stores a reference in a plain text column; there are no extra tables.
  • Files go to local disk or any S3-compatible bucket (the S3 provider needs Bun), with streaming uploads, signed links for private files and a year of caching for public ones.
  • Images get resized WebP, AVIF, JPEG and PNG versions and a small placeholder shown while they load. Orientation is fixed and metadata removed.
  • Replaced files are deleted on a schedule, a day later by default.

Your own endpoints

When you need code of your own

  • API functions

    One file per endpoint in functions/, a web-standard handler or a Hono app. It gets the session, records that follow the caller’s access, and the database for privileged work.

  • Signed webhooks in

    Helpers check the signatures of incoming webhooks, both HMAC ones and Standard Webhooks, and validate bodies with Zod, Valibot or ArkType.

  • Remote resources

    One Protobase app can show another app’s resources as its own. The browser calls the other app directly with a short-lived token; there is no proxy.

Keep reading

Your back office, live in a few minutes

Sign up with GitHub or email, pick a starting point, and ask the assistant for what you need.

Start in the cloud

Early access Plans from €0.99 a month.