> ## 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 a context file

> <Note>
  This endpoint is experimental and may change.
</Note>

Creates a context file in either the `organization` or `personal` scope. `organization` files can only be created by **Organization Admins**.



## OpenAPI

````yaml /api/openapi.yaml post /v1/context-files
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: Context Files
    description: >-
      Manage context files, the markdown files the Omni Agent reads as
      organization or personal standing context
  - 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:
  /v1/context-files:
    post:
      tags:
        - Context Files
      summary: Create a context file
      description: >-
        <Note>
          This endpoint is experimental and may change.
        </Note>


        Creates a context file in either the `organization` or `personal` scope.
        `organization` files can only be created by **Organization Admins**.
      operationId: contextFilesCreate
      parameters:
        - name: userId
          in: query
          schema:
            type: string
            format: uuid
          required: false
          description: >
            **Requires an Organization API key**. ID of the user who will own
            the file.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                content:
                  type: string
                  pattern: \S
                  description: >-
                    The file's markdown body, up to 20000 characters. Blank or
                    whitespace-only content is refused.
                  example: Fiscal years start in February.
                name:
                  type: string
                  description: >
                    A unique name for the new file. `.md` is added if not
                    included.


                    If the specified `scope` already has a file with the same
                    name, the API returns an error.
                  example: finance.md
                scope:
                  type: string
                  enum:
                    - organization
                    - personal
                  description: >
                    Defines the file's scope:


                    - `organiztion` - Organization-level files used by default
                    in all agent sessions in the organization

                    - `personal` - Files owned by the caller or the specified
                    `userId`, which the agent only reads in sessions with that
                    user
                  example: personal
              required:
                - content
                - name
                - scope
              additionalProperties: false
            example:
              scope: personal
              name: finance
              content: Report revenue in EUR.
      responses:
        '201':
          description: The created file, without its body
          content:
            application/json:
              schema:
                type: object
                properties:
                  file:
                    $ref: '#/components/schemas/ContextFileSummary'
                required:
                  - file
              example:
                file:
                  id: b2c3d4e5-f6a7-8901-bcde-f12345678901
                  name: finance.md
                  type: always_context
                  updatedAt: '2026-02-01T09:30:00.000Z'
                  characters: 22
        '400':
          description: >
            Invalid request. Possible causes:


            - Invalid body

            - Blank `content`

            - Invalid `name`

            - Body over the length limit

            - The scope already holds 20 `always_context` files, the most one
            scope can hold

            - The scope already holds 500 files of any type, the most one scope
            can hold


            New files are created as `always_context`. To free room, change an
            existing file's type to `on_demand_context` or delete one from the
            Omni UI.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError400'
              example:
                detail: >-
                  This location already holds 20 required files, the most it
                  can. Save this file as contextual, or first make another
                  required file contextual or delete one.
                status: 400
        '403':
          description: >
            Possible causes:


            - Invalid bearer token

            - The caller is an embed user

            - A user-scoped key named another member

            - The caller is not an organization admin and the file is an
            organization file, or may not create personal files
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError403'
        '404':
          description: |
            `userId` names a user who isn't a member of the organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError404'
        '405':
          $ref: '#/components/responses/ApiError405'
        '409':
          description: >-
            The scope already has a file with this name; the message gives its
            `id`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError409'
components:
  schemas:
    ContextFileSummary:
      type: object
      properties:
        characters:
          type: integer
          minimum: 0
          description: The number of characters in the file's body content
          example: 31
        id:
          type: string
          format: uuid
          description: Unique identifier for the file
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        name:
          type: string
          description: File name, ending in `.md`
          example: AGENTS.md
        type:
          type: string
          enum:
            - always_context
            - on_demand_context
          description: >
            When the AI reads the file: 


            - `always_context` - The file is sent with every message 

            - `on_demand_context` - The file is only listed by name and the AI
            opens it when a question needs it
          example: always_context
        updatedAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp of the last edit
          example: '2026-02-01T09:30:00.000Z'
      required:
        - characters
        - id
        - name
        - type
        - updatedAt
    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
    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
    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
  responses:
    ApiError405:
      description: Method Not Allowed
      content:
        application/json:
          schema:
            type: object
            required:
              - detail
              - status
            properties:
              detail:
                type: string
                description: Human-readable error message describing what went wrong.
                example: Method Not Allowed
              status:
                type: integer
                description: HTTP status code of the error.
                example: 405
  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`

````