Endpoints

Edit an app

Change an app from an instruction, the way the editor does.

POSThttps://www.setherion.com/api/v1/projects/{id}/edit

Plan: Every plan

Runs the same edit as writing an instruction in the Setherion editor. It is the same route behind the editor's box, so the same credits, the same plan rules and the same safety checks apply, and the result is saved and added to the app's history like any other edit.

You need to be able to edit the app: it is yours, you are an editor or admin of its workspace, or it was shared with you as an editor.

Credits are taken from the account that pays for the app, which is its creator, not necessarily you. If the app's workspace limits what you may spend, that limit applies too.

The change is saved, but it is not online until the app is published. Call Publish an app when you are ready.

Request

bash

curl -X POST https://www.setherion.com/api/v1/projects/7c1e4a52-9b0d-4f3e-8a61-2d5f0c9e7b14/edit \
  -H "Authorization: Bearer $SETHERION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "Make the buttons green and add an opening hours section" }'

Field	Type	Meaning
`prompt`	string, required	What to change, in any language. Spaces around it are ignored. Up to 4,000 characters.
`model`	string, optional	`auto` when left out: Setherion picks within your plan, as in the editor. A model your plan does not include is replaced by the best one it does, not refused.

The app must already have code. An app that was never built answers 409.

It answers when the edit is done

An edit takes from one to several minutes, and the request stays open until it has finished. An edit that runs past about 13 minutes is cut off by the server.

While it works, Setherion sends a space every 10 seconds, so that nothing between you and us closes a quiet connection. Spaces before JSON are still valid JSON: read the whole body, then parse it.

Once the edit has started the status is 200 whatever happens, and ok says how it went. The response's X-Setherion-Run header carries the edit's runId from the first moment, before the body.

Closing the connection does not stop the edit

If your client gives up or the connection drops, the edit carries on and lands in the app as if you had waited, and its credits are spent. Keep the X-Setherion-Run header and ask where the edit is with Following an edit. To stop an edit part way, press Stop in the Setherion editor, on the card that shows it running.

Response

A finished edit:

json

{
  "ok": true,
  "runId": "b3f0e2d1-6a47-4c8e-9d15-0f2b7a3c8e61",
  "projectId": "7c1e4a52-9b0d-4f3e-8a61-2d5f0c9e7b14",
  "changed": {
    "added": ["src/components/OpeningHours.tsx"],
    "modified": ["src/App.tsx", "src/index.css"],
    "removed": []
  }
}

Field	Type	Meaning
`ok`	boolean	`true` when the edit finished and was saved.
`runId`	string	The edit's id. Left out when Setherion could not tell.
`projectId`	string	The app it changed. Left out when Setherion could not tell.
`changed`	object	The files the edit added, changed and removed, each a sorted list of paths. Left out when Setherion could not tell, which is not the same as nothing changed.
`builds`	`false`	Present only when the edited app no longer builds. The edit was written, and its credits come back. Its absence is not a promise that the app builds.
`refundedCredits`	number	How many credits came back, when some did.

An edit that broke the app's build:

json

{
  "ok": true,
  "runId": "b3f0e2d1-6a47-4c8e-9d15-0f2b7a3c8e61",
  "projectId": "7c1e4a52-9b0d-4f3e-8a61-2d5f0c9e7b14",
  "changed": { "added": [], "modified": ["src/App.tsx"], "removed": [] },
  "builds": false,
  "refundedCredits": 10
}

An edit that did not happen:

json

{ "ok": false, "error": "This edit costs 10 credits and you have 3.", "outOfCredits": true }

outOfCredits is present, and true, only when the account paying for the edit has no credits left. Every other refusal has ok: false and an error and nothing else.

Why an edit can answer ok: false

These come back with status 200, because the edit had started.

This edit costs 10 credits and you have 3. with outOfCredits: true. The number is the price of that edit and your balance. On someone else's app the sentence is This app's owner has no credits left this month, so this edit cannot run., and never names their balance.
You have used 40 of the 100 credits a month this workspace allows you on its owner's plan. Ask an admin to raise it. with outOfCredits: true, when a workspace owner capped what you may spend.
You're working faster than our safety limit allows (120 an hour). You can carry on in about 12 minutes. Edits and builds are paced at 120 an hour per account.
The edit stopped before it finished. Nothing was charged for it. The run ended without finishing.
The edit could not start. or The edit failed: ... when something failed on our side. Try again.

Following an edit

GEThttps://www.setherion.com/api/v1/projects/{id}/edit?run={runId}

Plan: Every plan

Where an edit is, for a client that stopped waiting or never waited. Free, and safe to ask every minute or so.

bash

curl "https://www.setherion.com/api/v1/projects/7c1e4a52-9b0d-4f3e-8a61-2d5f0c9e7b14/edit?run=b3f0e2d1-6a47-4c8e-9d15-0f2b7a3c8e61" \
  -H "Authorization: Bearer $SETHERION_API_KEY"

json

{
  "ok": true,
  "status": "done",
  "runId": "b3f0e2d1-6a47-4c8e-9d15-0f2b7a3c8e61",
  "projectId": "7c1e4a52-9b0d-4f3e-8a61-2d5f0c9e7b14",
  "startedAt": "2026-10-16T15:13:02.118Z"
}

`status`	`ok`	Meaning
`running`	`true`	Still working. Ask again in a minute or so.
`done`	`true`	Finished and saved in the app. Publish it when you are ready. With `cutShort: true` it was saved as soon as the code was written, without the finishing touches.
`stopped`	`false`	Stopped before it finished. Nothing in the app changed.
`failed`	`false`	Failed. Nothing in the app changed.
`stalled`	`false`	Has not moved for several minutes and has probably stopped. Open the app in Setherion to see where it got to.

A false one carries an error sentence too, and the edit may be sent again. This answer does not list the files that changed: only the edit's own response does.

Status	`error`
`400`	`Say which edit, in "run": the runId its POST answered.`
`404`	`No such app on this account.` or `No such edit on this app.`

Errors before the edit starts

Status	When
`400`	`prompt` is missing, empty or longer than 4,000 characters.
`401`	The key is missing, wrong or revoked.
`404`	There is no such app, or your key cannot edit it. This includes an app you can only view.
`409`	The app has no code yet. Build it in Setherion first.

The exact sentences

Status	`error`
`400`	`Say what to change, in "prompt".`
`400`	`Keep "prompt" under 4,000 characters.`
`404`	`No such app on this account.`
`409`	`This app has no code yet. Build it in Setherion first, then edit it here.`

Was this page helpful?

List your apps

Publish an app

Join the community

Questions, ideas and what others are building.