Columns API - NocoDB

Overview

Columns are the fundamental building blocks of tables in NocoDB. The Columns API allows you to create, read, update, and delete columns with various data types and configurations.

Column Types

NocoDB supports a wide range of column types:

Text: SingleLineText, LongText, Email, URL, PhoneNumber
Numeric: Number, Decimal, Currency, Percent, Duration, Rating
Date & Time: Date, DateTime, Time, Year
Select: SingleSelect, MultiSelect
Relationship: LinkToAnotherRecord, Lookup, Rollup
Special: Attachment, Checkbox, QrCode, Barcode, JSON
Auto: ID, AutoNumber, CreatedTime, LastModifiedTime
User: User, Collaborator, CreatedBy, LastModifiedBy
Formula: Formula
Other: Button, GeoData, Geometry, AI, UUID

Create Column

Create a new column in a table.

curl -X POST "https://app.nocodb.com/api/v1/db/meta/tables/{tableId}/columns" \
  -H "xc-token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Full Name",
    "column_name": "full_name",
    "uidt": "SingleLineText"
  }'

Request Parameters

tableId

string

required

Unique identifier for the table

Request Body

title

string

required

Display title of the column (1-255 characters)

column_name

string

Database column name (auto-generated if not provided)

uidt

string

required

UI Data Type - determines the column type. See Column Types for available options

description

string

Column description (max 8192 characters)

string

Database data type (e.g., “varchar”, “int”)

dtxp

number | string

Data type precision (e.g., length for varchar)

dtxs

number | string

Data type scale (for decimal types)

rqd

boolean

Is required field (0 = false, 1 = true)

boolean

Is primary key (0 = false, 1 = true)

unique

boolean

Is unique constraint (0 = false, 1 = true)

cdf

string | number | boolean | null

Column default value

boolean

Is auto-increment (0 = false, 1 = true)

boolean

Auto update timestamp (0 = false, 1 = true)

Example: Create Select Column

curl -X POST "https://app.nocodb.com/api/v1/db/meta/tables/md_abc123/columns" \
  -H "xc-token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Status",
    "uidt": "SingleSelect",
    "colOptions": {
      "options": [
        {"title": "Todo", "color": "#ff0000"},
        {"title": "In Progress", "color": "#00ff00"},
        {"title": "Done", "color": "#0000ff"}
      ]
    }
  }'

Get Column

Retrieve a specific column by its ID.

curl -X GET "https://app.nocodb.com/api/v1/db/meta/columns/{columnId}" \
  -H "xc-token: YOUR_API_TOKEN"

Path Parameters

columnId

string

required

Unique identifier for the column

Response

string

Unique column identifier

title

string

Display title of the column

column_name

string

Database column name

uidt

string

UI data type (e.g., “SingleLineText”, “Number”)

string

Database data type

fk_model_id

string

Foreign key to the table this column belongs to

order

number

Display order of the column

boolean

Whether this is a primary key

boolean

Whether this is the primary value column

rqd

boolean

Whether this column is required

system

boolean

Whether this is a system column

unique

boolean

Whether this column has a unique constraint

Update Column

Update an existing column’s properties.

curl -X PATCH "https://app.nocodb.com/api/v1/db/meta/columns/{columnId}" \
  -H "xc-token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Title",
    "description": "New description"
  }'

Path Parameters

columnId

string

required

Unique identifier for the column to update

Request Body

Accepts the same parameters as Create Column. Only include fields you want to update.

title

string

New display title

description

string

New description

rqd

boolean

Update required status

Example: Update Column to Required

curl -X PATCH "https://app.nocodb.com/api/v1/db/meta/columns/cl_xyz789" \
  -H "xc-token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "rqd": 1,
    "description": "This field is now required"
  }'

Delete Column

Delete a column from a table.

curl -X DELETE "https://app.nocodb.com/api/v1/db/meta/columns/{columnId}" \
  -H "xc-token: YOUR_API_TOKEN"

Path Parameters

columnId

string

required

Unique identifier for the column to delete

Deleting a column will permanently remove all data in that column. This action cannot be undone.

Set Primary Value

Set a column as the primary display value for the table.

curl -X POST "https://app.nocodb.com/api/v1/db/meta/columns/{columnId}/primary" \
  -H "xc-token: YOUR_API_TOKEN"

Path Parameters

columnId

string

required

Unique identifier for the column

Response

success

boolean

Returns true if the operation was successful

The primary value column is used as the display value when this table is linked to other tables.

Bulk Column Operations

Perform multiple column operations in a single request.

curl -X POST "https://app.nocodb.com/api/v1/db/meta/tables/{tableId}/columns/bulk" \
  -H "xc-token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "hash": "abc123",
    "ops": [
      {
        "op": "add",
        "column": {
          "title": "New Column",
          "uidt": "SingleLineText"
        }
      },
      {
        "op": "update",
        "column": {
          "id": "cl_xyz789",
          "title": "Updated Title"
        }
      },
      {
        "op": "delete",
        "column": {
          "id": "cl_abc123"
        }
      }
    ]
  }'

Request Parameters

tableId

string

required

Unique identifier for the table

Request Body

hash

string

required

Hash of the current column state for optimistic locking

ops

array

required

Array of operations to perform

ops[].op

string

required

Operation type: add, update, or delete

ops[].column

object

required

Column object with properties based on the operation type

Get Columns Hash

Get a hash of the current column configuration for a table.

curl -X GET "https://app.nocodb.com/api/v1/db/meta/tables/{tableId}/columns/hash" \
  -H "xc-token: YOUR_API_TOKEN"

Path Parameters

tableId

string

required

Unique identifier for the table

Response

hash

string

Hash representing the current state of columns in the table

Use this hash for optimistic locking in bulk operations to ensure columns haven’t changed since you last read them.

Column Options

Different column types support specific options through the colOptions field:

Select Options

For SingleSelect and MultiSelect columns:

{
  "colOptions": {
    "options": [
      {"title": "Option 1", "color": "#ff0000"},
      {"title": "Option 2", "color": "#00ff00"}
    ]
  }
}

Link to Another Record

For LinkToAnotherRecord columns:

{
  "uidt": "LinkToAnotherRecord",
  "colOptions": {
    "fk_related_model_id": "md_xyz789",
    "type": "mm"
  }
}

Lookup

For Lookup columns:

{
  "uidt": "Lookup",
  "colOptions": {
    "fk_relation_column_id": "cl_abc123",
    "fk_lookup_column_id": "cl_def456"
  }
}

Rollup

For Rollup columns:

{
  "uidt": "Rollup",
  "colOptions": {
    "fk_relation_column_id": "cl_abc123",
    "fk_rollup_column_id": "cl_def456",
    "rollup_function": "count"
  }
}

Formula

For Formula columns:

{
  "uidt": "Formula",
  "colOptions": {
    "formula": "CONCAT({FirstName}, ' ', {LastName})"
  }
}

​Overview

​Column Types

​Create Column

​Request Parameters

​Request Body

​Example: Create Select Column

​Get Column

​Path Parameters

​Response

​Update Column

​Path Parameters

​Request Body

​Example: Update Column to Required

​Delete Column

​Path Parameters

​Set Primary Value

​Path Parameters

​Response

​Bulk Column Operations

​Request Parameters

​Request Body

​Get Columns Hash

​Path Parameters

​Response

​Column Options

​Select Options

​Link to Another Record

​Lookup

​Rollup

​Formula

Overview

Column Types

Create Column

Request Parameters

Request Body

Example: Create Select Column

Get Column

Path Parameters

Response

Update Column

Path Parameters

Request Body

Example: Update Column to Required

Delete Column

Path Parameters

Set Primary Value

Path Parameters

Response

Bulk Column Operations

Request Parameters

Request Body

Get Columns Hash

Path Parameters

Response

Column Options

Select Options

Link to Another Record

Lookup

Rollup

Formula