> ## 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 a work session > Change one work session. Only the fields you send are touched. ## OpenAPI ````yaml /openapi.yaml patch /deliverable/work-sessions/{id} 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/work-sessions/{id}: patch: tags: - Work sessions summary: Update a work session description: Change one work session. Only the fields you send are touched. parameters: - $ref: '#/components/parameters/id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DeliverableWorkSessionUpdate' responses: '200': description: The updated work session. content: application/json: schema: $ref: '#/components/schemas/DeliverableWorkSessionSingleResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '429': $ref: '#/components/responses/RateLimited' components: parameters: id: name: id in: path required: true description: Record id. schema: type: string format: uuid schemas: DeliverableWorkSessionUpdate: type: object description: Every field is optional. Only the fields you send are changed. properties: deliverableId: type: string format: uuid description: Deliverable the time was logged against. workerId: type: string format: uuid description: Person who did the work. shopId: type: string format: uuid description: Department the session belongs to. startDate: type: string format: date-time description: When the session started, in UTC. endDate: type: string format: date-time description: When the session ended, in UTC. `null` means it is still open. nullable: true isEdited: type: boolean description: '`true` when someone has edited the session by hand.' default: false lastUpdatedBy: type: string format: uuid description: Who last changed the session. nullable: true shiftWorkHours: type: object description: >- The shift the record was worked against. Break times are local wall-clock, not UTC. nullable: true required: - startTime - endTime properties: startTime: type: string description: Shift start as local wall-clock time, `HH:mm`. example: '08:00' endTime: type: string description: Shift end as local wall-clock time, `HH:mm`. example: '17:00' breaks: type: array description: >- Scheduled unpaid breaks for the shift. Omitted when the shift has none. items: type: object description: One scheduled break. required: - startTime - durationInSec properties: startTime: type: string description: Break start as local wall-clock time, `HH:mm`. example: '12:00' durationInSec: type: integer description: How long the break lasts, in seconds. example: 1800 timezone: type: string description: >- IANA timezone of the shop the shift belongs to, stamped server-side. `breakTimeInSec` anchors each break's local time to this zone. Defaults to `UTC` when absent. example: America/New_York externalSource: type: string description: System the session came from, for example `quickbase`. nullable: true externalSync: type: string description: Sync state for the external system. default: not synced example: synced metadata: type: object description: >- Free-form key-value store. No key is guaranteed to be present, and a missing key is not the same as a `null` one. See the resource guide for which paths populate `costCode` and `unionCode`. example: costCode: WELD-100 unionCode: LOCAL-7 additionalProperties: true DeliverableWorkSessionSingleResponse: type: object properties: value: $ref: '#/components/schemas/DeliverableWorkSession' required: - value DeliverableWorkSession: type: object description: >- Time one person logged against one deliverable. An open session has no `endDate`. 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. deliverableId: type: string format: uuid description: Deliverable the time was logged against. workerId: type: string format: uuid description: Person who did the work. shopId: type: string format: uuid description: Department the session belongs to. startDate: type: string format: date-time description: >- Effective start in UTC. The hours-rounding job can rewrite it; rawStart preserves the original. endDate: type: string format: date-time description: >- Effective end in UTC; null while open. The hours-rounding job can rewrite it; rawEnd preserves the original. nullable: true isEdited: type: boolean description: '`true` when someone has edited the session by hand.' default: false lastUpdatedBy: type: string format: uuid description: Who last changed the session. nullable: true shiftWorkHours: type: object description: >- The shift the record was worked against. Break times are local wall-clock, not UTC. nullable: true required: - startTime - endTime properties: startTime: type: string description: Shift start as local wall-clock time, `HH:mm`. example: '08:00' endTime: type: string description: Shift end as local wall-clock time, `HH:mm`. example: '17:00' breaks: type: array description: >- Scheduled unpaid breaks for the shift. Omitted when the shift has none. items: type: object description: One scheduled break. required: - startTime - durationInSec properties: startTime: type: string description: Break start as local wall-clock time, `HH:mm`. example: '12:00' durationInSec: type: integer description: How long the break lasts, in seconds. example: 1800 timezone: type: string description: >- IANA timezone of the shop the shift belongs to, stamped server-side. `breakTimeInSec` anchors each break's local time to this zone. Defaults to `UTC` when absent. example: America/New_York breakTimeInSec: type: integer description: >- Unpaid break seconds that fall inside this record's start/end window. The database derives it whenever the record is written, from `startDate`, `endDate`, and `shiftWorkHours`. Read-only: it cannot be written, and it is `0` while the record is still open. nullable: true externalSource: type: string description: System the session came from, for example `quickbase`. nullable: true externalSync: type: string description: Sync state for the external system. default: not synced example: synced metadata: type: object description: >- Free-form key-value store. No key is guaranteed to be present, and a missing key is not the same as a `null` one. See the resource guide for which paths populate `costCode` and `unionCode`. example: costCode: WELD-100 unionCode: LOCAL-7 additionalProperties: true createdAt: type: string format: date-time description: When the record was created. updatedAt: type: string format: date-time description: When the record last changed. rawStart: type: string format: date-time nullable: true readOnly: true description: >- Original clock start preserved when that boundary is processed. Null means this boundary has not been processed; fall back to startDate. rawEnd: type: string format: date-time nullable: true readOnly: true description: >- Original clock end preserved when that boundary is processed. Null means this boundary has not been processed; fall back to endDate. 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' NotFound: description: No record with that id in your organization. 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. ````