> ## 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.
# Upload a CSV file
>
To use this endpoint:
- The **Upload data** setting in **Settings > Content permissions** must enabled by an **Organization Admin**
- The authenticating user must have **Restricted Querier** permissions or higher on the model the file will be uploaded to
Upload a CSV file to create a new [data input table](/analyze-explore/data-input-csvs). The file is parsed, converted to Arrow format, uploaded to storage, written to the connection's table upload (scratch) schema, and a view is created in the specified model.
Uploaded files:
- Must be a CSV file with `.csv` extension
- Can have a maximum of 500,000 rows. Files will be truncated if this limit is exceeded.
## OpenAPI
````yaml /api/openapi.yaml post /v1/uploads
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/uploads:
post:
tags:
- Uploads
summary: Upload a CSV file
description: >
To use this endpoint:
- The **Upload data** setting in **Settings > Content permissions** must enabled by an **Organization Admin**
- The authenticating user must have **Restricted Querier** permissions or higher on the model the file will be uploaded to
Upload a CSV file to create a new [data input
table](/analyze-explore/data-input-csvs). The file is parsed, converted
to Arrow format, uploaded to storage, written to the connection's table
upload (scratch) schema, and a view is created in the specified model.
Uploaded files:
- Must be a CSV file with `.csv` extension
- Can have a maximum of 500,000 rows. Files will be truncated if this
limit is exceeded.
operationId: uploadCsvFile
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
required:
- file
- modelId
properties:
file:
type: string
format: binary
description: The CSV file to upload, which must have a `.csv` extension
modelId:
type: string
format: uuid
description: UUID of the model to create the view in
example: 880e8400-e29b-41d4-a716-446655440003
branchId:
type: string
format: uuid
description: >-
UUID of the branch to create the view in. Mutually exclusive
with `branchName`.
example: 990e8400-e29b-41d4-a716-446655440004
branchName:
type: string
description: >-
Name of the branch to create the view in. Mutually exclusive
with `branchId`.
example: my-branch
viewName:
type: string
description: Override the view name. Defaults to sanitized file name.
example: custom_view_name
encoding:
file:
contentType: text/csv
responses:
'201':
description: CSV file uploaded successfully and view created.
content:
application/json:
schema:
type: object
properties:
id:
type: string
format: uuid
description: Unique identifier for the upload
fileName:
type: string
description: Original file name
viewName:
type: string
description: Name of the view created
modelId:
type: string
format: uuid
description: ID of the model the view was created in
inDbAsTableName:
type: string
description: Database table name in the scratch schema
rowCount:
type: integer
description: Number of rows in the uploaded file
truncated:
type: boolean
description: >-
Whether the file was truncated due to row limit (500,000
rows)
viewCreated:
type: boolean
description: Whether a view was created in the model
example:
id: 550e8400-e29b-41d4-a716-446655440000
fileName: users.csv
viewName: users
modelId: 880e8400-e29b-41d4-a716-446655440003
inDbAsTableName: omni_upload_t550e8400
rowCount: 150
truncated: false
viewCreated: true
'400':
description: |
Bad Request. Possible error messages include:
- Missing required fields (`file` or `modelId`)
- Invalid file type (not a CSV file)
- CSV parsing failed
- Invalid UUID format
- Both `branchId` and `branchName` provided (mutually exclusive)
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
detail: 'Bad Request: file must have .csv extension'
status: 400
'401':
description: Missing or invalid authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
detail: Unauthorized
status: 401
'403':
description: >-
Insufficient permissions. Authenticating user must have **Restricted
Querier** permissions or higher on the model.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
detail: You do not have permission to perform this action
status: 403
'404':
description: |
Not Found. Possible error messages include:
- Model not found (invalid `modelId`)
- Branch not found (invalid `branchId` or `branchName`)
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
detail: Model not found
status: 404
'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`
````