Build API
Connect the agent you already use (Claude, ChatGPT, Codex, Cursor and others) to your Build account through Build's MCP server, then post projects, updates, 3D models and company documents from it. Scripts and clients that can't sign in use a personal token, further down.
1. Connect your agent through Build's MCP
Build runs its MCP server at https://www.builderslive.org/mcp (Streamable HTTP). One connection covers projects, posts, company records, and the 3D model and live-takeoff tools. Add it as a custom connector in Claude or ChatGPT, in Antigravity, or from a CLI, and sign in with your Build account when asked. Nothing to install and no token to copy; turn the connection off any time in Settings, where its limits show too.
# Claude Code (then run /mcp to sign in)
claude mcp add --scope user --transport http build https://www.builderslive.org/mcp
# Antigravity (IDE and CLI): … › MCP Servers › Manage MCP Servers › View raw config
# (~/.gemini/config/mcp_config.json). It opens Build to sign in.
{ "mcpServers": { "build": { "serverUrl": "https://www.builderslive.org/mcp" } } }
# Codex CLI (then: codex mcp login build)
codex mcp add build --url https://www.builderslive.org/mcp
# Any client that takes a header instead of signing in (a personal token, step 2)
Authorization: Bearer build_pat_…Each connection is limited to 60 requests a minute, 30 drafts and posts an hour and 500 MB of uploads a day. Over a limit, the API answers 429 with Retry-After and a message saying when it resets; GET /api/v1/limits shows what's left.
2. Personal tokens, for scripts
A token is a credential for your Build account (like a GitHub personal access token). Visit /settings/api-tokens and mint one. The token is shown once: copy it into your script's or agent's environment as BUILD_API_TOKEN. Then check it:
curl https://www.builderslive.org/api/v1/me \ -H "Authorization: Bearer $BUILD_API_TOKEN"
3. Post a live artifact
Code an HTML or React sandbox, ship it to your feed, share the link. One request.
curl -X POST https://www.builderslive.org/api/v1/artifacts \
-H "Authorization: Bearer $BUILD_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"title": "Spinning HSS Picket Rail",
"description": "Three.js procedural rail with finish picker.",
"sandbox_type": "html",
"content": "<!doctype html>… your full HTML …",
"ai_provider": "claude",
"ai_model": "claude-opus-4-7",
"also_post": {
"post_type": "3d",
"tech_stack": ["Three.js","HSS","Ornamental"],
"visibility": "public"
}
}'Response includes both the artifact URL and (if you set also_post) the live post URL.
4. Plain feed post
curl -X POST https://www.builderslive.org/api/v1/posts \
-H "Authorization: Bearer $BUILD_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"project_name": "Field install — 16th & Mission",
"description": "Wrapped the cap rail today.",
"post_type": "milestone",
"tech_stack": ["Field","Install"]
}'4b. Post the next update to a project
Posts with a project_id become that project's next numbered update (“Update #N”). Find the id and milestone ids with GET /api/v1/projects and GET /api/v1/projects/<id>. Ticking milestones moves the project's progress.
curl -X POST https://www.builderslive.org/api/v1/posts \
-H "Authorization: Bearer $BUILD_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"project_id": "<project uuid>",
"project_name": "Frame welded",
"description": "All four corners square within 2 mm.",
"post_type": "image",
"asset_url": "https://…/frame.jpg",
"feedback_ask": "Is the gusset spacing overkill?",
"complete_milestone_ids": ["<milestone uuid>"]
}'4c. Fill out your profile
Your assistant can fill out your profile too: bio, headline, trade, jobs, education and skills. Unlike posts, these aren't drafts: they show on your profile as soon as they're saved. GET /api/v1/me returns the profile with the ids of your jobs and education; send only the fields you want to change.
curl -X PATCH https://www.builderslive.org/api/v1/me \
-H "Authorization: Bearer $BUILD_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "headline": "Structural welder, AWS D1.1", "trade": "welder", "years_in_trade": 12 }'
curl -X POST https://www.builderslive.org/api/v1/me/experiences \
-H "Authorization: Bearer $BUILD_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "title": "Foreman", "company_name": "New Steel", "start_date": "2021-03", "end_date": null }'Editing needs the profile:write scope. Connections made before it existed can still post; reconnect them in Settings to let them edit your profile.
5. Endpoints
| Method | Path | Scope | Notes |
|---|---|---|---|
| GET | /api/v1/me | profile:read | Verify token, return your profile with your jobs, education and skills (and their ids). |
| PATCH | /api/v1/me | profile:write | Edit your profile: display_name, bio, headline, location, website, trade, years_in_trade, tech_stack, is_open_to_collaborate, available_for_work, featured_project_id, header_model_name, header_model_project_id, anthem_caption. Live right away. |
| POST | /api/v1/me/experiences | profile:write | Add a job: title, company_name, start_date (YYYY-MM), end_date (null = still there), visibility (public, or private = only you). |
| PATCH · DELETE | /api/v1/me/experiences/<id> | profile:write | Edit or remove one of your jobs. |
| POST | /api/v1/me/educations | profile:write | Add a school or trade program: school, degree, field_of_study, start_year, end_year. |
| PATCH · DELETE | /api/v1/me/educations/<id> | profile:write | Edit or remove one of your education entries. |
| PUT | /api/v1/me/skills | profile:write | Replace your skills list: { "skills": [...] }. Skills you keep keep their endorsements. |
| GET | /api/v1/artifacts | profile:read | List your recent artifacts. |
| POST | /api/v1/artifacts | artifacts:write | Create artifact + first version (+ optional post). |
| POST | /api/v1/posts | posts:write | Create a post. With project_id it's the project's next numbered update; feedback_ask, complete_milestone_ids and ai_generated (“MCP assisted”) optional. |
| GET | /api/v1/projects | any | Your projects: next update number, milestone progress, next milestone. |
| POST | /api/v1/projects | posts:write | Start a project with a brief and milestones. |
| GET | /api/v1/projects/<id> | any | One project with milestones and recent updates. |
| PATCH | /api/v1/projects/<id> | posts:write | Edit a project; { "status": "completed" } marks it finished. |
| PATCH | /api/v1/milestones/<id> | posts:write | Rename a milestone or tick it by hand: { "title", "done" }. |
| POST | /api/v1/projects/<id>/milestones | posts:write | Append milestones: { "titles": [...] }. |
| GET | /api/v1/models/kinds | public | 3D models you can generate (structural frame, stair, railing, canopy, fence), with parameters and defaults. |
| POST | /api/v1/models | posts:write | Make a frame, stair, railing, canopy or fence and post it as a 3D update people can watch go up. |
| GET | /api/v1/docs/kinds | docs:read | Documents Build makes (RFI, change order request, product submittal, drawing transmittal, pay app) with a one-line purpose; your company and role. |
| GET | /api/v1/docs/templates/<kind> | docs:read | Your company's effective template: sections, field JSON Schema with descriptions and examples, rules, settings, brand colors (and where each came from), overrides. |
| PATCH | /api/v1/docs/templates/<kind> | docs:templates | Admins/owners: change the draft overrides (JSON merge patch), or { "reset_brand": true }. |
| POST | /api/v1/docs/templates/<kind>/publish | docs:templates | Admins/owners: publish the draft overrides. |
| GET | /api/v1/docs/jobs?q= | docs:read | Your company's jobs (active first) to file a document on. |
| GET | /api/v1/docs/<kind>?job= | docs:read | Documents of a kind, newest first. |
| POST | /api/v1/docs/<kind> | docs:write | Create or update a DRAFT from fields: { "job" or "id", "fields" }. Checked first; if anything blocks, nothing is saved and you get field-level fixes (422). |
| GET | /api/v1/docs/<kind>/<id> | docs:read | The document and its checks: ready, issues, suggestions. |
| POST | /api/v1/docs/<kind>/<id>/preview | docs:write | Make the draft's PDF; returns a 10-minute link. Nothing is ever sent from the API. |
| GET | /api/v1/limits | any | This connection's rate limits and what's left right now. |
| GET | /embed/artifact/<id> | public | Public iframe-embeddable runner for the artifact. |
6. Local server and CLI, with a token
One file, /mcp/build-mcp.js, is both an MCP server and a command-line tool, so everything a token can create is available to any agent: projects, milestones, numbered updates, quick posts, file uploads and runnable artifacts. Install it once:
curl -fsSL https://www.builderslive.org/mcp/build-mcp.js -o ~/.local/bin/build chmod +x ~/.local/bin/build # Windows: node build-mcp.js <command> export BUILD_API_TOKEN=build_pat_…
Agents with MCP
# Claude Code
claude mcp add build --env BUILD_API_TOKEN=build_pat_… -- build
# Codex CLI — ~/.codex/config.toml
[mcp_servers.build]
command = "build"
env = { BUILD_API_TOKEN = "build_pat_…" }
# Cursor (~/.cursor/mcp.json), Windsurf, Cline, Continue — same JSON shape:
{ "mcpServers": { "build": { "command": "build", "env": { "BUILD_API_TOKEN": "build_pat_…" } } } }Tools your agent gets:
build_list_projects/build_get_project— find the project, its next update number and milestone idsbuild_post_update— draft the project's next update: what changed, a feedback question, milestones it completes. Drafts wait in the owner's Studio in the Build app until they post them.build_create_project/build_update_project— start a project with a brief and milestones; mark it finishedbuild_add_milestones/build_update_milestone— add, rename, tick or untick milestonesbuild_upload_file— upload a file, drafted as a project update unless you say not tobuild_post_artifact/build_list_artifacts— save runnable HTML/React/Vue/Markdown, with a draft update that shows itbuild_list_model_kinds/build_generate_model— generate a structural frame, stair, railing, canopy or fence (real section sizes, code checks, schedule) as a draft 3D updatebuild_post_feed— draft a quick post with no projectbuild_get_profile/build_update_profile— read and fill out the profile: bio, headline, trade, “Skills & tools”, “Currently building”. Unlike drafts, profile changes show right away.build_add_experience/build_update_experience/build_remove_experience— jobs on the profile (private = only you see it)build_add_education/build_update_education/build_remove_education— schools, trade programs and apprenticeshipsbuild_set_skills— replace the skills list friends endorsebuild_list_doc_kinds/build_get_doc_template/build_list_jobs— company documents for any trade: what Build makes, each template's fields, rules and example, and the job to file it on (hosted server)build_draft_document/build_check_document/build_preview_document— draft an RFI, change order request, product submittal or drawing transmittal, fix what the checks list, and preview the PDF. Drafts only: a person sends documents from the Build app.build_update_doc_template/build_publish_doc_template— company admins customize templates (brand colors, sections, wording, markup) as a draft, then publishbuild_api_request— any other/api/v1endpoint (local server only; it can't publish)build_who_am_i— sanity-check the token
Any agent with a shell
build projects build project create --name "Garage build" --milestone "Frame welded" --milestone "Wired" build post --project <id> --title "Frame welded" --body "Square within 2 mm" \ --feedback "Are the gussets overkill?" --complete <milestoneId> build upload ./render.png --project <id> --title "First render" --ai build artifact ./demo.html --title "Live demo" --project <id> build project finish <id> build profile set --headline "Structural welder" --trade welder --years 12 build job add --title "Foreman" --company "New Steel" --start 2021-03 build help # everything else; output is JSON
Give your agent the house rules too: save /agents.md as AGENTS.md or CLAUDE.md in your repo. Machine-readable reference: /api/v1/openapi.json.
7. Watch it land live
Open /settings/api-activity in another tab. Every call your agent makes streams in real-time over Supabase Realtime. Side-by-side with your editor it's genuinely magical.