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.
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.
Scope
Allows
apps:read
List apps, read an app, its versions and build progress.
apps:write
Create apps from a prompt, change them, run builds, restore versions, publish and unpublish.
code:read
Read every source file and download the project as a ZIP.
data:read
Read the records in an app's database.
data:write
Add, change and delete records in an app's database.
secrets:write
List, add and remove an app's server secrets (values are never returned). Off unless you tick it.
domains:write
Connect and disconnect an app's custom domain. Off unless you tick it.
ai
Call the built-in AI (billed at its real model cost in credits).
usage:read
See credits, plan usage and each key's calls.
webhooks
Set, 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.
Plan
Keys
Per key, per minute
Per key, per day
Published apps
Custom domains
Webhooks
Sandbox
1
up to 10
1,000
1
No
No
Starter
3
up to 60
20,000
3
3
No
Pro
10
up to 300
100,000
10
10
Yes
Scale
Unlimited
up to 1,000
500,000
100
100
Yes
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:
Status
Meaning
400
A value is missing or not valid. The error says which.
401
The key is missing, wrong, revoked, or lacks the scope this endpoint needs.
402
Your API credits are used up. Add a pack or move up a plan at api.builditomi.com/pricing.
403
A plan limit was reached, such as the record limit.
404
The app or record does not exist, or is not yours.
409
Something is already running, such as another build on the same app.
429
Too many requests for this key (per minute or per day). Wait and retry.
500
Our 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.
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.
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"
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"}'
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.
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}'
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.
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).
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.
# 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>