Management API

Everything the CLI and portal UI do goes through the portal's own HTTP API — there is no private back channel. Anything you can click, you can script.

This page is for your own tooling. If the caller is an AI client, use the MCP endpoint instead: it's these same operations exposed as MCP tools — with argument schemas, a project-scoped token you can rotate, and the docs served alongside them — rather than endpoints a model has to guess its way around.

Provision a project per customer

A B2B product that gives every tenant an isolated database: create the project, apply migrations, and read back the keys, all from your signup flow, instead of clicking through the portal for each new account.

Ephemeral environments in CI

Spin up a throwaway project for a pull request, run the test suite against real Postgres and real RLS policies rather than mocks, and delete it when the branch merges.

Infrastructure as code

Keep flags, secrets, scheduled functions, and DNS records in a script under version control, so a rebuilt project is identical to the one it replaced.

Internal admin tooling

Build your own support console — look up a user, ban an account, re-run a schedule — without giving support staff portal logins.

Authenticating

Exchange your admin email and password for a bearer token at /api/auth/cli-token — the same token the CLI stores in ~/.shovelbase/config.json. Treat it like a root credential: it can read every key and delete every project in the organization.

TOKEN=$(curl -s -X POST https://shovelbase.com/api/auth/cli-token \
  -H 'Content-Type: application/json' \
  -d '{"email": "admin@…", "password": "…"}' | jq -r .token)
 
curl -s https://shovelbase.com/api/projects -H "Authorization: Bearer $TOKEN"

A worked example — provision a project, wait for it, apply a schema, and print the keys an app would need:

set -euo pipefail
API=https://shovelbase.com/api
AUTH="Authorization: Bearer $TOKEN"
 
# 1. Create the project — the response is the project row, incl. its keys.
REF=$(curl -s -X POST "$API/projects" \
  -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"name": "tenant-acme"}' | jq -r .slug)
 
# 2. Wait for the service containers to come up (the endpoint returns an
#    array, one entry per service, each with a "healthy" boolean).
until curl -sf "$API/projects/$REF/services" -H "$AUTH" \
  | jq -e 'length > 0 and all(.healthy)' >/dev/null
do sleep 3; done
 
# 3. Apply the schema. "version" is the ordering key migrations are recorded
#    under — the CLI uses a timestamp, so anything sortable works.
curl -s -X POST "$API/projects/$REF/migrations" \
  -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"version": "20260720120000", "name": "init",
       "sql": "create table public.todos (id bigint generated always as identity primary key);"}'
 
# 4. Hand the app its credentials. There is no "url" field — a project is
#    always served at https://<slug>.shovelbase.com.
ANON=$(curl -s "$API/projects/$REF" -H "$AUTH" | jq -r .anon_key)
echo "SHOVELBASE_URL=https://$REF.shovelbase.com"
echo "SHOVELBASE_ANON_KEY=$ANON"

Projects & schema

Functions, schedules & secrets

Auth

Storage, queues & flags

Web & domains

Monitoring

Sources & organization

Sources mirror the project endpoints for the surfaces they have — database, functions, schedules, secrets, logs — under /api/sources/<slug> instead of /api/projects/<ref>.

Responses are JSON; failures carry a non-2xx status and an { "error": "…" } body. See the CLI reference for the commands that wrap the most common of these calls.