agentappbuilderOpen the app

Docs

Concepts

Organizations, projects, apps, screens, the two canvases, frames, captures, versions and your edits, variants, flow links, notices and project keys.

Organization

An organization holds your projects. You create one the first time you sign in, or while you claim a project. Members have a role: owner, admin or member. Owners and admins create projects, create and revoke keys, and claim projects into the organization. The app does not have a screen to invite members yet.

Project

A project is one product, for example your app and its admin panel. It has two statuses.

  • Pending: created by an agent with POST /api/projects, without any account. It belongs to no organization yet and nobody can open its canvas. It comes with a claim link valid 7 days and a temporary key.
  • Active: claimed into an organization, or created in the app. Its members see it at https://app.agentappbuilder.com/p/<project>, a short identifier of 8 letters and digits.

A claim link (https://app.agentappbuilder.com/claim/<token>) turns a pending project into an active one in the organization you choose. It works once. It expires 7 days after it was issued. Before it expires, the agent can call renew_claim_link for a new link valid 7 more days; the previous link stops working at once. Once the link has expired, the temporary key has expired with it, so the agent can no longer reach the project and has to create a new one.

A pending project stays small because anyone can create one: at most 100 frames (prototype and live frames together), 400 versions and 10 MB of captures until it is claimed.

App

An app is one surface of the project with its own screens: for example the web app, the mobile app, the marketing site or the admin panel. Each app has:

  • a kind: web, mobile, site or admin (default web);
  • a device preset that sets the size of its frames: phone (390 x 844), tablet (834 x 1112) or desktop (1440 x 900). The default is desktop, or phone for a mobile app;
  • optionally a description and the folder of the app in your repository (repo_path).

Each app has its own canvases. Flow links never cross from one app to another.

Screen

A screen is one view of an app, such as “Sign in” or “Interventions”. It has a name, a slug derived from the name, and optionally its route in the app, its source file and a description. A screen appears on the canvas as a group of its states, side by side.

Canvas

Each app has two canvases, and the switch at the bottom of the canvas goes from one to the other:

  • Prototype: the frames your agent writes as HTML, and the captures you imported. This is where versions live and where you point at what to change.
  • Live app: the captures of your running app, as your agent sent them. This is how the app looks today.

The same screen can appear on both canvases. A state can exist once on each: one live frame and one prototype frame with the same key.

State and frame

A state is one situation of a screen: empty, filled, modal open, error. Each state is a frame on a canvas, with a label (“empty”) and a key derived from the label (“empty”).

Every frame has its own URL:

https://app.agentappbuilder.com/f/<token>

A frame URL opens the canvas with that frame selected, for members of the project’s organization. Paste it into your chat with what you want changed: your agent reads the frame from the URL. The canvas address of a selected frame (/p/<project>?frame=<token>) works the same way. Anywhere a tool expects a frame, it accepts the frame URL, the canvas address of the frame, its token or the frame id.

Live frame and capture

A capture is a screenshot of one state of your running app, local or deployed. Your agent takes it with a script on your machine and sends it to POST /api/captures, with the screen, the state, the route, the address captured and the window size. The image goes from the script to the platform, not through the model.

A live frame is a state on the Live app canvas. It shows its latest capture, with the date of capture and the address captured.

  • A live frame has no versions: a new capture of the same state replaces the previous one.
  • Your agent cannot add a version to a live frame: it can only capture the state again, or delete it with delete_live_frame when you ask. To change a captured screen, you import it into the prototype first.
  • Captures are stored in a private storage bucket. Members of the project read them through signed links valid one hour, and your agent gets a signed link, and over MCP the image itself, from get_frame. See Security and data.

Import and capture version

Importing a live frame, with Import to prototype or Import all, adds a capture version to the prototype frame of the same screen and state. The prototype frame is created if it does not exist.

  • The capture version becomes active and implemented at once: it is what the app shows today. No notice is opened, and an open notice on that frame is closed.
  • Links between imported states are copied into the prototype.
  • Importing again adds another capture version.
  • A capture version keeps its image even when a newer capture replaces the live frame.

A capture version is an image, not HTML. When you ask for a change on it, your agent first recreates the screen as HTML faithful to the capture and to your code, then applies your change: the result is a new HTML version.

Version

A prototype frame keeps every version, numbered v1, v2, v3 in order: HTML versions written by your agent, and capture versions you imported. Versions are never overwritten.

  • A version your agent adds with add_proto_version becomes active at once. Variants wait for your choice instead (see Variant).
  • You can make an older version active again from the canvas. Your agent reads the active version.
  • The implemented version is the one your agent last reported as coded in your real app. A frame may have no implemented version yet.
  • A version has one author: get_frame says user for the copies you make with Duplicate or Duplicate screen and for your edits in the canvas, and agent for every other version, captures you imported included. Your agent treats a version of yours as a design decision: it starts from its HTML, and asks you before replacing it without starting from it.
  • A version made from your edits in the canvas keeps its base version (the version you edited) and the list of your edits: for each one, the element (tag, classes, the start of its text), the property, the value before and the value after. Only the style attribute of the elements you changed differs from the base version. See Edit a frame.
  • The HTML of a version holds at most 102400 bytes (100 KB).

When a project has at least one implemented frame, get_project_context lists in to_implement every frame whose active version differs from its implemented version, except states whose variants wait for your choice. That list is what “apply” means for your agent.

Variant

A variant is a version proposed next to others for the same state: your agent proposes 2 to 4 at once, as a round, with a label each (A, B, C, D by default). They are numbered versions like any other.

  • While a round waits for your choice, the canvas shows the variants side by side, and get_project_context lists them as pending_variants. Your agent does not implement the state before you choose.
  • The active version does not change when variants arrive, except for a new state, where the first variant is active.
  • You choose one: it becomes the active version and the round is settled. The other variants stay in the history. Choosing another version, or a new version from your agent, settles the round too.
  • Flow links belong to the state, so they stay in place whichever variant you choose.

A flow link joins two frames of the same app and the same canvas with the user action that leads from one to the other, the trigger: “Tap Save”, “Submit invalid form”. On the canvas it is an arrow labelled with its trigger. Your agent sets the links of a frame all at once: set_flow_links replaces every outgoing link of each frame it names.

Notice

A notice is a question the platform relays to your agent. Today there is one kind: the active version of a frame changed away from its implemented version.

  • Why: you made another version active on a frame that is already implemented, by choosing it or by saving your edits in the canvas. Importing a capture does not create a notice. Production still shows the implemented version, and your agent must not guess whether it should follow. For your edits, the notice lists them and your agent asks you whether to implement them.
  • When: the notice is created when you choose the version in the canvas. The canvas says “Claude Code will ask you at its next request whether production should follow vN”. Every response of every tool then lists the open notices first, until it is resolved.
  • How it is resolved: your agent asks you and calls resolve_notice with your decision. The notice also closes by itself when you make the implemented version active again, when your agent reports the active version as implemented, or when you import a capture into that frame.

A frame has at most one open notice. If you change the active version again, the open notice is updated.

Project key

Your agent reaches a project with a key: aab_ followed by 64 hexadecimal characters (32 random bytes). The platform stores only its SHA-256 hash and its first 12 characters, to show you which key is which. A key opens one project and nothing else.

  • Temporary: the key returned by POST /api/projects. It works as long as the claim link. When you claim the project, it becomes permanent.
  • Permanent: created in the app (empty canvas or Settings), or a temporary key after the claim.
  • Revocation: in Settings, Keys, an owner or admin revokes a key. It stops working at once and cannot be restored.

The key is shown once, when it is created. See Security and data.