AIBIMTool
Start Free Now

Developers

What the endpoints do

“Design a 7-story office building with a ground-floor lobby, café, and event space. Floors 2 through 4 are typical office floors around a central core with stairs, elevators, and restrooms…”

your brief
A brief in your own words. The agent asked three questions, proposed a five-task plan, and built it once approved.
Plan of Level 2 of the 7-storey office: central core, open workplaces, meeting rooms, private offices and focus booths with their areasGET /image?view=plan&storey=1
Level 2 as the engine draws it from the IFC: the core, open workplaces on the glass, meeting rooms, private offices and focus booths, each named and measured.
3D view of the 7-storey office the agent built
GET /ifc
The model this run produced, 1,065 elements on seven storeys. Grab it and turn it. Downloads as IFC4 for Revit, ArchiCAD, BlenderBIM or Tekla.
  • POST /api/v1/projectsMetered

    Start a new building from a brief. The agent works in the background; the reply is 202 with the project

  • GET /api/v1/projects/:idFree

    What the project is doing and waits for, the agent's reply, its questions or plan. ?wait=30 holds while it runs

  • POST /api/v1/projects/:id/messagesMetered

    The next message: answers to its questions, a change, the plan's go-ahead, or continue

  • GET /api/v1/projects/:id/ifcFree

    The model as an IFC4 file, as saved after the agent's last step

  • GET /api/v1/projects/:id/imageFree

    A PNG of the model: ?view=iso (3D), or ?view=plan&storey=1 (one storey, rooms named and measured)

  • POST /api/v1/projects/:id/stopFree

    Stop the running agent after the step it is on

  • GET /api/v1/projectsFree

    The account's projects, most recently changed first

  • DELETE /api/v1/projects/:idFree

    Delete a project with its model and chat

  • GET /api/v1/meFree

    Account, plan, credits left and how messages are charged

A message is charged for the AI it uses: 1 credit per $0.02, at most 150 credits per 8-minute segment, and a run that fails on our side is refunded in full. Nothing is priced differently for being called from code. The API, the CLI and the MCP server are part of Studio, which holds 50 projects.

Authentication

Every request carries a bearer token. Make one under API keys, or let the CLI mint one for you.

Authorization: Bearer aibim_sk_xxxxxxxxxxxxxxxx

Request and response

POST /api/v1/projects

Metered
1{
2 "message": "7-storey office: lobby, café, event space, central core",
3 "title": "Office, 7 storeys", // optional
4 "level": "medium" // easy | medium | high
5}
1{
2 "success": true,
3 "project": {
4 "id": "019cf06362ab4dac",
5 "title": "Office, 7 storeys",
6 "state": "running",
7 "next": "The agent is working. Poll again in 15-30 s.",
8 "elements": 0,
9 "creditsUsed": 0,
10 "viewerUrl": "https://aibimtool.com/model/019cf06362ab4dac"
11 }
12}

GET /api/v1/projects/:id

Free
1// While it waits for you (?wait=50 holds while it runs)
2{
3 "success": true,
4 "project": {
5 "id": "019cf06362ab4dac",
6 "state": "needs_answer",
7 "next": "Send the answers as the next message.",
8 "questions": [
9 { "header": "Floors 5-7",
10 "question": "What should floors 5-7 contain?",
11 "options": [
12 { "label": "Same typical office floors" },
13 { "label": "Offices plus a top-floor amenity" },
14 { "label": "Larger-tenant floors" } ] },
15 { "header": "Floor plate", … },
16 { "header": "Massing", … }
17 ],
18 "creditsUsed": 5
19 }
20}
1// Once it is done
2{
3 "success": true,
4 "project": {
5 "id": "019cf06362ab4dac",
6 "state": "ready",
7 "next": "Download the IFC, or send a change.",
8 "reply": "All five tasks are done. The model is a
9 7-storey office about 30 m tall …",
10 "plan": [ { "id": "1", "status": "completed",
11 "subject": "Set up program, storeys and
12 ground floor" }, … ],
13 "elements": 1065,
14 "creditsUsed": 71
15 }
16}

POST /api/v1/projects/:id/messages

Metered
1{ "message": "Floors 5-7: offices plus a top-floor
2 amenity. Floor plate: about 800 m². Massing:
3 rounded bar on a glazed plinth." }
4
5// the go-ahead for the agent's plan
6{ "approvePlan": true }
7
8// go on after a run stopped at its time limit
9{ "continue": true }
1{
2 "success": true,
3 "project": {
4 "id": "019cf06362ab4dac",
5 "state": "running",
6 "next": "The agent is working. Poll again in 15-30 s.",
7 "elements": 52
8 }
9}

What a project waits for

Every status carries a state and a next sentence saying what to send, so a client branches on one field.

  • running

    The agent is working. GET with ?wait=50 holds the answer until it changes.

  • needs_answer

    It asked questions (questions, each with options). Send the answers as a message.

  • needs_approval

    It proposed a plan (plan) for a large brief. Send approvePlan: true, or what to change.

  • needs_continue

    A long build stopped at its time limit and did not carry on by itself. Send continue: true.

  • ready

    Done. Download the IFC or a picture, or send a change.

  • out_of_credits

    The account ran out of credits. Nothing more runs until it is topped up.

  • failed

    The last run failed on our side and was refunded. Send the message again.

  • empty

    A project with nothing sent yet.

Following a run

The agent asks before it designs and plans before it builds anything large, as it does in the workspace. Answer it, approve the plan, and the model comes out at the end. Long builds run in eight-minute segments and carry on by themselves.

1API=https://aibimtool.com/api/v1; H="Authorization: Bearer $AIBIMTOOL_API_KEY"
2
3# 1. Brief in: the agent asks before it designs
4id=$(curl -sS $API/projects -H "$H" -H "Content-Type: application/json" \
5 -d '{"message":"Design a 7-story office building with a ground-floor lobby, café and event space …"}' \
6 | jq -r .project.id)
7curl -sS "$API/projects/$id?wait=50" -H "$H" | jq '.project.questions[].header'
8
9# 2. Answer, then approve the five-task plan it proposes
10curl -sS $API/projects/$id/messages -H "$H" -H "Content-Type: application/json" \
11 -d '{"message":"Offices plus a top-floor amenity. About 800 m². Rounded bar on a glazed plinth."}'
12curl -sS $API/projects/$id/messages -H "$H" -H "Content-Type: application/json" \
13 -d '{"approvePlan":true}'
14
15# 3. Model out: the IFC, and Level 2 to check it by
16curl -sS $API/projects/$id/ifc -H "$H" -o office.ifc
17curl -sS "$API/projects/$id/image?view=plan&storey=1" -H "$H" -o level-2.png

Errors

Every failure answers in the same shape, so one branch covers them all. A run that fails on our side is refunded; one you stop pays for the steps it took.

1{
2 "success": false,
3 "error": "no_credits",
4 "message": "The account is out of credits. Top up or subscribe at aibimtool.com/dashboard?view=plans."
5}
  • 401missing_api_key

    No Authorization header, or it is not a bearer token.

  • 401invalid_api_key

    The key is unknown, or it has been revoked.

  • 400missing_message

    No message, approvePlan or continue was sent, or the message is over 8,000 characters (message_too_long).

  • 402plan_required

    API, CLI and MCP access is part of the Studio plan; the account is on another one.

  • 403project_limit

    The account holds as many projects as its plan allows (Free 3, Starter 10, Studio 50). Delete one to make room.

  • 402no_credits

    The account is out of credits. Nothing ran.

  • 404not_found

    No project with that id on this account. A key reaches only its own account's projects.

  • 400bad_storey

    The plan asked for a storey the model does not have. The message lists the storeys it has.

  • 404no_model

    Nothing was built in the project yet, so there is no IFC or picture.

  • 409busy

    The agent is still working on this project. One run at a time; wait for the state to leave running.

  • 409no_plan

    approvePlan was sent, but no plan is waiting (nothing_to_continue is the same for continue).

  • 429rate_limited

    Over 60 requests, or 10 new runs, in 60s on this account. Retry-After says how long to wait.

  • 503daily_limit

    Today's capacity is used up. Try again tomorrow; nothing was charged.

  • 503engine_unavailable

    The BIM engine could not render the picture right now. Try again in a minute.

What the model is for

The 7-storey office in the AIBIMTool viewer: a rounded glass bar on a glazed plinth with timber fins, the entrance canopy, the sky lounge and the roof terrace
Real elements, not a mesh: walls, slabs, columns, curtain walls, doors, stairs, lifts and every room as an IfcSpace with its name and area, on named storeys. Link it into Revit, open it in ArchiCAD or BlenderBIM, and schedule it like any other model; or open it in the AIBIMTool viewer and keep changing it with the agent.

Built from a brief

Large buildings the agent designed from a few sentences, each one a real project with its real brief. The same agent answers the API and the MCP server.

Residential tower, 25 storeys the AIBIMTool agent built
Residential tower, 25 storeys3,844 elements · 188 apartments · pool deck on a 5-storey podium“Give me a big model of this site.” Three answers: a residential condominium, about 25 storeys, a podium with a slim rounded tower.
Office building, 7 storeys the AIBIMTool agent built
Office building, 7 storeys1,065 elements · 5,400 m² · lobby, café, event space, sky lounge“Design a 7-story office building with a ground-floor lobby, café, and event space…” Built from a five-task plan.
Office building, 4 storeys the AIBIMTool agent built
Office building, 4 storeys421 elements · L-plan with a curved glass corner · roof pavilionThe same office brief on a 1,419 m² plot: an L-plan covering about 55%, the entrance on the north-east frontage.
Office building, 3 storeys the AIBIMTool agent built
Office building, 3 storeys306 elements · 400 m² footprint · one tenant, open space“Chcem urobiť office building, tri poschodia.” Written in Slovak; the agent asked and answered in Slovak too.