Omni Content API

openapi: 3.2.0
info:
  title: Omni AI Content 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: Content
  description: Unified content retrieval (documents and folders)
paths:
  /v1/content:
    get:
      tags:
      - Content
      summary: Retrieve content
      description: Retrieve paginated list of documents and folders
      security:
      - bearerAuth: []
      operationId: getContent
      parameters:
      - name: labels
        in: query
        schema:
          type: string
        description: Filter content by labels. Provide as a comma-separated list (e.g., `finance,marketing`).
      - name: scope
        in: query
        schema:
          type: string
          enum:
          - restricted
          - organization
          default: organization
        description: Content scope filter
      - name: sortField
        in: query
        schema:
          type: string
          enum:
          - favorites
          - name
          - updatedAt
          default: name
        description: Field to sort by
      - $ref: '#/components/parameters/sortDirection'
      - name: include
        in: query
        schema:
          type: string
        description: 'Comma-separated list of additional fields to include in the response:

          - `_count` - Adds count metrics (folders: document and favorite counts; documents: favorite and view counts)

          - `labels` - Includes associated content labels

          '
      - name: folderId
        in: query
        schema:
          type: string
          format: uuid
        description: Returns all content in the specified folder. **Cannot be used with `path`.**
      - name: path
        in: query
        schema:
          type: string
        description: 'Filter content by path. **Cannot be used with `folderId`.** Examples:

          - `/folder/subfolder` - Returns the folder and any content it contains

          - `/folder/*` - Returns all folders and content recursively in the path

          - `/` - Returns all content in the organization

          '
      - name: creatorId
        in: query
        schema:
          type: string
          format: uuid
        description: UUID of organization membership. **Required when `scope` is `restricted`.**
      - name: pageSize
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
        description: Number of records per page (1-100)
      - name: cursor
        in: query
        schema:
          type: string
        description: Pagination cursor from previous response
      responses:
        '200':
          description: Paginated content list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
        '400':
          description: 'Bad Request


            Possible error messages:

            - `Page size must be at least 1`

            - `Page size cannot exceed 100`

            - `Invalid sort field`

            - `creatorId required when scope is restricted`

            - `Unrecognized query parameters`

            - `folderId and path cannot be used together`

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 'Not Found


            Possible error messages:

            - `User with id <uuid> does not exist`

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  responses:
    TooManyRequests:
      description: Too Many Requests - Rate limit exceeded (60 requests/minute)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    PaginatedResponse:
      type: object
      properties:
        records:
          type: array
          items:
            type: object
        pageInfo:
          $ref: '#/components/schemas/PageInfo'
    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>
    PageInfo:
      type: object
      description: Pagination information for paginated responses.
      properties:
        hasNextPage:
          type: boolean
          description: Indicates if there are more records available.
        nextCursor:
          type: string
          nullable: true
          description: Cursor for the next page of results. `null` if no more results.
        pageSize:
          type: integer
          description: Number of records per page.
        totalRecords:
          type: integer
          description: Total number of records matching the query.
  parameters:
    sortDirection:
      name: sortDirection
      in: query
      schema:
        type: string
        enum:
        - asc
        - desc
      description: 'Direction for sorting:


        - `asc` - Ascending order (A-Z, 0-9)

        - `desc` - Descending order (Z-A, 9-0)

        '
  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`

        '