API reference

BuildItOmi API

Omi can build anything. This API lets your code build, publish and run full-stack apps. Every example comes in curl, JavaScript and Python.

Introduction

The API speaks JSON over HTTPS. Send JSON bodies with Content-Type: application/json. Times are Unix milliseconds unless a field says otherwise.

Base URLhttps://api.builditomi.com/v1
Also workshttps://app.builditomi.com/api/v1 (the same API, for scripts made before 20 Nov 2026)
Statusstatus.builditomi.com
setup
export BUILDITOMI_KEY="bio_..."   # from api.builditomi.com/keys
export API="https://api.builditomi.com/v1"

SDKs

Official clients for JavaScript (npm install builditomi) and Python (pip install builditomi). They cover every endpoint below, stream builds, retry 429 for you and verify webhooks. Both read BUILDITOMI_KEY. Use them on your server only: never put an API key in a browser.

sdk
# JavaScript (Node 18+, Bun, Deno)
npm install builditomi

# Python 3.8+ (no dependencies)
pip install builditomi

export BUILDITOMI_KEY="bio_..."

Building an app builder of your own? Read Power your own app builder.

Authentication

Create a key at api.builditomi.com/keys. It starts with bio_ and is shown once, so keep it in your CI or server secrets, never in a browser or app. Send it on every request:

header
Authorization: Bearer bio_...
  • A key acts as you on your own apps. It can never change your account, billing, payouts or keys, or delete an app.
  • Your plan sets how many keys you can have: 1 on the free sandbox, 3 on Starter, 10 on Pro, unlimited on Scale. Revoke one any time; it stops on its next request.
  • Every account can make a key: it starts on the free sandbox. See pricing.

Scopes

Each key has scopes. A call without the scope it needs gets 401 naming the missing scope. Keys made before 20 Nov 2026 keep what they could always do: every scope below except secrets, domains and webhooks.

ScopeAllows
apps:readList apps, read an app, its versions and build progress.
apps:writeCreate apps from a prompt, change them, run builds, restore versions, publish and unpublish.
code:readRead every source file and download the project as a ZIP.
data:readRead the records in an app's database.
data:writeAdd, change and delete records in an app's database.
secrets:writeList, add and remove an app's server secrets (values are never returned). Off unless you tick it.
domains:writeConnect and disconnect an app's custom domain. Off unless you tick it.
aiCall the built-in AI (billed at its real model cost in credits).
usage:readSee credits, plan usage and each key's calls.
webhooksSet, test and remove the account's webhook. Off unless you tick it.

Rate limits

Each key has its own limit per minute (60 unless you choose) and a daily cap (UTC). Your plan sets the ceilings. Over either limit you get 429: wait a moment and retry. Builds also have their own hourly limits. The AI gateway allows up to 5,000 calls per account per day.

PlanKeysPer key, per minutePer key, per dayPublished appsCustom domainsWebhooks
Sandbox1up to 101,0001NoNo
Starter3up to 6020,00033No
Pro10up to 300100,0001010Yes
ScaleUnlimitedup to 1,000500,000100100Yes

Pricing

The API has its own plans and credits: a free sandbox, then Starter $9, Pro $29 or Scale $99 a month, and credit packs that never expire. See pricing.

Every call uses 1,000 credits. Builds, changes and AI gateway calls also use the credits their AI work really costs (shown in each reply), and each build step adds its server time (about 1,37,500 credits for a full 60-second step). Monthly plan credits are used first, then pack credits. When credits run out, calls return 402 until your plan refills or you add a pack. See your credits at GET /v1/usage (the api field) and per key at GET /v1/usage/keys. Every credit number the API returns is in the same credits you see on the site.

Errors

Errors return JSON like { "error": "What went wrong" } with one of these status codes:

StatusMeaning
400A value is missing or not valid. The error says which.
401The key is missing, wrong, revoked, or lacks the scope this endpoint needs.
402Your API credits are used up. Add a pack or move up a plan at api.builditomi.com/pricing.
403A plan limit was reached, such as the record limit.
404The app or record does not exist, or is not yours.
409Something is already running, such as another build on the same app.
429Too many requests for this key (per minute or per day). Wait and retry.
500Our side failed. Nothing was charged for the AI work. Retry, and check status.builditomi.com.

Apps

Create an app from a prompt, then run its build. Builds run in steps so no request runs longer than 60 seconds: call /step (JSON) or /stream (live events) until done is true.

List apps

GET/v1/appsapps:read

Your apps, newest first (up to 100), with your plan usage.

Request

curl "$API/apps" \
  -H "Authorization: Bearer $BUILDITOMI_KEY"

Response

{ "apps": [{ "id": "k3f9x2ab", "title": "Salon bookings", "published": true, "versions": 4, "building": false, "updatedAt": 1763600000000, "creditsUsed": 2.41 }], "trial": { … }, "usage": { … } }

Create an app

POST/v1/appsapps:write

Starts building a new app from a prompt. Apps and websites are React projects; pass "stack": "html" for a single HTML file. Returns at once: then run the build with /step or /stream.

Request

curl -X POST "$API/apps" \
  -H "Authorization: Bearer $BUILDITOMI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"A booking app for my salon with stylists, time slots and reminders"}'

Response

{ "id": "k3f9x2ab", "done": false, "steps": 0 }

Get an app

GET/v1/apps/{id}apps:read

Title, versions, whether it is building or published, and the chat history.

Request

curl "$API/apps/$APP_ID" \
  -H "Authorization: Bearer $BUILDITOMI_KEY"

Response

{ "id": "k3f9x2ab", "title": "Salon bookings", "building": false, "versions": 4, "published": true, "history": [ … ] }

Rename an app

PATCH/v1/apps/{id}apps:write

Changes the app's title.

Request

curl -X PATCH "$API/apps/$APP_ID" \
  -H "Authorization: Bearer $BUILDITOMI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Salon Bookings"}'

Response

{ "id": "k3f9x2ab", "title": "Salon Bookings" }

Run the next build step

POST/v1/apps/{id}/stepapps:write

Runs up to ~48 seconds of the build or change and returns. Call it again until done is true.

Request

curl -X POST "$API/apps/$APP_ID/step" \
  -H "Authorization: Bearer $BUILDITOMI_KEY"

Response

{ "done": false, "steps": 3 }   …   { "done": true, "title": "Salon bookings", "steps": 7 }

Stream a build step

POST/v1/apps/{id}/streamapps:write

Same as /step, as Server-Sent Events: progress shows what each AI agent is doing while the step runs. The last event is done, continue (call again) or error.

Request

curl -N -X POST "$API/apps/$APP_ID/stream" \
  -H "Authorization: Bearer $BUILDITOMI_KEY"

Response

event: progress
data: {"appId":"k3f9x2ab","agents":[{"role":"Builder","file":"src/App.tsx","status":"writing","chars":4120}]}

event: continue
data: {"appId":"k3f9x2ab","done":false,"steps":4}

Stop a build

DELETE/v1/apps/{id}/stepapps:write

Stops the running build or change. Work so far is kept.

Request

curl -X DELETE "$API/apps/$APP_ID/step" \
  -H "Authorization: Bearer $BUILDITOMI_KEY"

Response

{ "stopped": true }

Change or rebuild an app

POST/v1/apps/{id}/editapps:write

Asks Omi to change the app in plain words, like in the chat. Then run /step or /stream until done.

Request

curl -X POST "$API/apps/$APP_ID/edit" \
  -H "Authorization: Bearer $BUILDITOMI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"Add a contact form and send me an email for each message"}'

Response

{ "id": "k3f9x2ab", "done": false, "steps": 0 }

List versions

GET/v1/apps/{id}/versionsapps:read

Every version with the message that made it.

Request

curl "$API/apps/$APP_ID/versions" \
  -H "Authorization: Bearer $BUILDITOMI_KEY"

Response

{ "versions": [{ "version": 4, "at": 1763600000000, "current": true, "note": "Add a contact form" }] }

Restore a version

POST/v1/apps/{id}/versionsapps:write

Makes an earlier version the newest one.

Request

curl -X POST "$API/apps/$APP_ID/versions" \
  -H "Authorization: Bearer $BUILDITOMI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"version":3}'

Response

{ "ok": true, "version": 5 }

Publish

POST/v1/apps/{id}/publishapps:write

Puts the current version online at its link (and custom domain, if connected).

Request

curl -X POST "$API/apps/$APP_ID/publish" \
  -H "Authorization: Bearer $BUILDITOMI_KEY"

Response

{ "url": "https://builditomi.com/s/k3f9x2ab", "publishedAt": 1763600000000 }

Unpublish

DELETE/v1/apps/{id}/publishapps:write

Takes the app offline. Its data and versions stay.

Request

curl -X DELETE "$API/apps/$APP_ID/publish" \
  -H "Authorization: Bearer $BUILDITOMI_KEY"

Response

{ "ok": true }

Streaming events

POST /v1/apps/{id}/stream answers with text/event-stream. Each event has a name and one line of JSON:

EventWhen
startThe step began.
progressEvery ~2.5 s while something changes: each agent's role, model, file, status (thinking, writing, done, failed) and characters written.
continueThe step ended and the build is not finished. Call /stream again.
doneThe build is finished. Publish it, or read its code.
errorThe build stopped. The message says why; nothing more is charged.

Prefer no open connection? Set a webhook and get build.completed when it is done, while you drive the build with /step.

Code

Your code is yours. Read every file as JSON or download the whole project as a ZIP.

Read every file

GET/v1/apps/{id}/source?files=1code:read

Every source file of the project. Without ?files=1 you get the built page as text/html.

Request

curl "$API/apps/$APP_ID/source?files=1" \
  -H "Authorization: Bearer $BUILDITOMI_KEY"

Response

{ "stack": "react", "files": [{ "path": "src/App.tsx", "content": "…" }] }

Download as ZIP

GET/v1/apps/{id}/source?download=zipcode:read

The whole project as a .zip: every source file plus the built page.

Request

curl "$API/apps/$APP_ID/source?download=zip" \
  -H "Authorization: Bearer $BUILDITOMI_KEY" \
  -o app.zip

Response

application/zip (binary)

Data

Read and write an app's database as its owner. Records are JSON objects up to 20 KB; fields starting with _ and id, createdAt, updatedAt are set by the server. Writes count toward your plan's record limit.

List collections

GET/v1/apps/{id}/recordsdata:read

The app's collections and its total record count.

Request

curl "$API/apps/$APP_ID/records" \
  -H "Authorization: Bearer $BUILDITOMI_KEY"

Response

{ "appId": "k3f9x2ab", "collections": ["bookings", "stylists"], "records": 132 }

List records

GET/v1/apps/{id}/records/{collection}?limit=50data:read

Newest first, up to 200 per page (default 50). Page with ?before=<next>. Filter with ?where={"status":"paid"} (up to 3 fields, exact match).

Request

curl "$API/apps/$APP_ID/records/bookings?limit=50" \
  -H "Authorization: Bearer $BUILDITOMI_KEY"

Response

{ "records": [{ "id": "a1B2c3", "name": "Asha", "slot": "10:30", "createdAt": 1763600000000 }], "next": 1763590000000 }

Get a record

GET/v1/apps/{id}/records/{collection}?id=a1B2c3data:read

One record by its id.

Request

curl "$API/apps/$APP_ID/records/bookings?id=a1B2c3" \
  -H "Authorization: Bearer $BUILDITOMI_KEY"

Response

{ "record": { "id": "a1B2c3", "name": "Asha", "slot": "10:30" } }

Add a record

POST/v1/apps/{id}/records/{collection}data:write

Adds a record. Anyone watching the app sees it live.

Request

curl -X POST "$API/apps/$APP_ID/records/bookings" \
  -H "Authorization: Bearer $BUILDITOMI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Asha","slot":"10:30","stylist":"Ravi"}'

Response

{ "id": "a1B2c3" }

Change a record

PATCH/v1/apps/{id}/records/{collection}?id=a1B2c3data:write

Merges the fields you send into the record.

Request

curl -X PATCH "$API/apps/$APP_ID/records/bookings?id=a1B2c3" \
  -H "Authorization: Bearer $BUILDITOMI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"slot":"11:00"}'

Response

{ "ok": true }

Delete a record

DELETE/v1/apps/{id}/records/{collection}?id=a1B2c3data:write

Deletes one record.

Request

curl -X DELETE "$API/apps/$APP_ID/records/bookings?id=a1B2c3" \
  -H "Authorization: Bearer $BUILDITOMI_KEY"

Response

{ "ok": true }

Secrets

Server secrets are API keys your app calls other services with. Values are encrypted and never returned: only the name, host and last 4 characters.

List secrets

GET/v1/apps/{id}/keyssecrets:write

Names, hosts and last 4 characters.

Request

curl "$API/apps/$APP_ID/keys" \
  -H "Authorization: Bearer $BUILDITOMI_KEY"

Response

{ "secrets": [{ "name": "OPENWEATHER_KEY", "host": "api.openweathermap.org", "pathPrefix": "/", "last4": "9f2c" }] }

Add or replace a secret

POST/v1/apps/{id}/keyssecrets:write

Saves a secret the app can use only when calling this host. Up to 20 per app.

Request

curl -X POST "$API/apps/$APP_ID/keys" \
  -H "Authorization: Bearer $BUILDITOMI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"OPENWEATHER_KEY","value":"<your secret>","host":"api.openweathermap.org"}'

Response

{ "secrets": [ … ] }

Remove a secret

DELETE/v1/apps/{id}/keys?name=OPENWEATHER_KEYsecrets:write

Deletes a secret by name.

Request

curl -X DELETE "$API/apps/$APP_ID/keys?name=OPENWEATHER_KEY" \
  -H "Authorization: Bearer $BUILDITOMI_KEY"

Response

{ "secrets": [ … ] }

Domains

Connect your own domain to a published app. Add the DNS records the status lists at your registrar; HTTPS is set up for you.

Domain status

GET/v1/apps/{id}/domaindomains:write

The connected domain, the DNS records it needs and whether they are found.

Request

curl "$API/apps/$APP_ID/domain" \
  -H "Authorization: Bearer $BUILDITOMI_KEY"

Response

{ "published": true, "status": { "name": "book.mysalon.com", "state": "pending", "records": [ … ] } }

Connect a domain

POST/v1/apps/{id}/domaindomains:write

Connects a domain (replacing any connected one).

Request

curl -X POST "$API/apps/$APP_ID/domain" \
  -H "Authorization: Bearer $BUILDITOMI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"book.mysalon.com"}'

Response

{ "published": true, "status": { … } }

Disconnect

DELETE/v1/apps/{id}/domaindomains:write

Removes the custom domain. The app's own link keeps working.

Request

curl -X DELETE "$API/apps/$APP_ID/domain" \
  -H "Authorization: Bearer $BUILDITOMI_KEY"

Response

{ "status": null }

AI gateway

The same built-in AI your apps use, from your own code. No model keys to manage. "fast" (default) is the cheaper model, "standard" the stronger one. Each call is billed at its real model cost in credits, shown in usage.credits.

Chat

POST/v1/ai/chatai

Send messages (ending with a user message), get a reply. Up to 24,000 characters in and 2,048 tokens out. Set json: true for a JSON answer.

Request

curl -X POST "$API/ai/chat" \
  -H "Authorization: Bearer $BUILDITOMI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"fast","system":"You write short product descriptions.","messages":[{"role":"user","content":"A handmade clay mug, 350 ml, blue glaze"}],"max_tokens":300}'

Response

{ "model": "fast", "reply": "…", "finish": "stop", "usage": { "inputTokens": 31, "outputTokens": 84, "credits": 18100 } }

Usage and credits

The API has its own plan and credits (api.builditomi.com/pricing). Check them before a big job.

Credits and plan

GET/v1/usageusage:read

Your API plan, credits left, and credits spent per day split into plain calls, AI work and build time (?days= up to 31). Credits are in the same units the site shows.

Request

curl "$API/usage" \
  -H "Authorization: Bearer $BUILDITOMI_KEY"

Response

{ "api": { "plan": "api_pro", "planName": "API Pro", "renewsAt": 1766188800000, "creditsLeft": "14,21,30,000", "planCredits": "15,00,00,000", "planCreditsUsed": "78,70,000", "packCredits": "0" }, "spend": [{ "day": "2026-11-20", "calls": 42000, "ai": 3120000, "buildTime": 412000, "total": 3574000 }] }

Usage per key

GET/v1/usage/keysusage:read

Each key's calls and credits per day and per endpoint, for the last 14 days (?days= up to 31).

Request

curl "$API/usage/keys" \
  -H "Authorization: Bearer $BUILDITOMI_KEY"

Response

{ "keys": [{ "id": "3fa1c09b77d2e410", "name": "CI", "scopes": ["apps:read"], "rpm": 60, "days": [{ "day": "2026-11-20", "calls": 42, "credits": 42000, "routes": { "GET /apps": 40, "POST /apps/{id}/publish": 2 } }] }] }

Webhooks

Get a POST when a build finishes, fails, or an app is published or unpublished: no polling. One webhook per account, https only. Each request is signed (see Verify a webhook).

Get the webhook

GET/v1/webhookswebhooks

The URL, its events and the last delivery.

Request

curl "$API/webhooks" \
  -H "Authorization: Bearer $BUILDITOMI_KEY"

Response

{ "webhook": { "url": "https://example.com/hooks/builditomi", "events": ["build.completed", "build.failed"], "secretHint": "whsec_AbC1…", "last": { "event": "build.completed", "status": 200, "ok": true } } }

Set the webhook

PUT/v1/webhookswebhooks

Saves the URL and events. The signing secret is returned in full only here; it stays the same when you change the URL.

Request

curl -X PUT "$API/webhooks" \
  -H "Authorization: Bearer $BUILDITOMI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hooks/builditomi","events":["build.completed","build.failed","app.published"]}'

Response

{ "webhook": { … }, "secret": "whsec_…" }

Send a test event

POST/v1/webhooks/testwebhooks

Sends a signed sample build.completed event and says what your endpoint answered.

Request

curl -X POST "$API/webhooks/test" \
  -H "Authorization: Bearer $BUILDITOMI_KEY"

Response

{ "delivered": true, "status": 200 }

Remove the webhook

DELETE/v1/webhookswebhooks

Stops all deliveries.

Request

curl -X DELETE "$API/webhooks" \
  -H "Authorization: Bearer $BUILDITOMI_KEY"

Response

{ "ok": true }

Verify a webhook

Each delivery is a POST with a JSON body, the header X-BuildItOmi-Event, and X-BuildItOmi-Signature: t=<unix seconds>,v1=<signature>. The signature is the hex HMAC-SHA256 of <t>.<raw body> using your whsec_ secret. Check it, reject anything older than 5 minutes, then answer 2xx within 5 seconds. Deliveries are not retried, so use GET /v1/apps/{id} as the source of truth.

{
  "id": "evt_Qm8r2Xn0aB7c",
  "type": "build.completed",
  "created": 1763600000,
  "data": { "appId": "k3f9x2ab", "title": "Salon bookings" }
}
verify
# Webhooks are verified in your server code (JavaScript or Python tab).
# Each delivery is a POST with these headers:
#   X-BuildItOmi-Event: build.completed
#   X-BuildItOmi-Signature: t=1763600000,v1=<hex HMAC-SHA256 of "<t>.<raw body>" with your whsec_ secret>

Events: build.completed, build.failed, app.published, app.unpublished.