Setup API

The setup file your coding agent runs is one client of this API. You need this page only if you are writing another one: your own agent, a script, a CI job. Everything here is what the setup file itself relies on, and the server holds every client to the same rules.

Base URL: https://rendel.ai/api/setup

This is not the SDK's API at api.rendel.ai (see REST API). The setup API writes what the console writes, so it runs beside the console and applies the console's own checks.

Authentication

Every endpoint except GET /file takes the session's setup token, and only in this header:

Authorization: Bearer rd_st_0123456789abcdef01234567

A token is rd_st_ and 24 lowercase hex characters. It is in the file the console hands out, and nowhere else: Rendel keeps only its hash. A token in a query string is not read, so it never ends up in an access log.

There are two kinds of session. A setup session (rendel-setup.md) is refused on an app that has gone live. A sync session (rendel-sync.md) is not, but on a live app its writes become proposals: they answer 202 with proposed and wait for a person in the console. GET /context says which applies, as session.writes: apply or propose.

Limits

Errors

Every error has one shape, the same as the SDK API's:

{ "error": { "code": "invalid_body", "message": "items.0.content: Required" } }

message is a sentence a person or an agent can act on, and for a bad body it names the field. code is what to branch on.

The steps

The Overview panel has thirteen steps, in this order. Who closes a step decides what an agent's own report can do: for a server step, only something Rendel saw ticks it, and an agent saying done is recorded but changes nothing.

Every write endpoint reports its own step: the first write to a step marks it started, and every write adds a line with what it did. A write step counts as finished once the agent moves on to a later step. So an agent needs POST /events only for the steps that happen in code — discover, install, identity, verify — and to mark a step skipped or failed.

GET /file

GET /file?code=<32 hex> — no token. This is the console's curl line:

curl -fsSL "https://rendel.ai/api/setup/file?code=<code>" -o rendel-setup.md

Answers the file as text/markdown, with a newly minted token in it. The code works once and for 15 minutes; after that it answers 410. The console's Download button makes the same file.

POST /start

Claims the session. The panel moves from Waiting for your agent to Agent connected.

{ "ok": true, "session": { "id": "…", "kind": "setup", "status": "running", "expires_at": "…" }, "app": { "id": "…", "name": "…" }, "next": "GET /context" }

Calling it again with the same tool, model and os is a restart and answers the same. A different agent gets 409 already_claimed.

GET /context

What the agent needs before touching the code. Read-only.

POST /events

The agent's own progress. One event, an array of up to 50, or { "events": [...], "detected": {...} }.

detected, the discovery report, takes any of: platform, framework, router, http, auth, locales (up to 40), screens and apiCalls (counts), themeFile, darkTheme (boolean), fonts (up to 10), logoFile. It is merged into what was there and kept with the app.

{ "accepted": 2, "ids": [101, 102], "detected": true }

PUT /appearance

The theme, into the draft. A setup token never publishes.

The theme replaces the draft's, keeping a logo already uploaded. The assistant's name, welcome and suggestions are Experience's, not this endpoint's.

{ "saved": true, "changed": true, "draft": true, "warnings": [
  { "check": "Body text on the surface", "what": "prose and titles", "ratio": 3.9, "minimum": 4.5, "fix": { "token": "onSurface", "suggested": "#2B2B2B" } }
] }

warnings lists every colour pair that fails its contrast minimum, light and dark (a dark one names a themeDark. token), with a value on the same hue that would pass where there is one. They are warnings, not refusals: the SDK deepens an illegible ink on the device either way. Apply the suggestions and send again.

POST /logo

Multipart form data, the file in a field named file:

curl -X POST "https://rendel.ai/api/setup/logo" \
  -H "Authorization: Bearer $RENDEL_TOKEN" \
  -F "file=@assets/images/logo.svg"

PNG, JPEG, WebP or SVG, up to 2 MB. Stored where the console stores a logo, and set in the draft theme.

{ "saved": true, "draft": true, "logoAssetId": "…" }

PUT /experience

The assistant, into the draft persona. A patch: fields left out keep their value.

{ "saved": true, "draft": true, "personaVersion": 3, "changed": true }

POST /knowledge

Up to 25 items, { "items": [...] }. Each is upserted by its external_key (up to 200 characters), so sending a key again updates that source.

A link is fetched by Rendel's server, through the same guard as a link added in the console; the client sends only the address. Archiving takes a source out of service without deleting it. New and changed text is indexed right away.

{ "created": 2, "updated": 0, "unchanged": 1, "archived": 0, "failed": 0,
  "results": [{ "external_key": "plans", "ok": true, "op": "created", "id": "…", "chunks": 3 }],
  "note": "…" }

One item failing does not fail the others. The answer is 422 only when none was saved.

POST /actions

Up to 50 HTTP actions, { "items": [...] }, upserted by external_key, and checked with the console's own rules.

An archive item is { "op": "archive", "external_key": "…" }.

There is no field a secret could go in. An endpoint that wants a shared key says so in needs_key — the kind of key and where it goes, never the key — and is saved switched off until a person enters it with Add key, where it becomes a shared key for the endpoint's host.

• With auth: "none", the shared key is the only credential, and the action may only read.
• With auth: "user", it is sent beside the signed-in person's token: the shape of an API that wants the app's key and the user's session together. The action may read or write. The key must not go where the token goes: a bearer key needs the token moved with auth_name (header:X-Auth-Token), and a header key must not name the token's header. Such an item is refused with a reason.

Anything that changes data needs auth: "user". A key a person already entered on an action is kept when the action is sent again, and an action that already has a shared key is not put back to waiting for one.

{ "external_key": "GET /v1/pets", "name": "my_pets", "description": "The signed-in person's pets.",
  "method": "GET", "url_template": "https://api.example.com/v1/pets",
  "auth": "user", "needs_key": { "kind": "header", "name": "X-App-Key" } }

{ "failed": 0, "needs_key": ["find_stores"],
  "results": [{ "external_key": "GET /v1/stores", "ok": true, "name": "find_stores", "needs_key": true }] }

POST /screens

Declares the screens the client registered in code with registerRoute. A declaration is a plan: the console shows these as planned until a build's manifest names them.

{
  "screens": [{
    "name": "order_detail",
    "title": "Orders › Order",
    "description": "One order: its items, delivery status and payment.",
    "params": { "order_id": { "type": "string", "required": true, "fromActions": true } },
    "file": "lib/rendel/routes.dart",
    "deep_link": "/orders/:id"
  }],
  "archive": [{ "name": "old_settings", "reason": "Removed in 2.3" }]
}

name is snake_case; title 1–60 characters; description 1–300; params as in registerRoute. Declared again by the same name, a screen is updated.

{ "planned": 2, "added": 1, "updated": 0, "unchanged": 1, "archived": 1, "unknown": [], "note": "…" }

GET /status

What Rendel has seen, whatever anyone reported. The setup file polls it while it waits.

POST /smoke

No body. Rendel asks the copilot three to five questions drawn from the app's own configuration — its suggestions, its knowledge, a read action — through the test side, and judges each answer: grounded if it used knowledge, action-backed if it called an action. It passes when at least 80% are one or the other. Allow it up to 150 seconds.

{ "id": "…", "passed": true, "createdAt": "…", "platformFailure": false,
  "results": [{ "question": "Where is my order?", "from": "suggestion", "answer": "…", "actions": ["get_order"], "grounded": false, "actionBacked": true, "ok": true }] }

platformFailure is true when every answer was an error on Rendel's side rather than a weak answer. Nothing in the configuration would change that result, so change nothing and run it again later.

The last run is what the Go live check reads. The console's Run smoke test button runs the same test without a token.

GET /smoke

The latest run, in the shape POST /smoke answers with, for a client that lost that answer. It runs nothing. Before the first run it answers { "run": null }.

POST /complete

Ends the session. The token stops working.

{ "ok": true, "status": "completed", "token": "revoked" }

POST /fail

The client cannot go on. The step it names — or the last one with an event — turns red on the panel with the reason, and the session ends.

{ "ok": true, "status": "failed", "token": "revoked" }