> ## 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 an asset's labels > Replaces the full set of labels on an asset 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 buyer company's catalog; unknown or cross-tenant ids are rejected with 400. The write is gated by the asset write permission: a key that can only read the asset gets 400. An unknown, deleted, or foreign asset id answers the same 400 as a denied write, so ids outside your tenant are not disclosed as 404s. ## OpenAPI ````yaml /openapi/buyer.json put /v1/buyer/asset/assets/{assetId}/labels openapi: 3.1.0 info: title: OpenWrench Buyer API version: 1.0.0 description: >- External REST API for OpenWrench buyers (facilities-management side). Generated from the application source (Play routes, controllers and models). ## Authentication Every request must carry a buyer API key in the `X-API-KEY` header. The key resolves to a buyer contact, and all reads/writes are tenant-scoped to that contact's buyer company (plus, on several endpoints, role-based location/brand restrictions). Endpoints under `/v1/buyer/super_admin/...` (and a few others noted per-operation) additionally require the key's contact to be a buyer super admin. ## Rate limiting 10 requests per 20-second window per API key; requests beyond that receive **429**. A handful of operations noted per-operation bypass the rate limiter. ## Response envelope Single-entity responses: `{ "type": "", "data": { ... }, "status": "ok" }`. List responses: `{ "type": "", "data": [ ... ], "count": , "status": "ok" }`. count_by responses: `{ "type": "CountBy", "data": , "status": "ok" }`. Errors: `{ "message": "...", "type": "", "status": "error", "traceId": "..." }` — 401 missing/invalid key, 400 bad input, 404 not found, 429 rate limit. ## Pagination & filtering List endpoints accept `offset`, `limit` (default 10, max 25 — the locations list clamps to 10), `sort_by` and `order` (asc|desc). Every other query parameter is treated as a filter and matched against the entity's indexed columns (multi-value filters are comma-separated strings); these are combined with the tenant-security filters derived from the API key. Timestamps are ISO 8601 strings unless noted otherwise. ## 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: Me - name: Locations - name: Regions - name: Asset Types - name: Asset Meters - name: Assets - name: Asset Labels description: Read the asset label catalog and replace the labels applied to an asset. - name: Asset Models - name: Work Orders - name: Work Order Notes - name: Work Order Labels description: >- Read your work order label catalog and replace the labels applied to a work order. - name: Service Calls - name: Site Survey Walkthroughs - name: Invoices - name: Proposals - name: Files - name: Planned Maintenance - name: Currency Exchange - name: Supplier Network - name: User Provisioning paths: /v1/buyer/asset/assets/{assetId}/labels: put: tags: - Asset Labels summary: Replace an asset's labels description: >- Replaces the full set of labels on an asset 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 buyer company's catalog; unknown or cross-tenant ids are rejected with 400. The write is gated by the asset write permission: a key that can only read the asset gets 400. An unknown, deleted, or foreign asset id answers the same 400 as a denied write, so ids outside your tenant are not disclosed as 404s. operationId: updateBuyerAssetLabels parameters: - name: assetId in: path required: true schema: type: integer description: Asset id. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LabelIdsRequest' responses: '200': description: Success. Returns the labels now active on the asset. content: application/json: schema: $ref: '#/components/schemas/AssetLabelListResponse' '400': description: >- Missing or non-array ids, a non-integer id, a label id outside your catalog, a denied write, or an unknown/foreign asset. 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 AssetLabelListResponse: type: object properties: type: type: string description: Entity type marker, "AssetLabel". data: type: array items: $ref: '#/components/schemas/AssetLabel' count: type: integer status: type: string enum: - ok required: - type - data - count - status Error: type: object properties: message: type: string type: type: string description: >- Exception type, e.g. unauthorizedException, NotFoundException, BadRequestException, ParseException, InvalidInputDataException, ConflictException, UnexpectedException. status: type: string enum: - error traceId: type: string description: >- Trace id (a random 11-char alphanumeric string when no explicit trace applies). required: - message - type - status - traceId description: >- Standard error envelope. 401 = missing/invalid API key, 400 = bad input, 404 = not found, 429 = rate limit exceeded. AssetLabel: type: object description: >- An asset label in the buyer company's catalog. Asset labels always belong to a buyer company; there is no supplier-facility tenancy. properties: id: type: integer label: type: string description: Display text of the label. color: type: - string - 'null' description: Display color, when set. associatedAssetsCount: type: integer description: Number of assets currently carrying this label. buyerCompanyId: type: integer 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 - associatedAssetsCount - buyerCompanyId - isDeleted 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. ````