> ## Documentation Index > Fetch the complete documentation index at: https://api.buildingswell.com/llms.txt > Use this file to discover all available pages before exploring further. # Update many deliverables > Apply one set of changes to every deliverable matching your filter. The filter must be in the **query string**. A filter in the body is ignored, and a request with no filter is rejected with `400` so you cannot update the whole table by accident. ## OpenAPI ````yaml /openapi.yaml patch /deliverable/bulk openapi: 3.0.3 info: title: BuildingSwell Public API version: 2.0.0 description: > The BuildingSwell v2 public API. Every request needs an `X-API-Key` header, and every key is scoped to one organization, so you only ever see your own data. Base URL: `https://app.buildingswell.com/api/v2` Most resources share the same CRUD and query shape. Read the [standard endpoints](/guides/standard-endpoints) and [querying](/guides/querying) guides once and the rest of this reference follows the same rules. For what a delete actually removes, see [archiving and deleting](/guides/archiving-and-deleting). servers: - url: https://{instance}/api/v2 description: Your BuildingSwell instance variables: instance: default: app.buildingswell.com description: Your BuildingSwell host security: - ApiKeyAuth: [] tags: - name: Projects description: Customer jobs, and the archive behavior they share with most resources. - name: Stages description: Reusable shop stations, scoped to a department. - name: Deliverables description: >- The work tree: orders, routes, phases, components, stages, steps, and QC steps. - name: Work sessions description: Time logged by one person against one deliverable. - name: Dependencies description: Scheduling links between deliverables. - name: Documents description: Files attached to orders. - name: QC description: QC templates and the inspection sets filled from them. - name: People (Workers) description: Your workforce roster. Called People in the app and `worker` in the API. - name: Timesheets description: Read-only view over attendance and work sessions. - name: Codes description: Cost, union, and per diem code lists. Referenced by value, not by id. - name: Roles description: Permission roles, and the statements that make them up. - name: Users description: >- People with a BuildingSwell login. Called Users in the app and `organization-member` in the API. - name: Concepts description: Deliverable writes with the nesting rules enforced. - name: Items description: Material and part definitions, purchasing units, and availability. - name: Item vendors description: Supplier SKUs linked to items. - name: Inventory stock description: Read-only quantities by item and location. - name: Inventory transactions description: The inventory ledger and its posting rules. - name: Inventory allocations description: Read-only reservations for orders and projects. - name: BOM lines description: Planned material inputs for routes, orders, and projects. - name: Production outputs description: Declarations of manufactured outputs. - name: Units of measure description: Reusable names and abbreviations for quantities. - name: Vendors description: Suppliers, manufacturers, and subcontractors. - name: Locations description: Department and project locations for storage and delivery. - name: Deliveries description: Inbound receipts, outbound trips, and transfers. - name: Delivery lines description: Material and ad-hoc manifest lines. - name: Trucks description: Fleet vehicles and their capacity. - name: Contacts description: Drivers, receivers, and other business contacts. - name: Project contacts description: Links between projects and contacts. - name: Teams description: Read-only department teams. - name: Shifts description: Read-only department shifts. - name: Departments (shops) description: Read-only departments, called shops in the API. - name: Custom properties description: Organization property definitions and values on orders. paths: /deliverable/bulk: patch: tags: - Deliverables summary: Update many deliverables description: >- Apply one set of changes to every deliverable matching your filter. The filter must be in the **query string**. A filter in the body is ignored, and a request with no filter is rejected with `400` so you cannot update the whole table by accident. parameters: - $ref: '#/components/parameters/search' - $ref: '#/components/parameters/filter' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DeliverableUpdate' responses: '200': description: The updated deliverables. content: application/json: schema: $ref: '#/components/schemas/DeliverableMultiResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '429': $ref: '#/components/responses/RateLimited' components: parameters: search: name: search in: query description: >- Full-text search across the resource's search columns. Append `:col1,col2` to limit which columns are searched. schema: type: string example: warehouse filter: name: filter in: query description: >- AND/OR filter expression, for example `type eq 'phase' and isArchived eq false`. Simple equality can also be passed as plain field parameters. schema: type: string example: isArchived eq false schemas: DeliverableUpdate: type: object description: Every field is optional. Only the fields you send are changed. properties: identifier: type: string description: >- Human-readable id, unique within your organization. Generated for you when you leave it out. name: type: string description: Display name. isArchived: type: boolean description: >- Archived records are hidden from list results unless you ask for them. Set this to archive or restore the record. default: false archivedAt: type: string format: date-time description: >- When the record was archived. Set automatically when `isArchived` flips to `true`, and cleared on restore. nullable: true type: type: string enum: - order - route - overhead - template-phase - phase - component - stage - step - qcstep - group description: Which concept this node represents. quantity: type: integer description: How many of this node the work covers. default: 1 parentId: type: string format: uuid description: Node directly above this one. nullable: true rootParentId: type: string format: uuid description: Root of this node's tree. A root node points at itself. nullable: true originTemplateId: type: string format: uuid description: Route or template this node was built from. nullable: true cycleTimeSec: type: integer description: Cycle time per unit, in seconds. default: 0 durationSec: type: integer description: Total duration, in seconds. default: 0 peopleNum: type: integer description: How many people the node is planned for. default: 1 data: type: object description: >- Per-concept fields. Which keys apply depends on `type`: a stage node needs `stageId`, an order needs `projectId`, and so on. See the domain concepts guide for the full table. example: stageId: 3fa85f64-5717-4562-b3fc-2c963f66afa6 additionalProperties: true properties: properties: type: object additionalProperties: true description: >- Custom-property values keyed by immutable catalog key, on orders only. Requires customPropertiesEnabled; current disabled writes silently discard this key. Nonempty objects merge; null or {} clears all values. costCode: type: string description: >- Cost code. Trimmed on write, and an empty string is rejected: send a non-empty string or `null`. Stored as a plain string. It is not validated against the cost code list, and renaming an entry in that list does not change this value. nullable: true DeliverableMultiResponse: type: object properties: values: type: array items: $ref: '#/components/schemas/Deliverable' required: - values Deliverable: type: object description: >- One generic work-tree node. Its `type` decides which domain concept it represents, from an order down to a single step. properties: id: type: string format: uuid description: Unique id. Generated on create unless you supply one. organizationId: type: string format: uuid description: >- Your organization. Taken from the API key, never from the request body. identifier: type: string description: >- Human-readable id, unique within your organization. Generated for you when you leave it out. name: type: string description: Display name. isArchived: type: boolean description: >- Archived records are hidden from list results unless you ask for them. Set this to archive or restore the record. default: false archivedAt: type: string format: date-time description: >- When the record was archived. Set automatically when `isArchived` flips to `true`, and cleared on restore. nullable: true archivedById: type: string format: uuid description: >- Who archived the record. Server-managed: a value you send is ignored. nullable: true type: type: string enum: - order - route - overhead - template-phase - phase - component - stage - step - qcstep - group description: Which concept this node represents. quantity: type: integer description: How many of this node the work covers. default: 1 parentId: type: string format: uuid description: Node directly above this one. nullable: true rootParentId: type: string format: uuid description: Root of this node's tree. A root node points at itself. nullable: true originTemplateId: type: string format: uuid description: Route or template this node was built from. nullable: true cycleTimeSec: type: integer description: Cycle time per unit, in seconds. default: 0 durationSec: type: integer description: Total duration, in seconds. default: 0 peopleNum: type: integer description: How many people the node is planned for. default: 1 data: type: object description: >- Per-concept fields. Which keys apply depends on `type`: a stage node needs `stageId`, an order needs `projectId`, and so on. See the domain concepts guide for the full table. example: stageId: 3fa85f64-5717-4562-b3fc-2c963f66afa6 additionalProperties: true properties: properties: type: object additionalProperties: true description: >- Custom-property values keyed by immutable catalog key, on orders only. Requires customPropertiesEnabled; current disabled writes silently discard this key. Nonempty objects merge; null or {} clears all values. costCode: type: string description: >- Cost code. Trimmed on write, and an empty string is rejected: send a non-empty string or `null`. Stored as a plain string. It is not validated against the cost code list, and renaming an entry in that list does not change this value. nullable: true schedule: type: object description: Scheduled window for the node. Present on `order` nodes only. nullable: true properties: startDate: type: string format: date-time description: Scheduled start. endDate: type: string format: date-time description: Scheduled finish. progress: type: object description: >- Progress for the node. Present on `order` nodes only. Write it through the progress action endpoint rather than by patching this object. nullable: true properties: status: type: string enum: - waiting - todo - wip - rework - on-hold - done description: Where the work stands right now. completed: type: number description: Quantity finished. default: 0 minimum: 0 wip: type: number description: Quantity in progress. default: 0 minimum: 0 percentage: type: number description: Percent complete, 0 to 100. default: 0 minimum: 0 startedAt: type: string format: date-time description: When work first started. nullable: true completedAt: type: string format: date-time description: When the node reached `done`. nullable: true hasBeenReworked: type: boolean description: >- `true` once the node has ever been set to `rework`. Server-managed, and it stays `true` after the status changes again. default: false updatedById: type: string format: uuid description: >- Who last changed progress. Server-managed, and `null` for transitions into `waiting`. nullable: true updatedAt: type: string format: date-time description: >- When progress last changed. Server-managed, and `null` for transitions into `waiting`. nullable: true computed: description: >- Values BuildingSwell derives from the tree on every read. All read-only: anything you send here is ignored. type: object properties: rootType: type: string enum: - order - route - overhead - template-phase - phase - component - stage - step - qcstep - group description: '`type` of the root node of this tree.' nullable: true fullName: type: array description: Name breadcrumb from the root down to this node. items: type: string description: Node name. fullPath: type: array description: Id breadcrumb from the root down to this node. items: type: string format: uuid description: Node id. shopId: type: string format: uuid description: >- Department that applies to this node, inherited from the nearest ancestor when the node does not set one. `null` means cross-department. nullable: true phasesPath: type: array description: Phase names in this node's ancestry. items: type: string description: Phase name. phase: type: string description: Nearest phase name above this node. nullable: true currentChildren: type: array description: Summary of the node's direct children. items: type: object description: One direct child. properties: id: type: string format: uuid description: Child id. name: type: string description: Child name. stageId: type: string format: uuid description: Station the child links to, when it is a stage node. nullable: true type: type: string enum: - order - route - overhead - template-phase - phase - component - stage - step - qcstep description: Child type. containedStageIds: type: array description: Every station anywhere beneath this node. items: type: string format: uuid description: Station id. nullable: true containedPhaseNames: type: array description: Every phase name anywhere beneath this node. items: type: string description: Phase name. containedCurrentStageIds: type: array description: Stations beneath this node that sit on the active work frontier. items: type: string format: uuid description: Station id. nullable: true containedCurrentPhaseNames: type: array description: >- Phase names beneath this node that sit on the active work frontier. items: type: string description: Phase name. currentStageIds: type: array description: >- Stations on this node's own active work frontier. Filter it with the `jinco` operator. items: type: string format: uuid description: Station id. currentPhaseNames: type: array description: Phase names on this node's own active work frontier. items: type: string description: Phase name. combinedWorkerIds: type: array description: Everyone assigned anywhere beneath this node. items: type: string format: uuid description: Person id. combinedTagIds: type: array description: Every tag anywhere beneath this node. items: type: string description: Tag id. workerIds: type: array description: People assigned directly to this node. items: type: string format: uuid description: Person id. tags: type: array description: Tags on this node itself. items: type: string description: Tag id. isLeaf: type: boolean description: '`true` when the node has no children.' default: true projectId: type: string format: uuid description: Project this tree belongs to. nullable: true date: type: string description: Effective date for the node. nullable: true isAtRisk: type: boolean description: '`true` when the node is trending late.' default: false isLate: type: boolean description: '`true` when the node has missed its date.' default: false effectiveDueDate: type: string description: Due date that applies, whether set here or inherited. nullable: true effectiveDueDateIsInherited: type: boolean description: '`true` when the due date comes from an ancestor.' default: false effectiveDueDateIsLate: type: boolean description: '`true` when the effective due date has passed.' default: false hasReworkedStages: type: boolean description: '`true` when any stage beneath this node has been reworked.' default: false groupIds: type: array items: type: string format: uuid readOnly: true description: >- IDs of group deliverables containing this node. Maintained from group.data.itemIds. alertType: type: string enum: - on-hold - late - at-risk - no-risk description: > Highest-priority alert state for the node. Derived on every read, and returned at the top level rather than inside `computed`. alertTypeOrdinal: type: integer description: | `alertType` as a sortable number: 0 no-risk, 1 at-risk, 2 late, 3 on-hold. Sort on this rather than on `alertType`, whose values are not alphabetical. createdAt: type: string format: date-time description: When the record was created. updatedAt: type: string format: date-time description: When the record last changed. Error: type: object properties: error: type: object properties: message: type: string description: What went wrong, in plain language. code: type: string enum: - BAD_REQUEST - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - CONFLICT - VALIDATION - UNIQUE_VIOLATION - FK_VIOLATION - RATE_LIMITED - INTERNAL description: >- Stable machine-readable code. Branch on this rather than on the message text. requestId: type: string description: Id for this request. Quote it when you contact support. details: type: array items: type: object description: One field-level problem. properties: path: type: string description: Field that failed, for example `data.stageId`. message: type: string description: Why it failed. code: type: string description: Validation code. description: Per-field problems. Present on validation failures only. missingPermissions: type: array items: type: string description: Permission name. description: Permissions your key is missing. Present on `403` only. context: type: object description: Extra context for the error. Usually empty. additionalProperties: true responses: BadRequest: description: >- The request was malformed or failed validation. Check `error.details` for the fields at fault. content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: The `X-API-Key` header is missing or the key is invalid. content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: >- Your key lacks the permission for this call. `error.missingPermissions` lists what is needed. content: application/json: schema: $ref: '#/components/schemas/Error' Conflict: description: >- The write conflicts with existing data: a duplicate unique value (`UNIQUE_VIOLATION`), or a related record that blocks it (`FK_VIOLATION`). content: application/json: schema: $ref: '#/components/schemas/Error' RateLimited: description: >- Too many requests. Read `RateLimit-Reset` for when to retry. This response also carries a top-level `message` alongside `error`. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: >- Organization-scoped API key. Create one in the BuildingSwell app under Organization settings, API keys. ````