BuilderComs tools & API

MCP · REST v1 · Incoming webhooks

Tools & endpoint explorer

13 MCP tools · 14 API operations

Used only in request headers. Not saved, copied into examples or shared with another host. Account login tokens are not accepted. MCP requires OAuth.

Live test destinationLoading current app address…

Tests use this app, not a mock. Code samples use web.buildercoms.com. Publish changes before testing on the production address.

Read onlyGET

Test company REST key connection

/connection

Test 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"
          }
        }
      }
    }
  }
}
Without a token, tests check the authorization error only.
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

  1. The company owner opens Settings → Integrations → Developer portal, names a connection and selects Read only or Read & write.
  2. 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.
  3. Send Authorization: Bearer YOUR_COMPANY_KEY. Test with GET /api/public/v1/connection or 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 portal

Connection 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.

  1. Read OAuth resource metadata. Load authorization-server discovery from its authorization server.
  2. Register your tool at the discovered registration_endpoint, with its name, exact HTTPS redirect URI, grant_types: ["authorization_code", "refresh_token"], response_types: ["code"] and token_endpoint_auth_method: "none".
  3. Open the discovered authorization endpoint with client_id, registered redirect_uri, response_type=code, random state, code_challenge and code_challenge_method=S256. The company owner signs in, names the integration and selects access.
  4. Validate callback state. Exchange the code at the discovered token endpoint with grant_type=authorization_code, the same client_id, redirect_uri and original code_verifier. Refresh there with grant_type=refresh_token; securely store and replace rotated tokens.
  5. 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

GET/connection

Test company REST key connection

POST/webhooks/updates

Receive an incoming job, status, task or reply event

GET/jobs

List authorized jobs

POST/jobs

Create a job

PATCH/jobs/{job_id}/details

Replace job details

GET/jobs/{job_id}

Read job details

PATCH/jobs/{job_id}

Set job status

GET/jobs/{job_id}/tasks

List job tasks

POST/jobs/{job_id}/tasks

Create a task

PATCH/jobs/{job_id}/tasks/{task_id}

Replace task title and due date

PATCH/jobs/{job_id}/tasks/{task_id}/completion

Complete or reopen task

GET/jobs/{job_id}/conversations

Discover authorized Team channels and Client conversation IDs

GET/jobs/{job_id}/messages

Read conversation roots or exact-thread replies

POST/jobs/{job_id}/messages

Send 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"
  }
}

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.