> ## Documentation Index
> Fetch the complete documentation index at: https://basedash.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a definition

> Creates a new definition within an organization. Requires admin access to the organization.



## OpenAPI

````yaml https://charts.basedash.com/api/public/openapi post /api/public/organizations/{orgId}/definitions
openapi: 3.1.0
info:
  title: Basedash Public API
  version: 0.0.0
  description: >-
    API for programmatic access to Basedash features. Use API keys for
    authentication.
  contact:
    name: Basedash Support
    url: https://basedash.com
    email: support@basedash.com
servers:
  - url: https://charts.basedash.com
    description: Production
security: []
tags:
  - name: Organizations
    description: Manage organizations
  - name: Groups
    description: Manage organization groups and memberships
  - name: Data Sources
    description: Manage database connections and data sources
  - name: MCP servers
    description: Manage MCP server data sources
  - name: Insights
    description: Manage generated insights
  - name: Automations
    description: Manage automations and automation runs
  - name: Skills
    description: Manage organization skills
  - name: Definitions
    description: Manage reusable SQL definitions
  - name: Dashboards
    description: Manage dashboards and their tabs
  - name: Charts
    description: Manage charts and their SQL queries
  - name: Chats
    description: >-
      Chat with the Basedash AI agent about your data. Start a chat by sending a
      message, then continue the conversation with follow-up messages. The
      assistant responds asynchronously: pass the `wait` query parameter to
      receive the finished response in the same request, or poll the assistant
      message (or stream its events) after an HTTP 202. Chats created through
      the API are not shown in the Basedash app.
paths:
  /api/public/organizations/{orgId}/definitions:
    post:
      tags:
        - Definitions
      summary: Create a definition
      description: >-
        Creates a new definition within an organization. Requires admin access
        to the organization.
      parameters:
        - schema:
            type: string
            description: Organization ID
          required: true
          description: Organization ID
          name: orgId
          in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDefinitionInput'
      responses:
        '201':
          description: Definition created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/DefinitionResponse'
                required:
                  - data
        '400':
          description: Bad request - Invalid JSON body or validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found - Organization, data source, or admin access not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict - Definition reference name already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded - Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - bearerAuth: []
components:
  schemas:
    CreateDefinitionInput:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
          description: Human-readable definition name
        referenceName:
          type: string
          minLength: 1
          maxLength: 100
          description: Stable SQL reference name for the definition
        description:
          type: string
          maxLength: 10000
          description: Definition description
        databaseConnectionId:
          type: string
          description: Data source ID
        sqlQuery:
          type: string
          minLength: 1
          maxLength: 100000
          description: SQL query that defines the reusable dataset
      required:
        - name
        - databaseConnectionId
        - sqlQuery
    DefinitionResponse:
      type: object
      properties:
        id:
          type: string
          description: Definition ID
        createdAt:
          type: string
          format: date-time
          description: Definition creation timestamp
        updatedAt:
          type: string
          format: date-time
          description: Definition last update timestamp
        name:
          type: string
          description: Human-readable definition name
        referenceName:
          type: string
          description: Stable SQL reference name for the definition
        description:
          type: string
          description: Definition description
        sqlQuery:
          type: string
          description: SQL query for the latest definition version
        organizationId:
          type: string
          description: Organization ID
        databaseConnectionId:
          type: string
          description: Data source ID
      required:
        - id
        - createdAt
        - updatedAt
        - name
        - referenceName
        - description
        - sqlQuery
        - organizationId
        - databaseConnectionId
    ErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ApiError'
      required:
        - error
    RateLimitErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/RateLimitError'
      required:
        - error
    ApiError:
      type: object
      properties:
        title:
          type: string
          description: Error type identifier
        detail:
          type: string
          description: Human-readable error description
      required:
        - title
        - detail
    RateLimitError:
      allOf:
        - $ref: '#/components/schemas/ApiError'
        - type: object
          properties:
            title:
              type: string
              enum:
                - RateLimitExceeded
            retryAfterMs:
              type: number
              description: Milliseconds until the rate limit window resets
          required:
            - retryAfterMs
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key authentication using Bearer token format: `Bearer
        <basedash_api_key>`

````