# BuildingSwell API

> Integrate with the BuildingSwell v2 Public API

## Docs

- [Create comment(s)](https://api.buildingswell.com/api-reference/comments/create-comments.md)
- [Delete comment](https://api.buildingswell.com/api-reference/comments/delete-comment.md)
- [Get comment](https://api.buildingswell.com/api-reference/comments/get-comment.md)
- [Group and count comments](https://api.buildingswell.com/api-reference/comments/group-and-count-comments.md)
- [List comments](https://api.buildingswell.com/api-reference/comments/list-comments.md)
- [Query comments](https://api.buildingswell.com/api-reference/comments/query-comments.md)
- [Update comment](https://api.buildingswell.com/api-reference/comments/update-comment.md)
- [Upsert comment](https://api.buildingswell.com/api-reference/comments/upsert-comment.md)
- [Apply progress action](https://api.buildingswell.com/api-reference/concepts/apply-progress-action.md): Applies progress action with cascades. Stops work sessions and removes worker plans for done nodes.
- [Apply route to deliverable](https://api.buildingswell.com/api-reference/concepts/apply-route-to-deliverable.md)
- [Create concept deliverable](https://api.buildingswell.com/api-reference/concepts/create-concept-deliverable.md): Creates a deliverable with concept validation. Rejects invalid nesting and missing required data.
- [Create order from route](https://api.buildingswell.com/api-reference/concepts/create-order-from-route.md)
- [Get concept registry](https://api.buildingswell.com/api-reference/concepts/get-concept-registry.md): Machine-readable registry of all domain concepts with nesting rules and required fields.
- [Get order context](https://api.buildingswell.com/api-reference/concepts/get-order-context.md)
- [Get route summary](https://api.buildingswell.com/api-reference/concepts/get-route-summary.md)
- [List stages](https://api.buildingswell.com/api-reference/concepts/list-stages.md)
- [Preflight progress action](https://api.buildingswell.com/api-reference/concepts/preflight-progress-action.md): Returns proposed changes without writing. Use before destructive progress actions.
- [Update concept deliverable](https://api.buildingswell.com/api-reference/concepts/update-concept-deliverable.md)
- [Batch schedule deliverables](https://api.buildingswell.com/api-reference/deliverables/batch-schedule-deliverables.md): Each item wraps a 'ScheduleAction' (see 'POST /deliverable/root/{rootId}/schedule/{id}') with the target ids.
- [Bulk upsert deliverables](https://api.buildingswell.com/api-reference/deliverables/bulk-upsert-deliverables.md)
- [Create deliverable(s)](https://api.buildingswell.com/api-reference/deliverables/create-deliverables.md)
- [Delete deliverable](https://api.buildingswell.com/api-reference/deliverables/delete-deliverable.md)
- [Export deliverables to Excel](https://api.buildingswell.com/api-reference/deliverables/export-deliverables-to-excel.md): Returns a .xlsx file (max 10,000 rows). Accepts the same filters as GET /deliverable.
- [Get crew time](https://api.buildingswell.com/api-reference/deliverables/get-crew-time.md)
- [Get deliverable](https://api.buildingswell.com/api-reference/deliverables/get-deliverable.md)
- [Get deliverable hierarchy](https://api.buildingswell.com/api-reference/deliverables/get-deliverable-hierarchy.md): Returns all deliverables in the subtree rooted at the given id.
- [Group and count deliverables](https://api.buildingswell.com/api-reference/deliverables/group-and-count-deliverables.md)
- [Group deliverables](https://api.buildingswell.com/api-reference/deliverables/group-deliverables.md)
- [Import deliverables from Excel](https://api.buildingswell.com/api-reference/deliverables/import-deliverables-from-excel.md): Rate-limited to 100 requests/min. Only .xlsx, max 10 MB.
- [List deliverables](https://api.buildingswell.com/api-reference/deliverables/list-deliverables.md)
- [Query deliverables](https://api.buildingswell.com/api-reference/deliverables/query-deliverables.md)
- [Reorder deliverables](https://api.buildingswell.com/api-reference/deliverables/reorder-deliverables.md)
- [Schedule a deliverable](https://api.buildingswell.com/api-reference/deliverables/schedule-a-deliverable.md): Body is an action union (see 'ScheduleAction'); 'newStart'/'newFinish' are epoch **seconds**, not ISO date strings. Only one of the two is required per action — the engine derives the other.
- [Update deliverable](https://api.buildingswell.com/api-reference/deliverables/update-deliverable.md)
- [Update deliverable progress](https://api.buildingswell.com/api-reference/deliverables/update-deliverable-progress.md): Body is an action union (see 'ProgressAction'), not '{status, completed, wip}'. Response is '{ kickedWorkers }' — not the updated deliverable; re-fetch it separately if needed.
- [Upsert deliverable](https://api.buildingswell.com/api-reference/deliverables/upsert-deliverable.md)
- [Create dependency link(s)](https://api.buildingswell.com/api-reference/dependencies/create-dependency-links.md)
- [Delete dependency](https://api.buildingswell.com/api-reference/dependencies/delete-dependency.md)
- [Get dependency](https://api.buildingswell.com/api-reference/dependencies/get-dependency.md)
- [Get dependency hierarchy](https://api.buildingswell.com/api-reference/dependencies/get-dependency-hierarchy.md): Returns all dependencies in the subtree rooted at the given id.
- [List deliverable dependencies](https://api.buildingswell.com/api-reference/dependencies/list-deliverable-dependencies.md)
- [Update dependency](https://api.buildingswell.com/api-reference/dependencies/update-dependency.md)
- [Create document(s)](https://api.buildingswell.com/api-reference/documents/create-documents.md)
- [Delete document](https://api.buildingswell.com/api-reference/documents/delete-document.md)
- [Get document](https://api.buildingswell.com/api-reference/documents/get-document.md)
- [List documents](https://api.buildingswell.com/api-reference/documents/list-documents.md)
- [Query documents](https://api.buildingswell.com/api-reference/documents/query-documents.md)
- [Update document](https://api.buildingswell.com/api-reference/documents/update-document.md)
- [Upsert document](https://api.buildingswell.com/api-reference/documents/upsert-document.md)
- [Create note(s)](https://api.buildingswell.com/api-reference/notes/create-notes.md)
- [Create or update note by deliverable](https://api.buildingswell.com/api-reference/notes/create-or-update-note-by-deliverable.md): Creates if missing, updates if it exists.
- [Delete note](https://api.buildingswell.com/api-reference/notes/delete-note.md)
- [Get note](https://api.buildingswell.com/api-reference/notes/get-note.md)
- [List notes](https://api.buildingswell.com/api-reference/notes/list-notes.md)
- [Update note](https://api.buildingswell.com/api-reference/notes/update-note.md)
- [Upsert note](https://api.buildingswell.com/api-reference/notes/upsert-note.md)
- [Get notification](https://api.buildingswell.com/api-reference/notifications/get-notification.md)
- [List notifications](https://api.buildingswell.com/api-reference/notifications/list-notifications.md)
- [Mark channel comments as read](https://api.buildingswell.com/api-reference/notifications/mark-channel-comments-as-read.md)
- [Mark deliverable documents as read](https://api.buildingswell.com/api-reference/notifications/mark-deliverable-documents-as-read.md)
- [Create role](https://api.buildingswell.com/api-reference/organization/create-role.md)
- [Deactivate member](https://api.buildingswell.com/api-reference/organization/deactivate-member.md)
- [Duplicate role](https://api.buildingswell.com/api-reference/organization/duplicate-role.md)
- [Invite organization member](https://api.buildingswell.com/api-reference/organization/invite-organization-member.md)
- [List organization members](https://api.buildingswell.com/api-reference/organization/list-organization-members.md)
- [List roles](https://api.buildingswell.com/api-reference/organization/list-roles.md)
- [Reactivate member](https://api.buildingswell.com/api-reference/organization/reactivate-member.md)
- [Resend invite](https://api.buildingswell.com/api-reference/organization/resend-invite.md)
- [Update organization member](https://api.buildingswell.com/api-reference/organization/update-organization-member.md)
- [API reference overview](https://api.buildingswell.com/api-reference/overview.md): Interactive reference for BuildingSwell v2 API endpoints.
- [Bulk update projects](https://api.buildingswell.com/api-reference/projects/bulk-update-projects.md): The filter must be supplied as **query-string** parameters (e.g. '?isArchived=false'); a filter in the request body alone is ignored and the request 400s with "No filter provided for updateMany".
- [Bulk upsert projects](https://api.buildingswell.com/api-reference/projects/bulk-upsert-projects.md)
- [Count projects](https://api.buildingswell.com/api-reference/projects/count-projects.md)
- [Count projects (large filter)](https://api.buildingswell.com/api-reference/projects/count-projects-large-filter.md)
- [Create project(s)](https://api.buildingswell.com/api-reference/projects/create-projects.md): Create one or many project records.
- [Delete project](https://api.buildingswell.com/api-reference/projects/delete-project.md)
- [Get project](https://api.buildingswell.com/api-reference/projects/get-project.md)
- [Group and count projects](https://api.buildingswell.com/api-reference/projects/group-and-count-projects.md)
- [List projects](https://api.buildingswell.com/api-reference/projects/list-projects.md): List and filter project records. Supports pagination, sorting, search, and filters.
- [Query projects](https://api.buildingswell.com/api-reference/projects/query-projects.md): List projects when the filter is too large for a GET query string.
- [Update project](https://api.buildingswell.com/api-reference/projects/update-project.md)
- [Upsert project](https://api.buildingswell.com/api-reference/projects/upsert-project.md)
- [Create QC inspection set(s)](https://api.buildingswell.com/api-reference/qc/create-qc-inspection-sets.md)
- [Delete QC inspection set](https://api.buildingswell.com/api-reference/qc/delete-qc-inspection-set.md)
- [Delete QC template](https://api.buildingswell.com/api-reference/qc/delete-qc-template.md)
- [Get QC inspection set](https://api.buildingswell.com/api-reference/qc/get-qc-inspection-set.md)
- [Get QC template](https://api.buildingswell.com/api-reference/qc/get-qc-template.md)
- [List QC inspection sets](https://api.buildingswell.com/api-reference/qc/list-qc-inspection-sets.md)
- [List QC templates](https://api.buildingswell.com/api-reference/qc/list-qc-templates.md): Read and delete only — 'POST /qc-template' and 'PATCH /qc-template/{id}' are not supported (create fails server-side; update is a silent no-op). Manage QC templates via the BuildingSwell UI.
- [Update QC inspection set](https://api.buildingswell.com/api-reference/qc/update-qc-inspection-set.md)
- [Create stage(s)](https://api.buildingswell.com/api-reference/stages/create-stages.md)
- [Delete stage](https://api.buildingswell.com/api-reference/stages/delete-stage.md)
- [Get stage](https://api.buildingswell.com/api-reference/stages/get-stage.md)
- [Group and count stages](https://api.buildingswell.com/api-reference/stages/group-and-count-stages.md)
- [List stages](https://api.buildingswell.com/api-reference/stages/list-stages.md)
- [Query stages](https://api.buildingswell.com/api-reference/stages/query-stages.md)
- [Update stage](https://api.buildingswell.com/api-reference/stages/update-stage.md)
- [Upsert stage](https://api.buildingswell.com/api-reference/stages/upsert-stage.md)
- [Get timesheet](https://api.buildingswell.com/api-reference/timesheets/get-timesheet.md)
- [Group and count timesheets](https://api.buildingswell.com/api-reference/timesheets/group-and-count-timesheets.md)
- [List timesheets](https://api.buildingswell.com/api-reference/timesheets/list-timesheets.md): Read-only resource. Aggregates attendance and work sessions.
- [Query timesheets](https://api.buildingswell.com/api-reference/timesheets/query-timesheets.md)
- [Create work session(s)](https://api.buildingswell.com/api-reference/work-sessions/create-work-sessions.md)
- [List work sessions](https://api.buildingswell.com/api-reference/work-sessions/list-work-sessions.md)
- [Save work session assignments](https://api.buildingswell.com/api-reference/work-sessions/save-work-session-assignments.md)
- [Stop work sessions](https://api.buildingswell.com/api-reference/work-sessions/stop-work-sessions.md)
- [Create worker](https://api.buildingswell.com/api-reference/workers/create-worker.md)
- [Get worker](https://api.buildingswell.com/api-reference/workers/get-worker.md)
- [Group and count workers](https://api.buildingswell.com/api-reference/workers/group-and-count-workers.md)
- [List workers](https://api.buildingswell.com/api-reference/workers/list-workers.md)
- [Query workers](https://api.buildingswell.com/api-reference/workers/query-workers.md)
- [Update worker](https://api.buildingswell.com/api-reference/workers/update-worker.md): Use `isArchived: true` to archive. Hard delete returns 403.
- [Domain concepts](https://api.buildingswell.com/concepts/overview.md): Concept-aware endpoints that enforce nesting rules and validation on top of deliverables.
- [Examples](https://api.buildingswell.com/examples.md): Common API request examples for the BuildingSwell v2 API.
- [Authentication](https://api.buildingswell.com/getting-started/authentication.md): Authenticate API requests with an organization-scoped API key.
- [Rate limits](https://api.buildingswell.com/getting-started/rate-limits.md): Request rate limits and response headers for the BuildingSwell v2 API.
- [Group and count](https://api.buildingswell.com/guides/group-and-count.md): Group records by a field and return counts.
- [Import and export](https://api.buildingswell.com/guides/import-export.md): Excel import and export for deliverables.
- [Querying](https://api.buildingswell.com/guides/querying.md): Pagination, sorting, field selection, search, filtering, and joins.
- [Response format](https://api.buildingswell.com/guides/response-format.md): Response shapes and error format for the BuildingSwell v2 API.
- [Standard endpoints](https://api.buildingswell.com/guides/standard-endpoints.md): CRUD and query endpoints available on every v2 resource.
- [BuildingSwell Public API (v2)](https://api.buildingswell.com/index.md): Everything you need to integrate with the BuildingSwell v2 API.
- [Comment](https://api.buildingswell.com/resources/comment.md): Comments on deliverables.
- [Deliverable](https://api.buildingswell.com/resources/deliverable.md): The central work-tree resource — orders, routes, phases, stages, steps, and more.
- [Deliverable dependencies](https://api.buildingswell.com/resources/deliverable-dependencies.md): Dependency links between deliverables.
- [Deliverable work sessions](https://api.buildingswell.com/resources/deliverable-work-sessions.md): Work sessions on deliverables.
- [Document](https://api.buildingswell.com/resources/document.md): Documents attached to deliverables.
- [Note](https://api.buildingswell.com/resources/note.md): Notes on deliverables.
- [Notification](https://api.buildingswell.com/resources/notification.md): Notifications and read-state endpoints.
- [Users (Organization Members)](https://api.buildingswell.com/resources/organization-member.md): Members of the organization.
- [Project](https://api.buildingswell.com/resources/project.md): Projects group orders and other work in BuildingSwell.
- [QC inspection set](https://api.buildingswell.com/resources/qc-inspection-set.md): QC inspection sets.
- [QC template](https://api.buildingswell.com/resources/qc-template.md): QC template versions.
- [Role](https://api.buildingswell.com/resources/role.md): Permission roles.
- [Stage](https://api.buildingswell.com/resources/stage.md): Stages — reusable, department-scoped shop stations.
- [Timesheet](https://api.buildingswell.com/resources/timesheet.md): Unified view of all time-tracking records (read-only).
- [People (Workers)](https://api.buildingswell.com/resources/worker.md): The workforce roster.

## OpenAPI Specs

- [openapi](https://api.buildingswell.com/openapi.yaml)