> ## Documentation Index > Fetch the complete documentation index at: https://api-docs.useopenwrench.com/llms.txt > Use this file to discover all available pages before exploring further. # Replace a work order's labels > Replaces the full set of labels on a work order with the ids in the body; labels not listed are removed, and an empty ids array clears them all. Every id must be a live label of your own catalog; unknown or cross-tenant ids are rejected with 400. The write is gated by the work order write permission: a key that can only read the work order gets 400. On an unassigned work order, only a facility with read-write visibility may label it; bidders and read-only facilities get 400. An unknown, deleted, or foreign work order id answers the same 400 as a denied write, so ids outside your tenant are not disclosed as 404s. ## OpenAPI ````yaml /openapi/supplier.json put /v1/supplier/work_order/work_orders/{woId}/labels openapi: 3.1.0 info: title: OpenWrench Supplier API version: 1.0.0 description: >- External REST API for OpenWrench suppliers (service providers). ## Authentication Every request must carry a supplier API key in the `X-API-KEY` header. The key resolves to a supplier contact; all reads and writes are tenant-scoped to that contact's supplier facility/company. Missing or invalid keys are answered with 401. ## Rate limiting 10 requests per 20-second window per API key. Requests beyond that are answered with 429 and the standard error envelope. (A few endpoints, noted in their descriptions, are not rate-limited.) ## Response envelope Single entity: `{"type": "", "data": {...}, "status": "ok"}`. Lists: `{"type": "", "data": [...], "count": , "status": "ok"}`. count_by endpoints return the integer count in `data`. The `type` label is hard-coded on some endpoints (e.g. "WorkOrderNotes", "pingpong") and derived via Scala reflection on generic CRUD endpoints, where it may appear as the fully qualified server class name - treat it as informational. Errors: `{"message": "...", "type": "", "status": "error", "traceId": "..."}` with HTTP 400 (bad input, and also permission-denied reads/writes), 401 (missing/invalid key), 404 (not found), 429 (rate limit). ## Pagination List endpoints accept `offset`, `limit` (default 10, max 25 - the supplier locations list caps at 10), `sort_by` and `order` (`asc`|`desc`), plus entity-specific query-string filters on indexed columns. ## Data masking For third-party suppliers (keys whose supplier company is not a buyer's internal service team), work order, location and invoice responses are masked: buyer-private fields are blanked before the response is returned. ## Date formats Date-time fields serialize as strings in one of two shapes depending on the underlying type: ISO 8601 with offset (e.g. `2026-08-14T13:05:22.000-07:00`) for most timestamps, or `yyyy-MM-dd HH:mm:ss.S` (space-separated, no offset) for database timestamp fields. Plain dates are `yyyy-MM-dd`. When sending date-times, ISO 8601 is accepted. ## Required headers Every request must carry BOTH `X-API-KEY` (your API key) and `OW-KEY` (the OpenWrench shared secret issued with it). Requests missing either return 401. servers: - url: https://api.useopenwrench.com/api/external security: - ApiKeyAuth: [] OwKeyAuth: [] tags: - name: Ping - name: Buyer Companies - name: Locations - name: Regions - name: Asset Types - name: Assets - name: Asset Labels description: Read the asset label catalog and replace the labels applied to an asset. - name: Work Orders - name: Work Order Labels description: >- Read the work order label catalog visible to your key and replace the labels applied to a work order. - name: Service Calls - name: WrenchMode description: Read-only WrenchMode work logs and technician time analytics - name: Proposals - name: Invoices - name: Files - name: Purchase Requests - name: Purchase Orders - name: Purchase Order Receipts - name: Parts - name: Equipment Types - name: Stock Location Inventory - name: Vendors - name: Users paths: /v1/supplier/work_order/work_orders/{woId}/labels: put: tags: - Work Order Labels summary: Replace a work order's labels description: >- Replaces the full set of labels on a work order with the ids in the body; labels not listed are removed, and an empty ids array clears them all. Every id must be a live label of your own catalog; unknown or cross-tenant ids are rejected with 400. The write is gated by the work order write permission: a key that can only read the work order gets 400. On an unassigned work order, only a facility with read-write visibility may label it; bidders and read-only facilities get 400. An unknown, deleted, or foreign work order id answers the same 400 as a denied write, so ids outside your tenant are not disclosed as 404s. operationId: updateSupplierWorkOrderLabels parameters: - name: woId in: path required: true schema: type: integer description: Work order id. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LabelIdsRequest' responses: '200': description: Success. Returns the label mappings now active on the work order. content: application/json: schema: $ref: '#/components/schemas/WorkOrderLabelMappingListResponse' '400': description: >- Missing or non-array ids, a non-integer id, a label id outside your catalog, a denied write, or an unknown/foreign work order. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Missing or invalid X-API-KEY. content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Rate limit exceeded (10 requests per 20-second window per key). content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: LabelIdsRequest: type: object description: >- Full replacement set of label ids. Send an empty array to clear all labels. properties: ids: type: array items: type: integer description: >- Ids of labels from the corresponding label catalog. Duplicates are de-duplicated. required: - ids WorkOrderLabelMappingListResponse: type: object properties: type: type: string description: Entity type marker, "WorkOrderLabelMapping". data: type: array items: $ref: '#/components/schemas/WorkOrderLabelMapping' count: type: integer description: >- Number of mappings returned (the labels now active on the work order). status: type: string enum: - ok required: - type - data - count - status Error: type: object properties: message: type: string description: Human-readable error message type: type: string description: >- Exception type identifier. Known values (exact casing): "unauthorizedException", "authorizationException", "ParseException", "UnexpectedException", "NotFoundException", "BadRequestException", "PaymentRequiredException", "InvalidInputDataException", "ConflictException", "ForbiddenException", "InvalidInputException" status: type: string enum: - error traceId: type: string description: >- Server-generated trace identifier for support (11 alphanumeric characters) required: - message - type - status - traceId description: Standard error envelope returned for 4xx/5xx responses. WorkOrderLabelMapping: type: object description: >- One label currently applied to a work order, hydrated with the label itself. properties: id: type: integer workOrderId: type: integer workOrderLabelId: type: integer workOrderLabel: $ref: '#/components/schemas/WorkOrderLabel' action: type: string enum: - added - removed isActive: type: boolean createdBy: type: string createdByContact: $ref: '#/components/schemas/Contact' createdAt: type: string required: - workOrderId - workOrderLabelId - action - isActive - createdBy - createdAt WorkOrderLabel: type: object description: >- A work order label in the caller's tenant catalog. Buyer-owned labels carry buyerCompanyId; labels owned by a third-party supplier facility carry supplierFacilityId. properties: id: type: integer label: type: string description: Display text of the label. color: type: - string - 'null' description: Display color, when set. buyerCompanyId: type: - integer - 'null' supplierFacilityId: type: - integer - 'null' associatedWorkOrdersCount: type: integer description: Number of work orders currently carrying this label. createdBy: type: - string - 'null' createdAt: type: - string - 'null' updatedBy: type: - string - 'null' updatedAt: type: - string - 'null' isDeleted: type: boolean deletedAt: type: - string - 'null' required: - label - associatedWorkOrdersCount - isDeleted Contact: type: object properties: email: type: string nameGiven: type: string nameFamily: type: string title: anyOf: - type: string - type: 'null' department: anyOf: - type: string - type: 'null' facilityId: anyOf: - type: integer - type: 'null' contactType: type: string description: '"buyer" or "supplier"' isSharedContact: type: boolean readOnlyAccess: anyOf: - type: boolean - type: 'null' invitedByEmail: anyOf: - type: string - type: 'null' invitedAt: anyOf: - type: string format: date-time description: ISO 8601 date-time - type: 'null' epaCertificationType: anyOf: - type: string - type: 'null' epaCertificationNumber: anyOf: - type: string - type: 'null' createdAt: anyOf: - type: string format: date-time description: ISO 8601 date-time - type: 'null' updatedAt: anyOf: - type: string format: date-time description: ISO 8601 date-time - type: 'null' required: - email - nameGiven - nameFamily - contactType description: >- Contact record (abridged - the full Contact model carries additional fields). additionalProperties: true securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-KEY OwKeyAuth: type: apiKey in: header name: OW-KEY description: >- OpenWrench shared secret. Required on every request alongside X-API-KEY; issued together with your API key. ````