Back to Build

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.

Free. Build doesn't charge per call, and your agent runs on the plan you already have with it.

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

MethodPathScopeNotes
GET/api/v1/meprofile:readVerify token, return your profile with your jobs, education and skills (and their ids).
PATCH/api/v1/meprofile:writeEdit 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/experiencesprofile:writeAdd 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:writeEdit or remove one of your jobs.
POST/api/v1/me/educationsprofile:writeAdd a school or trade program: school, degree, field_of_study, start_year, end_year.
PATCH · DELETE/api/v1/me/educations/<id>profile:writeEdit or remove one of your education entries.
PUT/api/v1/me/skillsprofile:writeReplace your skills list: { "skills": [...] }. Skills you keep keep their endorsements.
GET/api/v1/artifactsprofile:readList your recent artifacts.
POST/api/v1/artifactsartifacts:writeCreate artifact + first version (+ optional post).
POST/api/v1/postsposts:writeCreate 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/projectsanyYour projects: next update number, milestone progress, next milestone.
POST/api/v1/projectsposts:writeStart a project with a brief and milestones.
GET/api/v1/projects/<id>anyOne project with milestones and recent updates.
PATCH/api/v1/projects/<id>posts:writeEdit a project; { "status": "completed" } marks it finished.
PATCH/api/v1/milestones/<id>posts:writeRename a milestone or tick it by hand: { "title", "done" }.
POST/api/v1/projects/<id>/milestonesposts:writeAppend milestones: { "titles": [...] }.
GET/api/v1/models/kindspublic3D models you can generate (structural frame, stair, railing, canopy, fence), with parameters and defaults.
POST/api/v1/modelsposts:writeMake a frame, stair, railing, canopy or fence and post it as a 3D update people can watch go up.
GET/api/v1/docs/kindsdocs:readDocuments 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:readYour 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:templatesAdmins/owners: change the draft overrides (JSON merge patch), or { "reset_brand": true }.
POST/api/v1/docs/templates/<kind>/publishdocs:templatesAdmins/owners: publish the draft overrides.
GET/api/v1/docs/jobs?q=docs:readYour company's jobs (active first) to file a document on.
GET/api/v1/docs/<kind>?job=docs:readDocuments of a kind, newest first.
POST/api/v1/docs/<kind>docs:writeCreate 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:readThe document and its checks: ready, issues, suggestions.
POST/api/v1/docs/<kind>/<id>/previewdocs:writeMake the draft's PDF; returns a 10-minute link. Nothing is ever sent from the API.
GET/api/v1/limitsanyThis connection's rate limits and what's left right now.
GET/embed/artifact/<id>publicPublic 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 ids
  • build_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 finished
  • build_add_milestones / build_update_milestone — add, rename, tick or untick milestones
  • build_upload_file — upload a file, drafted as a project update unless you say not to
  • build_post_artifact / build_list_artifacts — save runnable HTML/React/Vue/Markdown, with a draft update that shows it
  • build_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 update
  • build_post_feed — draft a quick post with no project
  • build_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 apprenticeships
  • build_set_skills — replace the skills list friends endorse
  • build_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 publish
  • build_api_request — any other /api/v1 endpoint (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.