Automate with the HTTP API

Anything that can send HTTP can build on Appbricx: your own scripts, internal tools, a deploy pipeline, or an agent framework without MCP. You can create projects, check and apply contracts, test the app as each user, take screenshots, read data, deploy, and operate the running app (SQL, rows, schema, snapshots, rollbacks, workflow runs, logs, secrets). JSON in, JSON out.

When you would use it

• You are wiring Appbricx into your own tooling, for example an agency dashboard that spins up a project per client.
• Your language or platform has no MCP client and you would rather not shell out to the CLI.

It does the same things as the MCP server and the CLI, with the same answers. If you just want to try it, the curl examples below are the quickest start.

Base URL and auth

https://appbricx.com/api/dev/v1
Authorization: Bearer apx_pat_...

• Use an access token. Tokens work on /dev/v1 and /mcp only; they are never accepted by the rest of the Appbricx API (billing, admin, workspace settings).
• The web app's signed-in session also works here, with every scope across all of the user's workspaces.
• Send content-type: application/json on requests with a body.

Endpoints

"read" endpoints work with any valid token. Writing endpoints also need a non-viewer role in the project's workspace.

Operate the running app

env is dev (the preview, the default) or prod (the published app). Every prod write takes a database snapshot first and returns its snapshotId; if the snapshot fails, nothing is written. Every write is recorded in the project's admin audit trail.

Hand-made schema (indexes, views, functions, triggers, extra tables and columns created with sql) is kept by contract apply and publish; schema marks it.

HTTP bodies use camelCase (dryRun, fullPage, skipVerify); the MCP tools use snake_case for the same fields. data/query also accepts entity in place of table.

Examples

export API=https://appbricx.com/api/dev/v1
export AUTH="Authorization: Bearer $APPBRICX_TOKEN"
export P=3f2c9a10-...   # project id

Check

curl -sS -X POST "$API/projects/$P/check" -H "$AUTH" \
  -H "content-type: application/json" \
  -d "{\"contract\": $(cat appbricx.json)}"
# → { "report": { "ok": true, "errors": [], "fixes": [...], "warnings": [], "summary": {...} } }

Apply

curl -sS -X POST "$API/projects/$P/apply" -H "$AUTH" \
  -H "content-type: application/json" \
  -d "{\"contract\": $(cat appbricx.json)}"
# → { "report": {...}, "summary": "... demo sign-ins per role ...", "warnings": [], "changed": true }

Verify

curl -sS -X POST "$API/projects/$P/verify" -H "$AUTH"
# → { "report": { "status": "pass", "ms": 25000, "stages": [
#       { "stage": "static",  "status": "pass", "checks": [...] },
#       { "stage": "data",    "status": "pass", "checks": [...] },
#       { "stage": "browser", "status": "pass", "checks": [...] } ] } }

Each check has id, status, evidence and, when it fails, a fix. skipped is never a pass.

Screenshot

# The PNG itself
curl -sS -X POST "$API/projects/$P/screenshot?format=png" -H "$AUTH" \
  -H "content-type: application/json" \
  -d '{"route": "/jobs", "as": "technician"}' -o jobs.png

# JSON: png (base64), url, signedInAs, viewport, errors, overflowX, text
curl -sS -X POST "$API/projects/$P/screenshot" -H "$AUTH" \
  -H "content-type: application/json" \
  -d '{"as": "guest"}'

as is a persona id, a demo login email or "guest". The default viewport is 390×844.

Run SQL on prod

curl -sS -X POST "$API/projects/$P/sql" -H "$AUTH" \
  -H "content-type: application/json" \
  -d '{"env": "prod", "sql": "CREATE INDEX job_due ON job (due)"}'
# → { "rows": [], "rowCount": 0, "statements": [{ "sql": "CREATE INDEX ...", "command": "CREATE" }],
#     "env": "prod", "readOnly": false, "durationMs": 41, "snapshotId": "prod-20261012T...-agent-sql" }

Errors

Errors are JSON with a message and, usually, a code:

{ "error": "This token lacks the \"deploy\" scope", "code": "FORBIDDEN_SCOPE" }

Next

• App contract
• Access tokens
• Developer CLI