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.
openapi: 3.1.0
info:
title: Omni AI Labels API
description: "The Omni REST API provides programmatic access to your Omni instance for managing users, documents, queries, schedules, and more. \n"
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: 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.
'
paths:
/v1/labels:
post:
tags:
- Labels
summary: Create label
description: 'Create a new label in the organization.
Any user can create basic labels, but **Organization Admin** permissions are required to:
- Create **Verified** labels (`verified: true`)
- Create **Homepage** labels (`homepage: true`)
'
security:
- bearerAuth: []
operationId: createLabel
parameters:
- 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
required:
- name
properties:
name:
type: string
minLength: 2
maxLength: 25
description: 'Label name. Must be 2-25 characters.
Names are case-insensitive: `"Production"` and `"production"` are considered the same.
'
color:
type: string
maxLength: 9
default: null
description: 'Hex color for the label
'
example: '#0366d6'
description:
type: string
maxLength: 500
default: null
description: Description of the label
example: Documents based on dev schemas
verified:
type: boolean
default: false
description: '**Requires Organization Admin permissions**. If `true`, documents with this label will be marked as verified/curated.
'
homepage:
type: boolean
default: false
description: '**Requires Organization Admin permissions**. If `true`, documents with this label will display on the instance''s Homepage.
'
example:
name: Dev
color: '#0366d6'
description: Documents based on dev schemas
responses:
'201':
description: Label created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Label'
example:
name: Dev
verified: true
homepage: true
usage_count: 0
color: '#0366d6'
description: Documents based on dev schemas
'400':
description: 'Bad Request. Possible causes:
- Label name too short (less than 2 characters)
- Label name too long (more than 25 characters)
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: 'Forbidden. Possible causes:
- User lacks **Organization Admin** permissions, which are required to create Verified and Homepage labels
- User lacks the permissions required to manage labels
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: 'Conflict. A label with this name already exists (case-insensitive).
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
$ref: '#/components/responses/TooManyRequests'
get:
tags:
- Labels
summary: List labels
description: Retrieve all labels in the organization.
security:
- bearerAuth: []
operationId: listLabels
responses:
'200':
description: List of all labels in the organization
content:
application/json:
schema:
type: object
properties:
labels:
type: array
items:
$ref: '#/components/schemas/Label'
example:
labels:
- name: Production
verified: true
homepage: true
usage_count: 12
color: '#000000'
description: Documents verified and in prod
- name: In Review
verified: true
homepage: false
usage_count: 5
color: '#CCCCCC'
description: Documents in review
- name: Draft
verified: false
homepage: false
usage_count: 3
color: '#EEEEEE'
description: Drafts that need review
'429':
$ref: '#/components/responses/TooManyRequests'
/v1/labels/{labelName}:
get:
tags:
- Labels
summary: Get label
description: Retrieve a single label by name.
security:
- bearerAuth: []
operationId: getLabel
parameters:
- name: labelName
in: path
required: true
schema:
type: string
description: 'The label name. Lookup is case-insensitive.
URL-encode special characters (e.g., `In%20Review` for "In Review").
'
responses:
'200':
description: Label details
content:
application/json:
schema:
$ref: '#/components/schemas/Label'
example:
name: Production
verified: true
homepage: true
usage_count: 12
color: '#000000'
description: Documents verified and in prod
'404':
description: Label not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
$ref: '#/components/responses/TooManyRequests'
put:
tags:
- Labels
summary: Update label
description: 'Update an existing label, including renaming, changing **Verified** status, or adding/removing it from the **Homepage**.
Users can update basic labels they created. **Organization Admin** permissions are required to modify **Verified** or **Homepage** labels, including making a label `verified` or visible on the `homepage`.
'
security:
- bearerAuth: []
operationId: updateLabel
parameters:
- name: name
in: path
required: true
schema:
type: string
description: 'The name of the label to update. Lookup is case-insensitive.
URL-encode special characters.
'
- 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:
description: 'Only include the fields you want to update when submitting requests.
'
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
minLength: 2
maxLength: 25
description: The new name of the label.
verified:
type: boolean
description: '**Organization Admin permissions required**. If `true`, documents with the label will be marked as **Verified**.
'
homepage:
type: boolean
description: '**Organization Admin permissions required**. If `true`, documents with the label will be visible on the **Homepage**.
'
color:
type: string
maxLength: 9
default: null
description: 'Hex color for the label
'
example: '#0366d6'
description:
type: string
maxLength: 500
default: null
description: Description of the label
example: Documents based on dev schemas
example:
name: Ready for Review
color: '#DDDDDD'
description: Documents that are ready for review
responses:
'200':
description: Label updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Label'
example:
name: Ready for Review
verified: true
homepage: false
usage_count: 3
color: '#DDDDDD'
description: Documents that are ready for review
'400':
description: 'Bad Request. Possible causes:
- Name too short or too long
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: 'Forbidden. Possible causes:
- User lacks permission to manage labels
- User lacks **Organization Admin** permissions, which are required to modify **Verified** labels
- User lacks **Organization Admin** permissions, which are required to modify **Homepage** labels
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Label not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: 'Conflict. The new label name already exists (case-insensitive).
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
$ref: '#/components/responses/TooManyRequests'
x-codeSamples:
- lang: bash
label: Rename label
source: "curl -X PUT \"https://{instance}.omniapp.co/api/v1/labels/Draft\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\": \"Ready for Review\"}'\n"
- lang: bash
label: Set verified (admin)
source: "curl -X PUT \"https://{instance}.omniapp.co/api/v1/labels/Production\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"verified\": true, \"homepage\": true}'\n"
delete:
tags:
- Labels
summary: Delete label
x-mint:
content: "<Warning>\n Labels that are currently applied to documents cannot be deleted. You must first remove the label from all documents.\n</Warning>\n"
description: 'Delete a label from the organization.
Any user can delete basic labels, but **Organization Admin** permissions are required to delete **Verified** and **Homepage** labels.
'
security:
- bearerAuth: []
operationId: deleteLabel
parameters:
- name: name
in: path
required: true
schema:
type: string
description: 'The name of the label to delete. Lookup is case-insensitive.
URL-encode special characters.
'
- 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.
'
responses:
'204':
description: Label deleted successfully. No response body.
'403':
description: 'Forbidden. Possible causes:
- User lacks permission to manage labels
- User lacks **Organization Admin** permissions, which are required to delete **Verified** labels
- User lacks **Organization Admin** permissions, which are required to delete **Homepage** labels
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Label not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: 'Conflict. The label is currently applied to documents and cannot be deleted.
Remove the label from all documents first.
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
$ref: '#/components/responses/TooManyRequests'
components:
schemas:
Label:
type: object
description: A label for organizing and categorizing documents and folders
properties:
name:
type: string
description: 'The label name (2-25 characters).
Names are case-insensitive: `"Production"` and `"production"` are considered the same.
'
example: Production
verified:
type: boolean
description: Whether the label is verified/curated
example: true
homepage:
type: boolean
description: Whether the label appears on the organization homepage
example: false
usage_count:
type: integer
description: Total number of documents and folders using this label
example: 12
color:
type: string
maxLength: 9
default: null
description: 'Hex color for the label
'
example: '#0366d6'
description:
type: string
maxLength: 500
default: null
description: Description of the label
example: Documents based on dev schemas
Error:
type: object
properties:
error:
type: string
description: HTTP response code for the error
example: <response_code>
message:
type: string
description: Detailed error description
example: <error_reason>
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#token-types).
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`
'