BuilderComs tools & API
MCP · REST v1 · Incoming webhooks
Tools & endpoint explorer
13 MCP tools · 14 API operationsUsed only in request headers. Not saved, copied into examples or shared with another host. Account login tokens are not accepted. MCP requires OAuth.
Loading current app address…Tests use this app, not a mock. Code samples use web.buildercoms.com. Publish changes before testing on the production address.
Test company REST key connection
/connectionTest company REST key connection
curl -X GET 'https://web.buildercoms.com/api/public/v1/connection' \
-H 'Accept: application/json' \
-H "Authorization: Bearer $BUILDERCOMS_ACCESS_TOKEN"Parameters & response contract
{
"parameters": [],
"request": null,
"responses": {
"200": {
"description": "Authorized records",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"data": {
"type": "object",
"additionalProperties": false,
"properties": {
"connected": {
"const": true
},
"company_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"access_mode": {
"type": "string",
"enum": [
"read",
"write"
]
}
},
"required": [
"connected",
"company_id",
"name",
"access_mode"
]
}
},
"required": [
"data"
]
}
}
}
},
"400": {
"description": "Invalid input",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Missing/expired/invalid OAuth token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Grant, subscription, permission or limit denied",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Missing or inaccessible resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"405": {
"description": "Unsupported method",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "Body exceeds 32 KiB",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"415": {
"description": "Requires application/json",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Internal failure",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Temporary failure",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}Shared request and response schemas
{
"WebhookEvent": {
"oneOf": [
{
"type": "object",
"additionalProperties": false,
"properties": {
"event_id": {
"type": "string",
"format": "uuid"
},
"event": {
"const": "job.created"
},
"data": {
"$ref": "#/components/schemas/CreateJob"
}
},
"required": [
"event_id",
"event",
"data"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"event_id": {
"type": "string",
"format": "uuid"
},
"event": {
"const": "job.updated"
},
"data": {
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"type": "string",
"maxLength": 150
},
"address": {
"type": "string",
"minLength": 1,
"maxLength": 500
},
"client_name": {
"type": "string",
"minLength": 1,
"maxLength": 150
},
"client_email": {
"type": "string",
"maxLength": 254,
"description": "Email address or empty string"
},
"client_phone": {
"type": "string",
"maxLength": 40
},
"project_type": {
"type": "string",
"maxLength": 100
},
"description": {
"type": "string",
"maxLength": 5000
},
"start_date": {
"type": "string",
"description": "YYYY-MM-DD or empty string"
},
"end_date": {
"type": "string",
"description": "YYYY-MM-DD or empty string; not before start_date"
},
"site_notes": {
"type": "string",
"maxLength": 3000
},
"job_id": {
"type": "string",
"format": "uuid"
}
},
"required": [
"job_id",
"name",
"address",
"client_name"
]
}
},
"required": [
"event_id",
"event",
"data"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"event_id": {
"type": "string",
"format": "uuid"
},
"event": {
"const": "job.status_changed"
},
"data": {
"type": "object",
"additionalProperties": false,
"properties": {
"job_id": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string",
"enum": [
"active",
"completed"
]
}
},
"required": [
"job_id",
"status"
]
}
},
"required": [
"event_id",
"event",
"data"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"event_id": {
"type": "string",
"format": "uuid"
},
"event": {
"const": "task.created"
},
"data": {
"type": "object",
"additionalProperties": false,
"properties": {
"job_id": {
"type": "string",
"format": "uuid"
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"due_date": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
}
},
"required": [
"job_id",
"title"
]
}
},
"required": [
"event_id",
"event",
"data"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"event_id": {
"type": "string",
"format": "uuid"
},
"event": {
"const": "task.updated"
},
"data": {
"type": "object",
"additionalProperties": false,
"properties": {
"job_id": {
"type": "string",
"format": "uuid"
},
"task_id": {
"type": "string",
"format": "uuid"
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"due_date": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
}
},
"required": [
"job_id",
"task_id",
"title"
]
}
},
"required": [
"event_id",
"event",
"data"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"event_id": {
"type": "string",
"format": "uuid"
},
"event": {
"const": "task.completion_changed"
},
"data": {
"type": "object",
"additionalProperties": false,
"properties": {
"job_id": {
"type": "string",
"format": "uuid"
},
"task_id": {
"type": "string",
"format": "uuid"
},
"done": {
"type": "boolean"
}
},
"required": [
"job_id",
"task_id",
"done"
]
}
},
"required": [
"event_id",
"event",
"data"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"event_id": {
"type": "string",
"format": "uuid"
},
"event": {
"const": "message.sent"
},
"data": {
"type": "object",
"additionalProperties": false,
"properties": {
"job_id": {
"type": "string",
"format": "uuid"
},
"body": {
"type": "string",
"minLength": 1,
"maxLength": 10000
},
"audience": {
"type": "string",
"enum": [
"team",
"client"
]
},
"channel_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"client_link_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"parent_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"job_id",
"body",
"audience"
],
"description": "Preserve exact Team/Client and parent scope."
}
},
"required": [
"event_id",
"event",
"data"
]
}
],
"description": "One event per request. event_id replaces Idempotency-Key; retry with identical event and data. Owner-authorized OAuth or company REST key required."
},
"CreateJob": {
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"type": "string",
"maxLength": 150
},
"address": {
"type": "string",
"minLength": 1,
"maxLength": 500
},
"client_name": {
"type": "string",
"minLength": 1,
"maxLength": 150
},
"client_email": {
"type": "string",
"maxLength": 254,
"description": "Email address or empty string"
},
"client_phone": {
"type": "string",
"maxLength": 40
},
"project_type": {
"type": "string",
"maxLength": 100
},
"description": {
"type": "string",
"maxLength": 5000
},
"start_date": {
"type": "string",
"description": "YYYY-MM-DD or empty string"
},
"end_date": {
"type": "string",
"description": "YYYY-MM-DD or empty string; not before start_date"
},
"site_notes": {
"type": "string",
"maxLength": 3000
}
},
"required": [
"address",
"client_name"
]
},
"JobSummary": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"address": {
"type": "string"
},
"client_name": {
"type": "string"
},
"status": {
"type": "string"
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"name",
"address",
"client_name",
"status",
"created_at"
]
},
"Job": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"address": {
"type": "string"
},
"client_name": {
"type": "string"
},
"status": {
"type": "string"
},
"description": {
"type": "string"
},
"project_type": {
"type": "string"
},
"start_date": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"end_date": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"site_notes": {
"type": "string"
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"name",
"address",
"client_name",
"status",
"description",
"project_type",
"start_date",
"end_date",
"site_notes",
"created_at"
]
},
"TaskInput": {
"type": "object",
"additionalProperties": false,
"properties": {
"title": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"due_date": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
}
},
"required": [
"title"
]
},
"Task": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"job_id": {
"type": "string",
"format": "uuid"
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"due_date": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"done": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"job_id",
"title",
"done",
"due_date",
"created_at"
]
},
"MessageInput": {
"type": "object",
"additionalProperties": false,
"properties": {
"body": {
"type": "string",
"minLength": 1,
"maxLength": 10000
},
"audience": {
"type": "string",
"enum": [
"team",
"client"
]
},
"channel_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"client_link_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"parent_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"body",
"audience"
],
"description": "Client requires client_link_id and no channel_id. Team forbids client_link_id; null channel_id is General. Replies must match root audience/channel/link. Do not include job_id; URL defines it."
},
"Message": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"job_id": {
"type": "string",
"format": "uuid"
},
"body": {
"type": "string",
"minLength": 1,
"maxLength": 10000
},
"audience": {
"type": "string",
"enum": [
"team",
"client"
]
},
"channel_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"client_link_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"parent_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"author_name": {
"type": "string"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"edited_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"job_id",
"body",
"audience",
"channel_id",
"client_link_id",
"parent_id",
"author_name",
"created_at",
"edited_at"
]
},
"Conversation": {
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"type": "string"
},
"audience": {
"type": "string",
"enum": [
"team",
"client"
]
},
"channel_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"client_link_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"name",
"audience",
"channel_id",
"client_link_id"
]
},
"ActionResult": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"kind": {
"type": "string",
"enum": [
"create_job",
"update_job_details",
"update_job_status",
"create_task",
"update_task",
"complete_task",
"send_message"
]
},
"status": {
"const": "succeeded"
},
"action_id": {
"type": "string",
"format": "uuid"
},
"agent_name": {
"type": "string"
}
},
"required": [
"id",
"kind",
"status",
"action_id",
"agent_name"
]
},
"Error": {
"type": "object",
"additionalProperties": false,
"properties": {
"error": {
"type": "object",
"additionalProperties": false,
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"path": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"path",
"message"
]
}
}
},
"required": [
"code",
"message"
]
}
},
"required": [
"error"
]
}
}Connect REST with a company API key
- The company owner opens Settings → Integrations → Developer portal, names a connection and selects Read only or Read & write.
- Create the key and copy it once into your external tool’s secure credential settings. It expires after 90 days; create a replacement and revoke the old key to rotate it.
- Send
Authorization: Bearer YOUR_COMPANY_KEY. Test withGET /api/public/v1/connectionor the portal’s Test connection button.
Keys remain company-scoped. Read & write permits direct updates with existing subscription, exact-conversation and retry checks. Revocation ends access immediately. Company keys cannot connect MCP agents.
Open developer portalConnection and authorization
MCP server: https://web.buildercoms.com/mcp. Assistants discover tools with tools/list, then invoke tools/call. All 13 tools are listed above; prepare tools require a person’s approval, and only three MCP tools write directly. REST exposes task writes separately.
Base address: https://web.buildercoms.com/api/public/v1. Publish API changes before using this address.
- Read OAuth resource metadata. Load authorization-server discovery from its authorization server.
- Register your tool at the discovered
registration_endpoint, with its name, exact HTTPS redirect URI,grant_types: ["authorization_code", "refresh_token"],response_types: ["code"]andtoken_endpoint_auth_method: "none". - Open the discovered authorization endpoint with
client_id, registeredredirect_uri,response_type=code, randomstate,code_challengeandcode_challenge_method=S256. The company owner signs in, names the integration and selects access. - Validate callback state. Exchange the code at the discovered token endpoint with
grant_type=authorization_code, the sameclient_id,redirect_uriand originalcode_verifier. Refresh there withgrant_type=refresh_token; securely store and replace rotated tokens. - Use
Authorization: Bearer …with the resulting OAuth access token. Account-session tokens are not accepted. REST tools may instead use an owner-created company API key from the Developer portal; MCP requires OAuth. Revoke access from Settings at any time.
Active named owner authorization is required for reads. Review changes is read-only in REST; existing MCP prepare tools support human-reviewed drafts. Direct writes require Read & write and an active company subscription. Company and identity come from the verified token, never submitted fields.
Endpoints
/connectionTest company REST key connection
/webhooks/updatesReceive an incoming job, status, task or reply event
/jobsList authorized jobs
/jobsCreate a job
/jobs/{job_id}/detailsReplace job details
/jobs/{job_id}Read job details
/jobs/{job_id}Set job status
/jobs/{job_id}/tasksList job tasks
/jobs/{job_id}/tasksCreate a task
/jobs/{job_id}/tasks/{task_id}Replace task title and due date
/jobs/{job_id}/tasks/{task_id}/completionComplete or reopen task
/jobs/{job_id}/conversationsDiscover authorized Team channels and Client conversation IDs
/jobs/{job_id}/messagesRead conversation roots or exact-thread replies
/jobs/{job_id}/messagesSend exact Team or Client message
OpenAPI documents request fields and response schemas. Collections accept limit (1–100; default 25) and before from page.next_cursor. Continue until null. Ordering is stable descending UUID, not chronological; sort messages by created_at for display.
Read jobs
curl 'https://web.buildercoms.com/api/public/v1/jobs?limit=25' \
-H "Authorization: Bearer $BUILDERCOMS_ACCESS_TOKEN"{
"data": [
{
"id": "123e4567-e89b-42d3-a456-426614174000",
"name": "Framing inspection",
"address": "123 Test Road",
"client_name": "Example client",
"status": "active",
"created_at": "2026-11-19T00:00:00Z"
}
],
"page": {
"limit": 25,
"next_cursor": null
}
}Save updates safely
curl -X PATCH "https://web.buildercoms.com/api/public/v1/jobs/$JOB_ID" \
-H "Authorization: Bearer $BUILDERCOMS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-H "Idempotency-Key: $ACTION_UUID" \
-d '{"status":"completed"}'Generate a new UUID for every action. Retry timeouts or temporary failures with the same UUID, endpoint and identical details. Changed retries return 409. All successful writes return 200 with data.status: "succeeded", including retries; read the matching record to confirm.
Job PATCH accepts only status: active or completed. Task PATCH replaces title and due date; omitting due date clears it. The completion endpoint accepts {"done":true} or {"done":false}. Unknown fields are rejected.
Team and Client messages
Read /jobs/{job_id}/conversations for current conversation IDs. General uses Team with a null channel. Client requires an active client_link_id and no Team channel. Read with audience=team or audience=client&client_link_id=…. Omit parent_id to page roots; provide a root ID to page replies. Send bodies omit job_id; the URL defines it.
{
"body": "Framing inspection is complete.",
"audience": "team",
"channel_id": null,
"client_link_id": null,
"parent_id": null
}Replies must retain the original audience, channel and client link. Client sends go directly to that client conversation. Existing company and participant permissions apply. This API is not email inbox sync and does not provide outgoing customer webhook subscriptions.
Incoming update webhook
POST to https://web.buildercoms.com/api/public/v1/webhooks/updates with an owner-authorized OAuth access token or company REST API key and application/json. Your external tool must support sending an Authorization header; unauthenticated provider callbacks and shared company-wide secrets are not accepted.
{
"event_id": "123e4567-e89b-42d3-a456-426614174000",
"event": "job.status_changed",
"data": {
"job_id": "123e4567-e89b-42d3-a456-426614174001",
"status": "completed"
}
}job.created: new-job fieldsjob.updated: job_id, name, address and client_name, plus complete job details; omitted optional fields are clearedjob.status_changed: job_id and active / completed statustask.created: job_id, title and optional due_datetask.updated: job_id, task_id, title and optional due_datetask.completion_changed: job_id, task_id and donemessage.sent: job_id, body, audience, channel_id, client_link_id and parent_id for a reply
Updates are applied synchronously, not queued or polled. A 200 with succeeded means the update is saved; read the matching REST record to confirm. Use a new event_id UUID per action and preserve it and identical data on retries. Duplicate deliveries return the same result without another message; event IDs reused with different details or REST actions conflict. No Idempotency-Key header is needed for this endpoint.
Read & write, subscription, current job and exact conversation permissions still apply. Events cannot select another company, impersonate a sender or bypass revoked access. Deliver updates for one job in order and wait for acknowledgment before sending the next status change; this endpoint does not reorder events from your provider. On 503 or timeout, retry with exponential backoff and the same event; on 401 refresh OAuth, on 403 stop and check permission, and on 409 correct your changed retry. Sending an event does not configure the external tool for you.
Errors and limits
JSON bodies are limited to 32 KiB; repeated query parameters are rejected. Cross-origin bearer requests work without cookies. Private responses are not cached. Use X-Request-ID when investigating failures; never log tokens or private conversation content.
{
"error": {
"code": "write_access_required",
"message": "The company owner must allow Read & write access."
}
}400 invalid fields · 401 invalid/expired token · 403 denied access, plan or limit · 404 missing/inaccessible job · 409 changed retry · 413 oversized body · 415 wrong content type · 503 temporary failure. Retry temporary failures with backoff and the original UUID; do not automatically retry permission failures. No production throughput guarantee is made.