> ## 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.

# Add a data input table to a draft

> <Note>
  This endpoint requires edit access to the specified document and permissions to edit the document's model. The connection the document is built on must have a configured [table upload schema](/connect-data/setup).
</Note>

Add a [data input table](/analyze-explore/data-input-csvs) to a draft from rows in the request body. A CSV file is not accepted yet — convert it to rows first.

The rows become a private table in the connection's upload schema, a view and a topic on the document's workbook model, and a tab on the draft. The table only exists in the document's model.

Publish the draft with the [Publish draft endpoint](/api/documents-v2/publish-draft) to make the table available in the published document.



## OpenAPI

````yaml /api/openapi.yaml post /v2/documents/{identifier}/draft/{draftIdentifier}/csv-tables
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: Who Am I
    description: Inspect your own user permissions
  - name: AI
    description: AI-powered query generation
  - name: AI Credit Controls
    description: Manage organization-level AI credit usage
  - name: AI Credit Usage
    description: Monitor AI credit usage
  - name: AI Evals
    description: >-
      Manage prompt sets and runs used to score AI quality against curated
      prompt suites.
  - name: AI Model Suggestions
    description: Manage AI-generated suggestions for shared models
  - name: AI Routines
    description: >-
      Manage Routines, which are scheduled, recurring AI-powered tasks that run
      automatically on your data
  - name: Apps
    description: Draft and publish app documents.
  - name: App downloads
    description: Download apps as PNG, PDF, XLSX, or CSV files
  - name: Branches
    description: List branches and open or close them to Viewers and Restricted Queriers
  - name: Documents v2
    description: >
      A draft-based workflow for creating and editing documents: create a
      document, patch a draft, then publish.
  - name: Documents
    description: Create, retrieve, and manage documents
  - name: API Tokens
    description: >-
      Manage API tokens (Organization keys, Personal Access Tokens, MCP OAuth
      grants)
  - name: IP Allowlist
    description: Manage the organization's IP allowlist
  - name: Connections
    description: Manage database connections
  - name: Connection environments
    description: Manage connection environments database connections
  - name: Color Palettes
    description: Manage custom chart color palettes
  - 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: 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: Embed
    description: Manage embed sessions
  - name: Labels
    description: |
      Manage labels in the organization
  - name: Folders
    description: Create and organize content folders
  - name: Folder favorites
    description: Favorite and unfavorite folders
  - name: Folder labels
    description: Apply and manage labels on 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: Skills
    description: >-
      Manage skills, the saved slash-command instructions the Omni AI assistant
      runs
  - 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:
  /v2/documents/{identifier}/draft/{draftIdentifier}/csv-tables:
    post:
      tags:
        - Uploads
      summary: Add a data input table to a draft
      description: >-
        <Note>
          This endpoint requires edit access to the specified document and permissions to edit the document's model. The connection the document is built on must have a configured [table upload schema](/connect-data/setup).
        </Note>


        Add a [data input table](/analyze-explore/data-input-csvs) to a draft
        from rows in the request body. A CSV file is not accepted yet — convert
        it to rows first.


        The rows become a private table in the connection's upload schema, a
        view and a topic on the document's workbook model, and a tab on the
        draft. The table only exists in the document's model.


        Publish the draft with the [Publish draft
        endpoint](/api/documents-v2/publish-draft) to make the table available
        in the published document.
      operationId: documentsCreateCsvTable
      parameters:
        - name: draftIdentifier
          in: path
          schema:
            type: string
            example: def456
          required: true
          description: >-
            Draft identifier. Use [List document
            drafts](/api/documents/list-document-drafts) to retrieve draft IDs.
        - name: identifier
          in: path
          schema:
            type: string
            example: abc123
          required: true
          description: Published document identifier.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                columns:
                  type: array
                  minItems: 1
                  maxItems: 100
                  description: Every column of the table, in order.
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                        pattern: ^[a-zA-Z_][a-zA-Z0-9_]{0,62}$
                        description: The column's name, e.g. "due_date".
                      type:
                        type: string
                        enum:
                          - text
                          - integer
                          - number
                          - boolean
                          - date
                          - timestamp
                        description: >
                          The column's data type. See [Column
                          types](/analyze-explore/data-input-csvs#column-type)
                          for more information.
                    required:
                      - name
                      - type
                    additionalProperties: false
                  example:
                    - name: suggestion_id
                      type: text
                    - name: dismissed
                      type: boolean
                keyColumns:
                  type: array
                  description: >
                    **Supported for Postgres, Snowflake, Databricks, Lakebase,
                    BigQuery, Redshift, SQL Server, Fabric, and MotherDuck
                    connections.**
                      
                    The column(s) that uniquely identify a row. `null` or an
                    empty value means the table doesn't have a key. If a key is
                    set, every row must have a value for each key column.


                    See [Setting keys](/analyze-explore/data-input-csvs#csv-key)
                    for more information, including how to write to the table in
                    apps.
                name:
                  type: string
                  pattern: ^[a-z][a-z0-9_]*$
                  description: >
                    The name of the view in the document's workbook model that
                    uniquely identifies the table. This name is also used for
                    the table's topic and workbook tab.
                  example: dismissals
                rows:
                  type: array
                  items:
                    type: object
                    additionalProperties:
                      anyOf:
                        - type: string
                        - type: number
                        - type: boolean
                        - type: 'null'
                  maxItems: 1000
                  description: >-
                    The rows, each an object keyed by column name. For an empty
                    cell, omit the column or pass null. For ane mpty table, omit
                    entirely.
                  example:
                    - dismissed: true
                      suggestion_id: sg_1
              required:
                - columns
                - name
              additionalProperties: false
            example:
              name: dismissals
              columns:
                - name: suggestion_id
                  type: text
                - name: dismissed
                  type: boolean
              rows:
                - suggestion_id: sg_1
                  dismissed: true
              keyColumns:
                - suggestion_id
      responses:
        '201':
          description: >-
            The table was created and a tab added. `queryKey` is the new tab's
            key in the draft's `queryPresentations.data`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  draftIdentifier:
                    type: string
                    description: Identifier of the draft the table was added to.
                  identifier:
                    type: string
                    description: Published document identifier.
                  keyColumns:
                    type: array
                    nullable: true
                    items:
                      type: string
                    description: The key the table was given, or null.
                  queryKey:
                    type: string
                    description: >-
                      Record key of the tab added for the table in
                      `queryPresentations.data`.
                    example: '3'
                  topicName:
                    type: string
                    description: The topic the table can be queried through.
                    example: dismissals
                  truncated:
                    type: boolean
                    description: Whether the rows were cut at the upload row limit.
                  viewName:
                    type: string
                    description: The view the table's rows live in.
                    example: dismissals
                required:
                  - draftIdentifier
                  - identifier
                  - keyColumns
                  - queryKey
                  - topicName
                  - truncated
                  - viewName
              example:
                draftIdentifier: def456
                identifier: abc123
                keyColumns:
                  - suggestion_id
                queryKey: '3'
                topicName: dismissals
                truncated: false
                viewName: dismissals
        '400':
          description: >-
            Invalid body. Possible causes:


            - Rows that don't fit the declared column types or the key. A row
            that doesn't fit its column's type is named by its row in a
            spreadsheet view of the table, where the column header is row 1 —
            `Row 2` is the first row sent. An unknown column or a nested value
            is named by the row's position in `rows`, starting from 1.

            - Too many rows or bytes

            - Keys on a connection that doesn't support setting keys

            - The connection doesn't have a configured table upload schema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError400'
        '401':
          description: Authentication required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError401'
        '403':
          description: >-
            Insufficient permissions. No edit access to the document, or no
            upload or modeling rights on its model.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError403'
        '404':
          description: Document or draft not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError404'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: >-
            The document's model already has a view with that name, or the
            connection has no upload schema. Nothing was created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError409'
        '500':
          description: >-
            The server couldn't create the table, or it made the table but
            couldn't add its tab — the detail names the topic to add a tab from.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    ApiError400:
      type: object
      properties:
        detail:
          type: string
          description: Human-readable error message describing what went wrong.
        status:
          type: integer
          description: HTTP status code of the error.
          example: 400
      required:
        - detail
        - status
    ApiError401:
      type: object
      properties:
        detail:
          type: string
          description: Human-readable error message describing what went wrong.
          example: 'Unauthorized: Missing or invalid API key'
        status:
          type: integer
          description: HTTP status code of the error.
          example: 401
      required:
        - detail
        - status
    ApiError403:
      type: object
      properties:
        detail:
          type: string
          description: Human-readable error message describing what went wrong.
        status:
          type: integer
          description: HTTP status code of the error.
          example: 403
      required:
        - detail
        - status
    ApiError404:
      type: object
      properties:
        detail:
          type: string
          description: Human-readable error message describing what went wrong.
        status:
          type: integer
          description: HTTP status code of the error.
          example: 404
      required:
        - detail
        - status
    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>
    ApiError409:
      type: object
      properties:
        detail:
          type: string
          description: Human-readable error message describing what went wrong.
        status:
          type: integer
          description: HTTP status code of the error.
          example: 409
      required:
        - detail
        - status
  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`

````