REST API

Read and write your Busymate data over a standard PostgREST API at https://api.busymate.net/rest/v1/, with row-level security and role-based access enforced on every call.

api.busymate.net is a CNAME to the Busymate database, so everything here is plain PostgREST — the same REST surface any Supabase project exposes. If you've used @supabase/supabase-js or hit a Supabase REST endpoint before, this will feel familiar; if not, every example below is a copy-pasteable curl.

TL;DR

Authentication

Every request needs an OAuth access token — the same token type that authenticates MCP, Realtime, and the BusyBro ask API. There is one token, three ways in.

Pass it in two headers:

Authorization: Bearer <token>
apikey: <token>

Yes, the token goes in both headers — apikey is the PostgREST gateway key and Authorization is your identity. Put the same OAuth token in each.

How you obtain the token:

• External clients — run the OAuth 2.1 flow (Dynamic Client Registration + PKCE) against the MCP server. See MCP → Connect.
• In the dashboard — the logged-in dashboard exchanges your session for the identical token at POST /first-party-token; you don't normally handle it by hand.

The token carries your user identity and role, so the database knows who you are and what you're allowed to do on every call.

What you can reach — and what governs it

Every table lives in the public schema and has row-level security (RLS) enabled. On top of RLS, most reads and writes are gated by capabilities — your role grants view / edit on sections like devices, entries, settings, services, tags, users. The database checks has_capability(section, action) for you; a token whose role lacks the capability simply gets an empty result (for reads) or a permission error (for writes). See Roles & permissions for the model.

Practically, that means:

• Admins (a role that grants every capability) read and write the whole fleet.
• Scoped roles are limited to the rows they own — e.g. captures and settings for devices you own (owner_user_id = auth.uid()).

Tables you'll typically read or write:

Backend internals — migrations, triggers, partitioning, the device-JWT path — live under Under the Hood. This page is the developer-facing read/write surface.

Reading data

Standard PostgREST. Select columns with select, filter with ?col=<op>.<value>, order, and paginate.

List your devices:

curl -s "https://api.busymate.net/rest/v1/devices?select=uuid,name,os,owner_user_id&order=name.asc" \
  -H "Authorization: Bearer $TOKEN" \
  -H "apikey: $TOKEN"

Read the most recent captures for one device:

curl -s "https://api.busymate.net/rest/v1/entries?select=id,ts,host,payload&device_uuid=eq.$DEVICE_UUID&order=ts.desc&limit=50" \
  -H "Authorization: Bearer $TOKEN" \
  -H "apikey: $TOKEN"

PostgREST operators you'll use most: eq, neq, in, gt/lt, ilike, is. Range pagination via Range headers or limit/offset.

Writing data

POST to insert, PATCH (with a filter) to update, DELETE (with a filter) to remove — each gated by your edit capability and RLS scope.

Rename a device you own:

curl -s -X PATCH "https://api.busymate.net/rest/v1/devices?uuid=eq.$DEVICE_UUID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "apikey: $TOKEN" \
  -H "content-type: application/json" \
  -H "Prefer: return=representation" \
  -d '{ "name": "Test iPhone" }'

If your role can't edit that section, or the row isn't in your scope, the write is rejected — RLS is the real gate, not the request shape.

Callable RPCs

Some operations are exposed as Postgres functions over POST /rest/v1/rpc/<name>. These are the ones meant for integrators (each granted to your authenticated role and scoped to what you're allowed to see):

Resolve a device's effective settings:

curl -s -X POST "https://api.busymate.net/rest/v1/rpc/effective_settings_for_device" \
  -H "Authorization: Bearer $TOKEN" \
  -H "apikey: $TOKEN" \
  -H "content-type: application/json" \
  -d '{ "target_uuid": "'"$DEVICE_UUID"'" }'

Search captures across a workspace:

curl -s -X POST "https://api.busymate.net/rest/v1/rpc/entries_filtered_list" \
  -H "Authorization: Bearer $TOKEN" \
  -H "apikey: $TOKEN" \
  -H "content-type: application/json" \
  -d '{ "target_workspace": "'"$WORKSPACE_UUID"'", "search_q": "api.stripe.com", "lim": 50 }'

Prefer entries_filtered_list / _count over a raw GET /entries?host=ilike.… for search — they force the trigram index and won't hit the statement timeout on large capture sets.

Using a client library

Anything that speaks PostgREST works. With @supabase/supabase-js, point it at the Busymate host and attach your OAuth token:

import { createClient } from "@supabase/supabase-js";
 
const supabase = createClient("https://api.busymate.net", PUBLISHABLE_KEY, {
  global: { headers: { Authorization: `Bearer ${TOKEN}` } },
});
 
const { data, error } = await supabase
  .from("devices")
  .select("uuid, name, os")
  .order("name");

The same client gives you Realtime and RPC calls (supabase.rpc("get_stats")) over the identical token.

Troubleshooting