> ## 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.
## Submitting Feedback
If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:
POST https://docs.omni.co/feedback
```json
{
"path": "/api/folders/list-folders",
"feedback": "Description of the issue"
}
```
Only submit feedback when you have something specific and actionable to report.
# List folders
> Retrieve a paginated list of folders within an organization. Supports filtering, sorting, and cursor-based pagination.
The folders endpoint behaves differently based on the type of API key used to authenticate the request:
- **Organization-scoped API keys:** Full access to all folders. Can view any user's restricted folders with `ownerId`. Must provide `ownerId` for `scope=restricted`.
- **Personal Access Tokens (PAT):** Permission-filtered access matching the UI.
- For `scope=organization` - Returns all organization-shared folders the user can access
- For `scope=restricted` - Returns only the user's own restricted folders. An `ownerId` is optional; if not provided, it will be auto-inferred and the API will return only the folders belonging to PAT owner.
## OpenAPI
````yaml /api/openapi.yaml get /v1/folders
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/folders:
get:
tags:
- Folders
summary: List folders
description: >
Retrieve a paginated list of folders within an organization. Supports
filtering, sorting, and cursor-based pagination.
The folders endpoint behaves differently based on the type of API key
used to authenticate the request:
- **Organization-scoped API keys:** Full access to all folders. Can view
any user's restricted folders with `ownerId`. Must provide `ownerId` for
`scope=restricted`.
- **Personal Access Tokens (PAT):** Permission-filtered access matching
the UI.
- For `scope=organization` - Returns all organization-shared folders the user can access
- For `scope=restricted` - Returns only the user's own restricted folders. An `ownerId` is optional; if not provided, it will be auto-inferred and the API will return only the folders belonging to PAT owner.
operationId: listFolders
parameters:
- name: include
in: query
schema:
type: string
description: >
Comma-separated list of additional fields to include:
- `_count` - Include document and favorite counts
- `labels` - Include folder labels
- `onlySharedWithMe` - Returns only folders explicitly shared with
the specified user via folder permissions. Excludes folders owned by
the user. Cannot be combined with `ownerId` or `path`.
Additionally, depending on the type of API key being used:
- **Organization API keys** require the `userId` parameter
- **Personal Access Tokens** automatically infer the `userId` from the token
- name: path
in: query
schema:
type: string
description: >
Filter folders by path. Wildcards are supported and must appear at
the end of the path:
- `*` - Include direct children only (e.g., `blob-sales/*`)
- `**` - Include all descendants recursively (e.g., `blob-sales/**`)
- name: labels
in: query
schema:
type: array
items:
type: string
description: Comma-separated list of labels to filter by.
- name: scope
in: query
schema:
type: string
enum:
- organization
- restricted
default: organization
description: >
Scope of folders to retrieve.
- When `include=onlySharedWithMe` is specified without a `scope`
parameter, returns shared folders of all scopes with each folder's
actual scope preserved
- Otherwise, defaults to `organization`
When set to `restricted`, the `ownerId` parameter behavior depends
on the API key type:
- **Organization-scoped API keys:** `ownerId` is required
- **Personal Access Tokens (PAT):** `ownerId` is optional and
auto-inferred to the token owner
- name: sortField
in: query
schema:
type: string
enum:
- favorites
- name
- path
default: name
description: |
Field to sort by:
- `favorites` - Sort by number of favorites
- `name` - Sort by folder name
- `path` - Sort by folder path
- name: sortDirection
in: query
schema:
type: string
enum:
- asc
- desc
default: desc
description: Sort direction.
- name: cursor
in: query
schema:
type: string
description: Cursor for pagination positioning.
- name: pageSize
in: query
schema:
type: integer
minimum: 1
default: 20
description: Number of items per page.
- name: ownerId
in: query
schema:
type: string
format: uuid
description: >
UUID of organization membership.
How the API behaves depends on the type of API key used to
authenticate the request and the current `scope` value.
**Personal Access Tokens (PAT)**
| Scope | ownerId | Behavior |
|-------|---------|----------|
| `organization` | Not provided | All organization-shared folders
user has permission to access |
| `organization` | own ID | Own organization folders only |
| `restricted` | Not provided | Infers owner's ID, returns own
restricted folders |
| `restricted` | Own ID | Own restricted folders |
| `restricted` | Other's ID | 403 Forbidden |
**Organization API key**
| Scope | ownerId | Behavior |
|-------|---------|----------|
| `organization` | Not provided | All organization folders |
| `organization` | Any ID | That user's organization folders |
| `restricted` | Not provided | 400 Bad Request (`ownerId` required)
|
| `restricted` | Any ID | That user's restricted folders |
- name: userId
in: query
schema:
type: string
format: uuid
description: >
The ID of a standard or embed user to filter results, returning only
folders the specified user can view based on their permissions.
If `include=onlyFavorites` is specified:
- **And using an Organization API key**, this parameter is
**required**
- **And using a Personal Access Token**, the `userId` will be
automatically inferred from the token
responses:
'200':
description: Paginated folder list
content:
application/json:
schema:
type: object
properties:
records:
type: array
description: Array of folder objects matching the query.
items:
$ref: '#/components/schemas/Folder'
pageInfo:
$ref: '#/components/schemas/PageInfo'
example:
records:
- id: 21db26b3-466c-4791-90e7-b9ce9375426d
name: Blob Sales
path: /blob-sales
scope: organization
url: https://blobsrus.omni.co/f/blob-sales-reports
owner:
id: f4df8d6e-7f69-4d54-b23b-7abfe5c4da74
name: Blob Ross
labels:
- important
- archived
_count:
documents: 15
favorites: 3
pageInfo:
hasNextPage: true
nextCursor: eyJpZCI6ImZvbGRlcjEyMyJ9
pageSize: 20
totalRecords: 45
'400':
description: >
Bad Request
Possible error messages:
- `Bad Request: pageSize: Page size must be at least 1`
- `Bad Request: ownerId: ownerId is required when scope is
'restricted'` (organization-scoped API keys only)
- `Bad Request: sortField: Invalid enum value. Expected 'name' |
'path', received ''`
- `Bad Request: include: Invalid value. Expected: _count, labels,
onlySharedWithMe, received ''`
- `Bad Request: Invalid path pattern. Only a single wildcard (*) is
allowed at the end of the pattern`
- `Bad Request: onlySharedWithMe requires userId` - When using
`include=onlySharedWithMe` with an Organization API key without
providing a `userId` parameter
- `Bad Request: onlySharedWithMe cannot be combined with ownerId` -
When using `include=onlySharedWithMe` with an `ownerId` parameter
- `Bad Request: onlySharedWithMe cannot be combined with path` -
When using `include=onlySharedWithMe` with a `path` parameter
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: >
Forbidden
Personal Access Tokens (PAT) cannot access other users' restricted
folders.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: |
Not Found
Possible error messages:
- `Folder with path does not exist`
- `User membership not found`
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
$ref: '#/components/responses/TooManyRequests'
security:
- bearerAuth: []
components:
schemas:
Folder:
type: object
description: Represents a folder in Omni.
properties:
id:
type: string
format: uuid
description: Unique identifier for the folder.
name:
type: string
description: Display name of the folder.
path:
type: string
description: Full path to the folder.
scope:
type: string
enum:
- organization
- restricted
description: |
Visibility scope of the folder.
- `organization` - Organization-wide access
- `restricted` - Limited access
owner:
type: object
description: Information about the folder owner.
properties:
id:
type: string
description: ID of the folder owner.
name:
type: string
description: Display name of the owner.
labels:
type: array
items:
type: string
description: >-
List of labels associated with the folder. Only included when
requested via the `include` parameter.
_count:
type: object
description: >-
Contains count information. Only included when requested via the
`include` parameter.
properties:
documents:
type: integer
description: Number of documents contained in the folder.
favorites:
type: integer
description: Number of users who favorited this folder.
createdAt:
type: string
format: date-time
description: Timestamp when the folder was created.
updatedAt:
type: string
format: date-time
description: Timestamp when the folder was last updated.
url:
type: string
format: uri
description: Direct link to the folder in the Omni UI.
example: https://blobsrus.omni.co/f/blob-sales-reports
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.
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`
````