# The Brickify API

## Bricks Technical Documentation

*How Brickify turns an existing project into a Bricks tenant — what the endpoint actually returns, why the endpoint itself is free, and where the cost of adopting Bricks really lands.*

---

Brickify is the on-ramp for bringing an existing application — something you built by hand, or "vibe-coded" with an AI IDE — onto the Bricks platform. The name suggests a converter, but the mechanism is more honest than that: **Brickify does no conversion and runs no AI of its own.** It hands your own IDE assistant a precise, tenant-specific instruction document, and *that* assistant does the migration by talking to Bricks's normal APIs.

This design has a direct consequence for cost, so it is worth stating up front: **the Brickify endpoint is free. What you pay for is the Studio AI work it sets in motion — and only if you choose the conversational path.**

## What the endpoint returns

Brickify is a single authenticated request that returns a large Markdown instruction document tailored to one tenant:

```
GET /v2/tenants/:tenantId/brickify-prompt
    ?tenantConfig=1&semanticGraph=1&capabilityIndex=1&appConformance=1
Authorization: Bearer <your Bricks session>
```

The four query flags are scope toggles — each includes or omits a section of the protocol. In the Bricks app they appear as checkboxes in the Brickify dialog; toggling one re-fetches the document. The response is the rendered protocol, with your tenant's real identifiers (base URL, tenant id, schema name, name) interpolated into it.

You then save that document as your IDE's instruction file — `CLAUDE.md`, `.cursorrules`, or equivalent — and let your assistant work from it.

The protocol instructs your assistant to:

- **Sign the project's provenance** — record that this project was brickified, so its origin is auditable.
- **Read your repository's own docs** to understand the app it is migrating.
- **Configure the tenant**, by one of two paths (below).
- **Pre-register the semantic graph**, build a per-app capability index, and bring the app into conformance (a SvelteKit static build with Tailwind and the Bricks SDK), then upload, publish and version it.

```mermaid
flowchart TD
    A["Org admin opens Apps → Brickify"] --> B["GET /brickify-prompt"]
    B --> C["Endpoint interpolates your tenant's<br/>real ids into the protocol"]
    C --> D["Copy as CLAUDE.md / .cursorrules"]
    D --> E["Paste into your OWN IDE assistant"]
    E --> F{"Which path?"}
    F -->|Conversational| G["Your assistant drives ONE Studio AI<br/>conversation on this tenant"]
    F -->|Declarative| H["Apply a manifest bundle to<br/>/v2/tenants/:id/apply<br/>— needs an apply grant"]
    G --> I["Schema, relationships, workflows, roles,<br/>permissions and concepts in place"]
    H --> I
    I --> J["App brought into conformance,<br/>uploaded, published, deployed"]
```

## Calling it from an MCP client

The same calls are served as **MCP tools**, one endpoint per organisation:

```
POST /v2/tenants/:tenantId/mcp
api-key: <your integrator key>        (or Authorization: Bearer <your Bricks session>)
```

Register that URL in your assistant's MCP client. The prompt still says *how* to brickify; the tools are how the assistant acts:

| Tool | What it calls |
|---|---|
| `brickify_prompt` | this prompt (also offered as the MCP prompt `brickify`) |
| `config_read`, `state_read` | the tenant configuration, and the snapshot with its `state_version` |
| `apply_schema` | the manifest as JSON Schema: what each artefact type's `spec` may contain |
| `studio_send`, `studio_progress`, `studio_cancel`, `studio_clear_context` | the organisation's Studio conversation |
| `apply_dry_run`, `apply` | the manifest lint plan, and the apply |
| `app_list`, `app_upload`, `publish`, `publish_status` | the apps, their upload and their publish |

Each tool calls its HTTP route as you, so it accepts and refuses exactly what that route does and returns its status and body unchanged: `apply` still needs an apply grant, a Studio turn still costs Bricks Tokens, and an upload still needs the rights it needs over HTTP. `studio_send` returns as soon as the turn starts, because a turn runs for minutes; `studio_progress` follows it to its result.

There is no tool that writes a table, a role or a permission directly, none that runs SQL, and none that reads or writes your organisation's records: the tenant changes only through the Studio, a manifest, or an app upload and publish. The server sends no instructions into your assistant's session when it connects; the prompt is there to read when you choose.

## The two migration paths

- **Conversational.** Your IDE assistant works in the organisation's one **Studio AI** conversation — the one people use in the browser, never a second — authenticating with the developer's integrator key. It is not a reduced or programmatic variant: it is the same whole-system assistant a human drives in the Studio, holding the same tools, so it creates tables and relationships, wires workflows, sets roles and permissions, declares concepts and can write app files. A turn streams its progress back (server-sent events) and runs for as long as the work takes — minutes, not milliseconds. This path costs Bricks Tokens (see below).
- **Declarative (manifest apply).** Your assistant writes a manifest — one declaration per artefact: tables, relationships, workflows, roles, permissions, integrations, apps — zips it, and applies it to the tenant. It writes through the same spine the Studio writes through, but no model runs, so it debits **no Bricks Tokens**; the manifest lives in your repository and is reviewed like code. The trade is that it refuses more: it requires the `state_version` you last read (so a tenant that moved underneath you is a refusal, not a silent overwrite), it lints the whole plan before executing any of it, and it is **not open by default** — it needs an *apply grant*, issued per (person, organisation) and revocable. Being an org admin on your own tenant is deliberately not enough. Talk to Bricks sales about a grant; the work of *producing* the manifest happens on your own IDE assistant's account.

Neither path is the default. Your assistant chooses per problem: the Studio when the shape is still being worked out or the change spans the backend and the app's files, a manifest when the spec can already be written down. Mixing them has one risk: a manifest declares an artefact as its spec states it, so one written from an older copy undoes the Studio's later edits to that artefact (a table only ever gains columns; a workflow's graph is replaced whole). Read the artefact's current version before declaring it.

In the Studio, a turn is one problem with everything it needs, not one edit: every turn re-reads the conversation's carried context, so many small turns cost more than one. Clear that context (`studio_clear_context`, or the clear control in the Studio) when moving on to an unrelated problem; no message is deleted.

## Who can use it

- **Getting the prompt** requires being an **org admin** on the target tenant (or a platform admin). The prompt exposes app-upload and role-management surfaces that need admin rights downstream, so a lower-privileged caller would only hit a wall of refusals later — the endpoint refuses early instead.
- **Applying a manifest** requires an **apply grant** (or platform admin). The grant is what makes the declarative path a commercial arrangement rather than a self-serve one. Creating a *new* empty tenant to apply into additionally requires a **signed-in user**: integrator keys are refused there by design, because a key acts inside the tenant it was issued for.
- **The conversational path authenticates with the developer's own integrator key**, minted at Account → Integrator. A *tenant* API key is a separate, server-side credential — it is not part of this flow and never belongs in an app.

## Uploading the app

The conformed app is uploaded as a multipart file tree — `POST /v2/tenants/:tenantId/apps` to create the app, `PUT /v2/tenants/:tenantId/apps/:appId` to replace its files. Both accept an org admin, a platform admin or an integrator the organisation appointed. Upload the **source** the platform builds, not your local install: a tree containing a `node_modules` path anywhere — including inside an uploaded zip — is refused with `400` and `{"error": "node_modules_in_bundle", "message": "node_modules/ must not be in the bundle (found \"…\") — your build step should exclude it"}`. Exclude it in the step that packs the upload and send again.

## How Brickify is paid for

The Brickify flow separates *generating instructions* (free) from *doing the work* (metered). Here is exactly where money enters:

| Step | Cost |
|---|---|
| Getting the Brickify prompt | **Free** — it only renders text |
| Applying a manifest | **Free of Bricks Tokens** — no model runs; gated on an apply grant |
| Minting / using a tenant API key | **Free** |
| **Each conversational Studio AI turn** | **Costs Bricks Tokens** |

So the only metered part is the conversational path, at the same rates whether your IDE assistant drives it or a human types it in the Studio. The declarative path is not metered per token; it is gated per grant.

> **An AI assistant can cost a lot more than a person.** The rates are the same, but IDE assistants are very verbose: they write long messages, paste large amounts of code and logs, and split work into many turns. A turn is priced on everything it reads and writes, including the conversation's carried context, so the same migration can use far more Bricks Tokens when an assistant drives it. Ask your assistant to send short messages and to group each problem into one turn, clear the context between unrelated problems, and watch the organisation's balance during the first turns.

### How a Studio AI turn is priced

Bricks meters AI usage in **Bricks Tokens (BT)**, where **1 € = 100 BT**. A turn is priced from the model's real token usage, not a flat fee:

```mermaid
flowchart TD
    A["Studio AI turn completes"] --> B["Model reports token usage<br/>(input, output, cache-write, cache-read)"]
    B --> C["Look up the live pricing matrix<br/>for this provider · model · operation"]
    C --> D["Price each token bucket at its own rate<br/>(cache reads are much cheaper)"]
    D --> E["Sum → Bricks Tokens charged"]
    E --> F["Resolve who pays (the billing principal)"]
    F --> G{"Billing mode?"}
    G -->|tenant wallet| H["Debit the organisation's balance"]
    G -->|integrator wallet| I["Debit the acting user's balance"]
    G -->|exempt| J["Zero-amount audit record"]
    H --> K["Ledger entry written"]
    I --> K
    J --> K
```

The pricing matrix is the single source of truth: each row prices a model's token buckets, and cheaper buckets (like cache reads) flow through as genuine savings. Every charge is written to a ledger, so spend is auditable per tenant and per call.

### Who pays

The payer is decided **only** by the tenant and the acting user — never by *how* the request authenticated. This is a deliberate guarantee: the transport can't change who pays.

- **Default — the tenant wallet.** The organisation's BT balance pays; the org admin tops it up and sees the spend.
- **Integrator wallet.** Only if the org explicitly set a per-user directive — then the acting user's own balance pays.
- **Exempt.** Certain tenants or admin-granted directives make usage free; it is still recorded as a zero-amount audit row. Being a platform admin does **not** by itself make usage free.

An integrator key changes *who is acting*, but its owner is the same person for billing purposes — so authenticating with a key never quietly shifts the bill.

## Worth knowing

- **The integrator key is a credential, not a payment method.** It never changes the cost or the payer.
- **The prompt always uses your externally reachable base URL**, so the instructions your IDE assistant follows point at real, callable endpoints.
- **Pricing today is pay-as-you-go BT.** The self-serve beta runs on a metered token balance; a fully token-free programmatic tenant declaration is a sales conversation, not a self-serve button yet.

---

*This page describes shipped behavior. For how the conversational path works from the inside, see [Studio AI tools](/technical/studio-ai-tools). For the wallet and pricing model in general, Bricks Tokens are the same currency across all AI usage on the platform.*
