> ## 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.
# Update folder
>
This endpoint requires [**Editor** permissions or higher](/share#content-access-permissions) on the folder being updated.
Update a folder's name and/or path segment. Either or both fields can be updated in a single request.
Name-only updates will not trigger updates to descendant folders (subfolders).
However, path updates will automatically update all descendent folder paths. Consider the following folder structure:
```text title="Existing paths with /blob-shared"
.
└── blob-shared
├── sales # full path: /blob-shared/sales
└── marketing # full path: /blob-shared/marketing
```
If the path for `blob-shared` is updated to `all-blobs`, the full paths for its descendent folders will be automatically updated:
```text title="New paths with /all-blobs"
.
└── all-blobs
├── sales # full path: /all-blobs/sales
└── marketing # full path: /all-blobs/marketing
```
## OpenAPI
````yaml /api/openapi.yaml patch /v1/folders/{folderId}
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/{folderId}:
patch:
tags:
- Folders
summary: Update folder
description: >
This endpoint requires [**Editor** permissions or higher](/share#content-access-permissions) on the folder being updated.
Update a folder's name and/or path segment. Either or both fields can be
updated in a single request.
operationId: updateFolder
parameters:
- name: folderId
in: path
required: true
schema:
type: string
format: uuid
description: >-
The UUID of the folder to update. Use the [List
folders](/api/folders/list-folders) endpoint to retrieve folder IDs.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: >
The new display name for the folder. Leading and trailing
whitespace is automatically trimmed.
At least one of `name` or `path` must be provided.
path:
type: string
description: >
The new URL path segment for the folder, which will
automatically be converted to lowercase. When a folder's
path is updated, all descendant folder paths are
automatically updated.
To be valid, path segments:
- Can contain only alphanumeric characters and dashes
- Cannot use reserved names: `favorite`, `labels`, `move`,
`share`, `transfer`. Folder names may include these words,
but the name cannot be only this word. For example,
`favorite` is invalid but `my-favorite` is not.
At least one of `name` or `path` must be provided.
resolvePathConflict:
type: boolean
default: false
description: >
When `true`, automatically resolves path conflicts by
appending a numeric suffix (e.g., `blob-sales-2`).
When `false` (default), returns a `409 Conflict` error if
the path already exists.
example:
name: Blob Sales Reports
path: sales-reports
resolvePathConflict: 'true'
responses:
'200':
description: Folder updated successfully
content:
application/json:
schema:
type: object
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
examples:
success:
summary: Successful update
value:
id: 3c90c3cc-0d44-4b50-8888-8dd25736052a
name: Blob Sales Reports
path: sales-reports
'400':
description: >
Bad Request
Possible error messages:
- `At least one of 'name' or 'path' must be provided`
- `Path cannot be one of the reserved names: favorite, labels, move,
share, transfer`
- `Path must contain only alphanumeric characters and dashes`
- Invalid JSON or validation errors
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
missingFields:
summary: No fields provided
value:
error: '400'
message: At least one of 'name' or 'path' must be provided
reservedPath:
summary: Reserved path name
value:
error: '400'
message: >-
Path cannot be one of the reserved names: favorite,
labels, move, share, transfer
invalidPathCharacters:
summary: Invalid path characters
value:
error: '400'
message: Path must contain only alphanumeric characters and dashes
'403':
description: >
Forbidden
Possible error messages:
- Permission denied. Authenticating user must have **Edit**
permissions on the folder.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: |
Not Found
Possible error messages:
- `Folder with id does not exist`
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: >
Conflict
Returned when `resolvePathConflict=false` (default) and the
requested path already exists in the parent folder.
Possible error messages:
- `A folder with path '' already exists at this location`
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
pathConflict:
summary: Path already exists
value:
error: '409'
message: >-
A folder with path 'sales-reports' already exists at this
location
'429':
$ref: '#/components/responses/TooManyRequests'
security:
- bearerAuth: []
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`
````