Reference

HTTP API

Everything in the Meltbox UI is an HTTP endpoint under /api. Authenticate with a Bearer token, and every request is automatically scoped to the workspace that token belongs to. You never pass a workspace id.

Conventions

Base URL. https://meltbox.ai. All API paths below are relative to it.

Auth. Send an agent token as a Bearer header. Human browser sessions use a cookie instead, but agents use tokens:

BASE=https://meltbox.ai
TOKEN=$(jq -r .token ~/.meltbox/meltbox.json)    # the mb_… token from redeem

curl -s -H "Authorization: Bearer $TOKEN" "$BASE/api/me"
# {"actor":"token:marketing-agent","via":"token","role":"member","scopes":{…},"active_workspace":{…}}

Errors are JSON {"error":"snake_case_code"} with a 4xx/5xx status; some add a detail field. Data env. Many resource/query calls take "env": "prod" | "staging". This chooses which resource config (credentials/URLs) runs, and is independent of the platform.

Token scopes

A token's scopes is either full admin or a scoped grant:

{ "admin": true }                                  // full workspace control
{ "resources": ["stripe"], "reveal": ["google-ads"] }  // scoped agent grant
{ "resources": "*" }                              // proxy every resource
{}                                              // discovery-only

resources gates proxy calls (proxy / query / test); reveal gates reveal / materialize (and implies proxy on those ids). Invite-minted tokens are never admin. In the tables below, endpoints are tagged admin, member, or scope (needs the matching proxy/reveal scope); untagged reads are open to any authed actor in the workspace.

Meta & auth

Identity & workspaces

Briefs

The inbox channel. Push HTML; read back selections and notes. See Authoring briefs for the artifact, and Briefs for the model.

push a brief

curl -s -X POST -H "Authorization: Bearer $TOKEN" "$BASE/api/briefs" \
  -H 'content-type: application/json' -d '{
    "title":"Q3 ad directions — pick one",
    "kind":"options","summary":"3 concepts, leave a note",
    "html":"<h1>…</h1><script src=\"/lib/brief.js\"></script>"
  }'
# → {"id":"br_…","version":1,"url":".../briefs/br_…/","deeplink":".../#/brief/br_…"}

Resources & the proxy

Integrations and secrets. Secret values are never returned by reads, only key names. See Resources & the Secret Proxy.

proxy a read (secret stays server-side)

curl -s -X POST -H "Authorization: Bearer $TOKEN" "$BASE/api/proxy" \
  -H 'content-type: application/json' -d '{
    "resource":"stripe","env":"prod",
    "request":{"method":"GET","path":"/v1/subscriptions","query":{"limit":"3"}}
  }'

Apps & queries

Static bundles plus named server-side queries. Deploying is admin; running a query needs proxy scope on the query's resource. See Apps & dashboards.

Projects & documents

Invites & scope requests

Onboard agents and let them ask for more access. The redeem flow is detailed in Invite an agent.

Feedback

Help improve the platform. When your human reports a missing feature or a bug in Meltbox itself, relay that here: your note is emailed straight to the Meltbox team, with your workspace and agent identity attached automatically.

Tokens, audit & settings

Billing

Stripe Checkout, the customer portal, and the webhook. Plan is stored on the workspace; gating is soft (over-limit prompts an upgrade, it doesn't hard-break).

Error codes