> ## 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. # Create document > Create a new document ## OpenAPI ````yaml /api/openapi.yaml post /v1/documents 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/documents: post: tags: - Documents summary: Create document description: Create a new document operationId: createDocument requestBody: required: true content: application/json: schema: type: object required: - modelId - name properties: modelId: type: string format: uuid description: The ID of the model to build the document on name: type: string description: The name of the document description: type: string minLength: 1 maxLength: 1024 description: Description of the document identifier: type: string description: > Custom identifier for the document. If not provided, an identifier will be auto-generated. The identifier is used in the document's URL and must be unique across all documents in your organization. **Format requirements:** - Must match the pattern: lowercase letters, numbers, hyphens, and underscores only - Cannot start or end with a hyphen or underscore **Note:** Once created, the identifier can be changed using the [Update document endpoint](/api/documents/update-document). example: sales-dashboard-2026 queryPresentations: type: array description: >- An array of query presentation objects, each representing a query in the document's workbook items: type: object properties: name: type: string description: The name of the query description: type: string description: A description of the query query: type: object description: The query definition object visConfig: type: object description: Visualization configuration for the query examples: basicDocument: summary: Create document with auto-generated identifier value: modelId: a1b2c3d4-e5f6-7890-abcd-ef1234567890 name: Sales Dashboard description: Q1 2026 sales performance metrics customIdentifier: summary: Create document with custom identifier value: modelId: a1b2c3d4-e5f6-7890-abcd-ef1234567890 name: Sales Dashboard identifier: sales-dashboard-2026 description: Q1 2026 sales performance metrics responses: '200': description: Document created successfully content: application/json: schema: type: object properties: dashboard: type: object properties: id: type: string format: uuid description: The dashboard ID createdAt: type: string format: date-time description: Timestamp when the dashboard was created updatedAt: type: string format: date-time description: Timestamp when the dashboard was last updated metadata: type: object description: Dashboard metadata including layouts and tile settings properties: layouts: type: object description: Layout configurations for different screen sizes textTiles: type: array items: type: object hiddenTiles: type: array items: type: string tileSettings: type: object tileFilterMap: type: object tileControlMap: type: object metadataVersion: type: integer description: Version of the metadata schema refreshInterval: type: integer description: Auto-refresh interval in seconds facetFilters: type: boolean description: Whether facet filters are enabled organizationId: type: string format: uuid description: The organization ID workbookId: type: string format: uuid description: The associated workbook ID creatorId: type: string format: uuid description: The ID of the user who created the dashboard updaterId: type: string format: uuid description: The ID of the user who last updated the dashboard queryPresentationCollectionId: type: string format: uuid description: The query presentation collection ID dashboardId: type: string format: uuid description: The dashboard ID (same as id) workbook: type: object properties: id: type: string format: uuid description: The workbook ID createdAt: type: string format: date-time description: Timestamp when the workbook was created updatedAt: type: string format: date-time description: Timestamp when the workbook was last updated deletedAt: type: string format: date-time description: Timestamp when the workbook was deleted, if applicable publishedAt: type: string format: date-time description: Timestamp when the workbook was published isDraft: type: boolean description: Whether the workbook is a draft identifier: type: string description: The unique identifier for the document name: type: string description: The name of the document lastItemIndex: type: integer description: Index of the last item in the workbook ephemeral: type: string description: Ephemeral state identifier organizationRole: type: string description: Organization-level role for the document organizationAccessBoost: type: boolean publicRole: type: string publicAccessBoost: type: boolean canAnalyze: type: boolean description: Whether users can analyze data in the document canDownload: type: boolean description: Whether users can download data from the document canDrill: type: boolean description: Whether users can drill into data in the document canSchedule: type: boolean description: Whether users can create schedules in the document canUpload: type: boolean description: >- Whether users can upload data in the document's workbook canViewWorkbook: type: boolean description: Whether users can view the workbook in the document organizationId: type: string format: uuid description: The organization ID ownerId: type: string format: uuid description: The ID of the document owner updaterId: type: string format: uuid description: The ID of the user who last updated the document folderId: type: string format: uuid description: The folder ID, if the document is in a folder originDocumentId: type: string format: uuid description: The origin document ID, if duplicated documentId: type: string format: uuid description: The document ID '400': description: > Bad Request Possible error messages: - `modelId: Required` - `name: Required` - Identifier format is invalid (must be lowercase letters, numbers, hyphens, and underscores; cannot start/end with hyphen or underscore) - Identifier is already in use by another document content: application/json: schema: $ref: '#/components/schemas/Error' '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` ````