Skip to content
Esc
↑↓navigate↵open⌘Jpreview
On this page

Build over the HTTP API

Build and update Charming apps with plain web requests, no MCP server to add and nothing to install.

Charming has two ways in. One is MCP, where your client adds Charming as a connector and gets a set of tools. The other is this one: a plain HTTP API that any agent able to make web requests can call, with nothing installed and no server to add.

Both build the same apps in the same account. Pick whichever your agent can do.

When to use this path

Use the HTTP API when your client cannot add an MCP server, when adding one is more trouble than it is worth, or when your agent lives in a terminal or an editor and already makes web requests all day.

Most coding agents fall in that last group. Two cases do not: a chat surface that cannot make its own web requests, such as claude.ai or ChatGPT chat, and Microsoft 365 Copilot, which reaches Charming only through MCP. Setup steps per client are at AI clients.

Start here

Paste this into your agent:

Connect me to Charming and help me build my first app. Use Charming's
HTTP API. Ask before starting account pairing, wait for me to approve
it, then read https://charm.ing/docs/build-http.md and ask me what I
want to build.

That URL is the full build manual, written for the agent rather than for you. Your agent reads it, then asks what you want.

What your agent does

Every save needs a signed-in user’s chrm_user_* token, so your agent connects to your account first. It calls POST /api/pair/start, shows you the returned verification_url and user_code, and polls POST /api/pair/poll until you approve at charm.ing/pair. The token it receives works for your whole account, so later saves and updates skip this step.

Your agent then writes the app as a package, package.json plus server.js and an optional ui.js, and posts the files with a fresh Idempotency-Key:

jq -n --rawfile p package.json --rawfile s server.js --rawfile u ui.js \
    '{files: {"package.json": $p, "server.js": $s, "ui.js": $u}}' \
  | curl -sS -i https://charm.ing/app \
      -H "Authorization: Bearer $TOKEN" \
      -H 'Content-Type: application/json' \
      -H 'Idempotency-Key: todo-create-001' -d @-

The response is HTTP 202 with a buildId and a statusUrl. Charming resolves the npm dependencies and bundles the code in the background; your agent polls GET /api/v1/app-builds/<buildId> until state is published, and the response then carries the app’s URL. A failed build names the error, and the file, line, and column when available, so the agent fixes the file and saves again with a fresh key.

To update, the agent reads GET /app/<id>/source, sends the whole replacement tree to PUT /app/<id> with the ETag as If-Match, or sends PATCH /app/<id>/source with edits that each name a path. The app keeps running its last working revision until the new build publishes, and a failed build leaves it unchanged.

These routes build and run an app:

Route What it does
POST /api/pair/start, /poll Pair the agent with your account for a chrm_user_* token
POST /app Create an app from its files; returns a build to poll
GET /api/v1/app-builds/<buildId> Read a build’s progress or result
GET /app/<id>/source Read the app’s files and the ETag an update needs
PUT /app/<id> Replace the whole tree with If-Match
PATCH /app/<id>/source Apply exact edits that name a path
GET /app/<id>/describe List the app’s callable operations
<method> /app/<id>/api/<op> Call one operation with the method its route declares

An operation called with a method its route does not declare returns HTTP 405 method_not_allowed, and the Allow header names the declared method.

Where the detail lives

Execution failures

An executor_error may include details: { execution, operationId, reservationId? }. execution: "not_started" means the authority permanently ruled out execution of that operation. "may_have_run" means the operation may have executed; inspect its state before trying again. If admission failed before the authority returned an identity, details contains only execution: "may_have_run"; no operation or reservation ID is invented. Missing details, a timeout, or a lost connection do not prove nonexecution. These fields do not trigger an automatic retry. An invalid_module found after remote evaluation also carries execution: "may_have_run" and its operation identity, while retaining the validation message needed to fix the source. Read these fields from the response’s error.details. An operation that runs past its time limit answers 504 timeout instead, and its details carry the same execution fields next to limit, limitMs, and elapsedMs.

Was this page helpful?