HTTP API

There is no intentic API in the cloud that reaches your code. The platform stores your identity and your sandbox's address and nothing else; the API on this page is served by your daemon, inside your container, and the only way in is a credential you minted.

This page is long and you probably want one part of it:

Where it is#

Each sandbox answers on its own hostname, https://sandbox-<id>.<zone>, over its private Cloudflare tunnel. The app shows the exact URL on Sandbox → Overview. One route stays open: /health, the "is a daemon there" probe every launch script and readiness loop makes.

curl https://sandbox-a1b2c3d4e5f6.intentic.dev/health

{ "ok": true, "sandboxId": "a1b2c3d4e5f6", "boot": { … }, "announce": { … } }

The sandbox id in that answer is how a caller proves it reached this daemon rather than something else on the same port. On the machine running the sandbox there is also https://local-<id>.<zone>, a public DNS name that resolves to 127.0.0.1: a real certificate on a loopback address, so a browser on that machine skips the round trip to Cloudflare and back.

How a call is authorized#

Two kinds of caller, two credentials, and the difference is whether a person is present.

A person, in a browser#

The sandbox authenticates the end user directly against Google: the browser presents a Google ID token, and the daemon verifies its signature against Google's published keys. The platform never holds or signs this credential, so a platform compromise cannot command your sandbox. The first verified identity to arrive becomes the owner; further people are granted access by the owner, with a role that decides how far they reach.

POST /system/session exchanges that token for a daemon-minted session, which is what every steady-state call presents as authorization: Bearer …. Calling it again with a still-valid session renews it.

A program, anywhere#

Anything outside a browser presents a control token in the x-intentic-control header instead. A control token is shown once when minted. The daemon keeps only its hash, and you can revoke it at any time.

curl -X POST "$SANDBOX/system/control/tokens" \
  -H "authorization: Bearer $OWNER_SESSION" \
  -H "content-type: application/json" \
  -d '{"label":"nightly CI","scope":"read"}'

{ "id": "6f1c…", "token": "ict_9wQ…" }

The app mints one for you on Sandbox → Computers → Editor bridge, at editor scope, together with the settings snippet an ACP editor needs. Any other scope is minted through the route above, which requires an owner session.

What a scope reaches#

Worth saying plainly: at drive and above, a stolen token is the agent's reach, because driving an agent means editing files and running commands in this sandbox. read has a smaller scope, which is why it exists separately rather than as a politeness. A token presented on a route outside its scope gets a 403 that says so, rather than a confusing 401.

The shape of a call#

The API is described by a typed contract that the daemon implements and the browser is built against, served over OpenAPI. That has one consequence worth internalising: the contract's path is the URL, there is no envelope, and the body you send and the body you get back are the declared shapes.

SANDBOX=https://sandbox-a1b2c3d4e5f6.intentic.dev

# GET: input rides the query string
curl "$SANDBOX/workspace/file?path=README.md" \
  -H "x-intentic-control: $INTENTIC_TOKEN"

# Everything else: input rides the JSON body, including DELETE
curl -X POST "$SANDBOX/git/root/commit" \
  -H "x-intentic-control: $INTENTIC_TOKEN" \
  -H "content-type: application/json" \
  -d '{"message":"fix the flaky test"}'

Drive an agent#

The reason most scripts are here. A turn executes as a detached daemon-side run: starting it acks with a run id, and any number of clients render it by attaching. So a reload, a second window, another device and your script all watch the same work identically, and nothing is lost if the caller goes away.

# Start a turn. It answers as soon as the run exists: the work is detached.
curl -X POST "$SANDBOX/agent" \
  -H "x-intentic-control: $INTENTIC_TOKEN" \
  -H "content-type: application/json" \
  -d '{"prompt":"Update the changelog for the last five commits.",
       "conversationId":"nightly-changelog",
       "isolated":true}'

{ "run": "run_8c2f…" }

# Watch it: server-sent events, from the start or from a cursor you kept.
curl -N -X POST "$SANDBOX/agent/attach" \
  -H "x-intentic-control: $INTENTIC_TOKEN" \
  -H "content-type: application/json" \
  -d '{"conversationId":"nightly-changelog","after":0}'

conversationId is yours to choose and is what makes a run resumable and addressable later. isolated: true runs the turn in that conversation's own git worktree instead of the shared tree, which is what lets several agents work at once without colliding. The work reaches your main tree only when something calls land.

The route surface#

Around 230 routes in the groups below. Rather than list them here, where they would date, ask the daemon: the hello frame on /events advertises every route name this particular daemon implements.

Streams#

Long-lived routes emit server-sent events: blank-line separated frames, each carrying one data: line of JSON.

curl -N "$SANDBOX/events" -H "authorization: Bearer $SESSION"

data: {"kind":"hello","workspaceId":"…","routes":["agent.run","git.status", …],"build":"…"}

data: {"kind":"heartbeat"}

data: {"kind":"workspaceChanged","paths":["src/app.ts","README.md"]}

data: {"kind":"refsChanged","repos":["root"]}

Those change pushes are not a nicety. An intentic workspace is file-first: the agent edits files and moves git refs with its own tools, out of band from every HTTP route. Without them a client is only ever as fresh as the last thing someone clicked.

Routes that aren't JSON#

Failures#

Open on purpose#

A handful of routes check no bearer, because the caller provably cannot present one. They are /health, the web-chat widget's routes, an automation's webhook fire, a CI provider's webhook, a workflow gate, and the enrollment routes a new computer redeems a one-time pairing token on. Each carries its own narrower check instead.

Old daemon, new client#

Your browser is routinely newer than the daemon it talks to: a released app plane serves every sandbox, whatever image each user last pulled. That stays supported, and it is why hello advertises route names. A client compares that list against the contract it was built with, so a route the daemon predates surfaces as a named gap instead of a 404 nobody can attribute. Pin nothing; ask.

Related pages

• Host API: the same daemon from inside the app, typed, for an extension's views.
• Manifest reference: how an extension declares which of these routes it may call.