openapi: 3.0.0
info:
  title: NocoDB Meta API
  version: "2.0"
  description: >-
    RESTful API for managing NocoDB metadata including workspaces, bases,
    tables, fields, views, hooks (webhooks), scripts, and user permissions.
    Collaboration-related meta operations require Business plan or higher;
    View and Script APIs require Enterprise tier or licensed self-hosted
    Business+.
  contact:
    name: NocoDB
    url: https://nocodb.com
  license:
    name: GNU Affero General Public License v3.0
    url: https://github.com/nocodb/nocodb/blob/develop/LICENSE
servers:
  - url: https://app.nocodb.com
    description: NocoDB Cloud
externalDocs:
  description: NocoDB Developer Resources
  url: https://nocodb.com/docs/product-docs/developer-resources/rest-apis
tags:
  - name: Auth
    description: Authentication and token management
  - name: Workspaces
    description: Workspace management operations
  - name: Bases
    description: Base (database) management operations
  - name: Tables
    description: Table management operations
  - name: Fields
    description: Field/column management operations
  - name: Views
    description: View management operations
  - name: Hooks
    description: Webhook management operations
  - name: Users
    description: User and team management
paths:
  /api/v1/auth/user/signin:
    post:
      summary: Sign in
      operationId: auth-user-signin
      description: Authenticate a user with email and password to receive an auth token.
      tags:
        - Auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - password
              properties:
                email:
                  type: string
                  format: email
                password:
                  type: string
                  format: password
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                    description: JWT auth token
        '400':
          $ref: '#/components/responses/BadRequest'
  /api/v1/auth/token/list:
    get:
      summary: List API tokens
      operationId: auth-token-list
      description: List all API tokens for the authenticated user.
      tags:
        - Auth
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ApiToken'
        '400':
          $ref: '#/components/responses/BadRequest'
      security:
        - bearerAuth: []
  /api/v1/auth/token:
    post:
      summary: Create API token
      operationId: auth-token-create
      description: Create a new API token for the authenticated user.
      tags:
        - Auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - description
              properties:
                description:
                  type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiToken'
        '400':
          $ref: '#/components/responses/BadRequest'
      security:
        - bearerAuth: []
  /api/v1/auth/token/{tokenId}:
    delete:
      summary: Delete API token
      operationId: auth-token-delete
      description: Delete an API token by its identifier.
      tags:
        - Auth
      parameters:
        - name: tokenId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
      security:
        - bearerAuth: []
  /api/v1/meta/bases:
    get:
      summary: List bases
      operationId: base-list
      description: List all bases accessible to the authenticated user.
      tags:
        - Bases
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  list:
                    type: array
                    items:
                      $ref: '#/components/schemas/Base'
                  pageInfo:
                    $ref: '#/components/schemas/Paginated'
        '400':
          $ref: '#/components/responses/BadRequest'
      security:
        - xcToken: []
        - bearerAuth: []
    post:
      summary: Create base
      operationId: base-create
      description: Create a new NocoDB base.
      tags:
        - Bases
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BaseReq'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Base'
        '400':
          $ref: '#/components/responses/BadRequest'
      security:
        - xcToken: []
        - bearerAuth: []
  /api/v1/meta/bases/{baseId}:
    get:
      summary: Read base
      operationId: base-read
      description: Retrieve details of a specific base by its identifier.
      tags:
        - Bases
      parameters:
        - $ref: '#/components/parameters/baseId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Base'
        '400':
          $ref: '#/components/responses/BadRequest'
      security:
        - xcToken: []
        - bearerAuth: []
    patch:
      summary: Update base
      operationId: base-update
      description: Update metadata of a specific base.
      tags:
        - Bases
      parameters:
        - $ref: '#/components/parameters/baseId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BaseReq'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
      security:
        - xcToken: []
        - bearerAuth: []
    delete:
      summary: Delete base
      operationId: base-delete
      description: Delete a specific base and all its data.
      tags:
        - Bases
      parameters:
        - $ref: '#/components/parameters/baseId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
      security:
        - xcToken: []
        - bearerAuth: []
  /api/v1/meta/bases/{baseId}/tables:
    get:
      summary: List tables
      operationId: table-list
      description: List all tables within a specific base.
      tags:
        - Tables
      parameters:
        - $ref: '#/components/parameters/baseId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  list:
                    type: array
                    items:
                      $ref: '#/components/schemas/Table'
                  pageInfo:
                    $ref: '#/components/schemas/Paginated'
        '400':
          $ref: '#/components/responses/BadRequest'
      security:
        - xcToken: []
        - bearerAuth: []
    post:
      summary: Create table
      operationId: table-create
      description: Create a new table within a base.
      tags:
        - Tables
      parameters:
        - $ref: '#/components/parameters/baseId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TableReq'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Table'
        '400':
          $ref: '#/components/responses/BadRequest'
      security:
        - xcToken: []
        - bearerAuth: []
  /api/v1/meta/tables/{tableId}:
    get:
      summary: Read table
      operationId: table-read
      description: Retrieve details of a specific table including its fields and views.
      tags:
        - Tables
      parameters:
        - $ref: '#/components/parameters/tableId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Table'
        '400':
          $ref: '#/components/responses/BadRequest'
      security:
        - xcToken: []
        - bearerAuth: []
    patch:
      summary: Update table
      operationId: table-update
      description: Update metadata of a specific table.
      tags:
        - Tables
      parameters:
        - $ref: '#/components/parameters/tableId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TableReq'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
      security:
        - xcToken: []
        - bearerAuth: []
    delete:
      summary: Delete table
      operationId: table-delete
      description: Delete a specific table and all its records.
      tags:
        - Tables
      parameters:
        - $ref: '#/components/parameters/tableId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
      security:
        - xcToken: []
        - bearerAuth: []
  /api/v1/meta/tables/{tableId}/fields:
    get:
      summary: List fields
      operationId: field-list
      description: List all fields (columns) for a specific table.
      tags:
        - Fields
      parameters:
        - $ref: '#/components/parameters/tableId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  list:
                    type: array
                    items:
                      $ref: '#/components/schemas/Field'
        '400':
          $ref: '#/components/responses/BadRequest'
      security:
        - xcToken: []
        - bearerAuth: []
    post:
      summary: Create field
      operationId: field-create
      description: Add a new field (column) to a specific table.
      tags:
        - Fields
      parameters:
        - $ref: '#/components/parameters/tableId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FieldReq'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Field'
        '400':
          $ref: '#/components/responses/BadRequest'
      security:
        - xcToken: []
        - bearerAuth: []
  /api/v1/meta/fields/{fieldId}:
    patch:
      summary: Update field
      operationId: field-update
      description: Update a specific field configuration.
      tags:
        - Fields
      parameters:
        - name: fieldId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FieldReq'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
      security:
        - xcToken: []
        - bearerAuth: []
    delete:
      summary: Delete field
      operationId: field-delete
      description: Delete a specific field from a table.
      tags:
        - Fields
      parameters:
        - name: fieldId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
      security:
        - xcToken: []
        - bearerAuth: []
  /api/v1/meta/tables/{tableId}/views:
    get:
      summary: List views
      operationId: view-list
      description: List all views for a specific table.
      tags:
        - Views
      parameters:
        - $ref: '#/components/parameters/tableId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  list:
                    type: array
                    items:
                      $ref: '#/components/schemas/View'
        '400':
          $ref: '#/components/responses/BadRequest'
      security:
        - xcToken: []
        - bearerAuth: []
  /api/v1/meta/tables/{tableId}/hooks:
    get:
      summary: List webhooks
      operationId: hook-list
      description: List all webhooks (hooks) configured for a specific table.
      tags:
        - Hooks
      parameters:
        - $ref: '#/components/parameters/tableId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  list:
                    type: array
                    items:
                      $ref: '#/components/schemas/Hook'
                  pageInfo:
                    $ref: '#/components/schemas/Paginated'
        '400':
          $ref: '#/components/responses/BadRequest'
      security:
        - xcToken: []
        - bearerAuth: []
    post:
      summary: Create webhook
      operationId: hook-create
      description: Create a new webhook for a specific table.
      tags:
        - Hooks
      parameters:
        - $ref: '#/components/parameters/tableId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HookReq'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Hook'
        '400':
          $ref: '#/components/responses/BadRequest'
      security:
        - xcToken: []
        - bearerAuth: []
components:
  parameters:
    baseId:
      name: baseId
      in: path
      required: true
      schema:
        type: string
      description: Unique identifier of the NocoDB base
    tableId:
      name: tableId
      in: path
      required: true
      schema:
        type: string
      description: Unique identifier of the NocoDB table
  schemas:
    Paginated:
      title: Paginated
      type: object
      properties:
        pageSize:
          type: integer
        totalRows:
          type: integer
        isFirstPage:
          type: boolean
        isLastPage:
          type: boolean
        page:
          type: number
    Attachment:
      title: Attachment
      type: object
      properties:
        mimetype:
          type: string
        size:
          type: integer
        title:
          type: string
        url:
          type: string
        icon:
          type: string
    ApiToken:
      title: ApiToken
      type: object
      properties:
        id:
          type: string
        fk_user_id:
          type: string
        description:
          type: string
        token:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Base:
      title: Base
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        description:
          type: string
        fk_workspace_id:
          type: string
        type:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    BaseReq:
      title: BaseReq
      type: object
      required:
        - title
      properties:
        title:
          type: string
        description:
          type: string
    Table:
      title: Table
      type: object
      properties:
        id:
          type: string
        fk_model_id:
          type: string
        title:
          type: string
        table_name:
          type: string
        type:
          type: string
          enum: [table, view]
        columns:
          type: array
          items:
            $ref: '#/components/schemas/Field'
        views:
          type: array
          items:
            $ref: '#/components/schemas/View'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    TableReq:
      title: TableReq
      type: object
      required:
        - title
      properties:
        title:
          type: string
        table_name:
          type: string
        columns:
          type: array
          items:
            $ref: '#/components/schemas/FieldReq'
    Field:
      title: Field
      type: object
      properties:
        id:
          type: string
        fk_model_id:
          type: string
        title:
          type: string
        column_name:
          type: string
        uidt:
          type: string
          description: UI data type
        dt:
          type: string
          description: Database data type
        pv:
          type: boolean
          description: Primary value field
        pk:
          type: boolean
          description: Primary key field
        required:
          type: boolean
        unique:
          type: boolean
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    FieldReq:
      title: FieldReq
      type: object
      required:
        - title
        - uidt
      properties:
        title:
          type: string
        column_name:
          type: string
        uidt:
          type: string
          description: >-
            UI data type. Supported values: SingleLineText, LongText, Attachment,
            Checkbox, MultiSelect, SingleSelect, Date, Year, Time, PhoneNumber,
            Email, URL, Number, Decimal, Currency, Percent, Duration, Rating,
            Formula, Rollup, Count, Lookup, DateTime, CreateTime, LastModifiedTime,
            AutoNumber, Geometry, JSON, SpecificDBType, Text, Barcode, QrCode, Links
        required:
          type: boolean
        unique:
          type: boolean
    View:
      title: View
      type: object
      properties:
        id:
          type: string
        fk_model_id:
          type: string
        title:
          type: string
        type:
          type: integer
          description: View type (1=Grid, 2=Form, 3=Gallery, 4=Kanban, 5=Calendar)
        lock_type:
          type: string
          enum: [collaborative, locked, personal]
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Hook:
      title: Hook
      type: object
      properties:
        id:
          type: string
        fk_model_id:
          type: string
        title:
          type: string
        description:
          type: string
        event:
          type: string
          enum: [after.insert, after.update, after.delete, after.bulkInsert, after.bulkUpdate, after.bulkDelete]
        operation:
          type: string
        active:
          type: boolean
        notification:
          type: object
          properties:
            type:
              type: string
            payload:
              type: object
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    HookReq:
      title: HookReq
      type: object
      required:
        - title
        - event
        - notification
      properties:
        title:
          type: string
        description:
          type: string
        event:
          type: string
          enum: [after.insert, after.update, after.delete, after.bulkInsert, after.bulkUpdate, after.bulkDelete]
        active:
          type: boolean
        notification:
          type: object
          required:
            - type
          properties:
            type:
              type: string
            payload:
              type: object
  securitySchemes:
    xcToken:
      type: apiKey
      in: header
      name: xc-token
      description: NocoDB API token
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Bearer token authentication. Use 'Authorization: Bearer <token>'
        header format.
  responses:
    BadRequest:
      description: BadRequest
      content:
        application/json:
          schema:
            type: object
            properties:
              msg:
                type: string
                example: 'BadRequest [Error]: <ERROR MESSAGE>'
            required:
              - msg
security:
  - xcToken: []
  - bearerAuth: []