> ## Documentation Index > Fetch the complete documentation index at: https://docs.omni.co/llms.txt > Use this file to discover all available pages before exploring further. # Bulk update document labels Add and/or remove multiple labels from a document in a single atomic operation. When using this endpoint, keep in mind that: * **All changes succeed or fail together.** No partial updates occur. * **Label matching is case-insensitive**. * **Requests must have at least one operation.** Either `add` or `remove` must contain at least one label. * **Labels must already exist to be added to or removed from a document.** Create labels via the [Create label API](/api/labels/create-label). * **Labels cannot be included in both `add` and `remove` in the same request.** * **Organization Admin permissions are required to**: * Add or remove **Verified** labels * Add or remove **Homepage** labels ## OpenAPI ````yaml /api/openapi.yaml patch /v1/documents/{documentId}/labels openapi: 3.1.0 info: title: Omni API description: > The Omni REST API provides programmatic access to your Omni instance for managing users, documents, queries, schedules, and more. version: 1.0.0 contact: name: Omni Support url: https://docs.omni.co servers: - url: https://{instance}.omniapp.co/api description: Production variables: instance: default: blobsrus description: Your production Omni instance subdomain - url: https://{instance}.playground.exploreomni.dev/api description: Playground variables: instance: default: blobsrus description: Your playground Omni instance subdomain security: - bearerAuth: [] - orgApiKey: [] tags: - name: AI description: AI-powered query generation - name: API Tokens description: >- Manage API tokens (Organization keys, Personal Access Tokens, MCP OAuth grants) - name: Connections description: Manage database connections - name: Connection environments description: Manage connection environments database connections - name: Content description: Unified content retrieval (documents and folders) - name: Content migration description: Export and import dashboards - name: Content validator description: Validate content against models and perform find/replace operations - name: Dashboard downloads description: Download dashboards and tiles as PDF, PNG, XLSX, CSV, or JSON files - name: Dashboard filters and controls description: Read and update dashboard filter and control default values - name: dbt description: Manage dbt configuration for connections - name: Documents description: Create, retrieve, and manage documents - name: Document favorites description: Favorite and unfavorite documents - name: Document labels description: Apply and manage labels on documents - name: Document permissions description: Manage document-level access - name: Labels description: > Manage labels in an organization. Labels can be applied to documents and folders to help organize and categorize content. **Label types:** - **Basic labels**: Can be created and managed by any user - **Verified labels**: Indicate curated or officially sanctioned content. Admin-only. - **Homepage labels**: Appear on the organization homepage. Admin-only. - name: Folders description: Create and organize content folders - name: Folder permissions description: Manage folder-level access - name: Jobs description: Check status of asynchronous jobs - name: Models description: Create and manage data models - name: Model branches description: Manage model branches and merge changes - name: Model git configuration description: Manage git configuration for shared models - name: Queries description: Execute workbook queries - name: Schedules description: Create and manage scheduled tasks - name: Schedule recipients description: Manage schedule recipients - name: Schema refresh schedules description: Manage automated schema refresh schedules for connections - name: Topics description: Retrieve topic information from models - name: Uploads description: Manage file uploads - name: Users description: Manage users - name: User attributes description: Manage user attribute definitions - name: User groups description: Manage user groups - name: User model roles description: Manage model and connection role assignments for users - name: User group model roles description: Manage model and connection role assignments for user groups - name: Uploads description: Manage CSV and spreadsheet uploads paths: /v1/documents/{documentId}/labels: patch: tags: - Document labels summary: Bulk update document labels operationId: bulkUpdateDocumentLabels parameters: - name: documentId in: path required: true schema: type: string format: uuid description: The document identifier (UUID) - name: userId in: query required: false schema: type: string description: > **Requires an Organization API key**. Optional user ID that attributes the action to the specified user. requestBody: required: true content: application/json: schema: type: object properties: add: type: array items: type: string minLength: 2 maxLength: 25 default: [] description: Label names to add to the document remove: type: array items: type: string minLength: 2 maxLength: 25 default: [] description: Label names to remove from the document examples: addLabels: summary: Add labels value: add: - production - reviewed removeLabels: summary: Remove labels value: remove: - draft - needs-review addAndRemove: summary: Add and remove labels value: add: - approved remove: - pending-review responses: '200': description: Labels updated successfully content: application/json: schema: type: object properties: labels: type: array items: type: string description: The updated list of labels on the document example: labels: - label-one - label-two - new-label '400': description: | Bad Request. Possible causes: - Empty request - Neither `add` nor `remove` contains any labels - Label appears in both `add` and `remove` arrays - Invalid label name (less than 2 or more than 25 characters) content: application/json: schema: $ref: '#/components/schemas/Error' examples: emptyRequest: summary: Empty request value: detail: >- Bad Request: At least one label must be specified in add or remove status: 400 title: Bad Request conflictingLabels: summary: Label in both arrays value: detail: >- Bad Request: Labels cannot appear in both add and remove arrays status: 400 title: Bad Request '403': description: > Forbidden. Possible causes: - User does not have `canLabel` permission on the document - User lacks Organization Admin permissions to modify Verified labels - User lacks Organization Admin permissions to modify Homepage labels content: application/json: schema: $ref: '#/components/schemas/Error' examples: permissionDenied: summary: Permission denied value: detail: >- You do not have permission to modify labels on this document. status: 403 title: Forbidden verifiedLabelDenied: summary: Verified label permission denied value: detail: >- You do not have permission to modify Verified labels on this document status: 403 title: Forbidden '404': description: > Not Found. Possible causes: - Document does not exist - Label does not exist globally. Create the label first with the [Create label API](/api/labels/create-label). - Label in `remove` array does not exist on the document content: application/json: schema: $ref: '#/components/schemas/Error' examples: documentNotFound: summary: Document not found value: detail: Document with identifier "abc123" not found status: 404 title: Not Found labelNotFound: summary: Label not found globally value: detail: Label "my-label" not found status: 404 title: Not Found labelNotOnDocument: summary: Label not on document value: detail: > Labels not found on this document: "label-one", "label-two" status: 404 title: Not Found '429': $ref: '#/components/responses/TooManyRequests' security: - bearerAuth: [] - orgApiKey: [] components: schemas: Error: type: object properties: error: type: string description: HTTP response code for the error example: message: type: string description: Detailed error description example: responses: TooManyRequests: description: Too Many Requests - Rate limit exceeded (60 requests/minute) content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: > Can be either an [Organization API Key](/api/authentication#organization-api-keys) or [Personal Access Token (PAT)](/api/authentication#personal-access-tokens-pat). Include in the `Authorization` header as: `Bearer YOUR_TOKEN` orgApiKey: type: http scheme: bearer bearerFormat: JWT description: > Requires an [Organization API Key](/api/authentication#organization-api-keys). Personal Access Tokens (PATs) are not supported for this endpoint. Include in the `Authorization` header as: `Bearer ORGANIZATION_API_KEY` ````