API Reference

NocoDB REST API — Schema Reference

Authoritative API reference for nocodb-dev. Two bundled OpenAPI specs:

For full payload shapes and per-endpoint details, see the bundled JSON files. Domain-grouped quick reference for the Meta API is in references/meta-api-endpoints.md. Per-type field config is in references/field-types.md.

Authentication

Both APIs accept the same two header schemes:

curl -sS \
  -H "xc-token: $NOCODB_API_TOKEN" \
  -H "Content-Type: application/json" \
  "$NOCODB_URL/api/v3/meta/bases/$BASE_ID"

Base URL

All requests go against $NOCODB_URL. The default server in the spec is https://app.nocodb.com; for self-hosted instances substitute your own host.

API Surface Map

nocodb-dev focuses on the Meta API because schema modification is its purpose. The Data API is bundled for completeness so dev workflows can verify data after schema changes without leaving the plugin.

Data API v3 — Quick Index

Meta API v3 — Quick Index (by domain)

See references/meta-api-endpoints.md for full request / response shapes.

Workspaces (5 ops): GET/POST /workspaces, GET/PATCH/DELETE /workspaces/{workspaceId}, plus ?include[]=members and team membership endpoints.

Bases (3 + 4 ops): GET/PATCH/DELETE /bases/{baseId}; member invite/update/delete under /bases/{base_id}/members; list bases via /workspaces/{workspaceId}/bases.

Tables (5 ops): GET/POST /bases/{base_id}/tables, GET/PATCH/DELETE /bases/{baseId}/tables/{tableId}.

Fields (4 ops): POST /bases/{baseId}/tables/{tableId}/fields, GET/PATCH/DELETE /bases/{baseId}/fields/{fieldId}.

Views (4 ops, single endpoint with type discriminator): GET/POST /bases/{baseId}/tables/{tableId}/views, GET/PATCH/DELETE /bases/{baseId}/views/{viewId}.

Filters (5 ops): per-view GET/POST/PUT /views/{viewId}/filters, PATCH/DELETE /filters/{filterId}.

Sorts (4 ops): per-view GET/POST /views/{viewId}/sorts, PATCH/DELETE /sorts/{sortId}.

Hooks (5 ops, V3 shape): GET/POST /tables/{tableId}/hooks, GET/PATCH/DELETE /hooks/{hookId}. event is record|manual; operation is array of insert/update/delete; uses trigger_fields (not a top-level condition).

Comments (5 ops): GET/POST /records/{recordId}/comments, PATCH/DELETE /comments/{commentId}, POST /comments/{commentId}/resolve.

Scripts (5 ops): GET/POST /scripts, GET/PATCH/DELETE /scripts/{script_id}. Referenced by Button fields and Script hook notifications.

Dashboards + Widgets (3 + 5 ops + 2 data endpoints): full /dashboards and per-dashboard /widgets CRUD plus /data GET on both.

Workflows + Executions (5 ops, read-and-execute only): GET /workflows, GET /workflows/{workflow_id}, POST /execute, list/get executions. Workflow authoring lives in the NocoDB UI.

Teams (7 ops): /workspaces/{workspaceId}/teams lifecycle plus per-team membership.

API Tokens (3 ops): GET/POST /tokens, DELETE /tokens/{tokenId}. Token returned once on create — store it immediately.

Reading the OpenAPI Files

Probe the meta spec when looking up an endpoint or schema:

META=skills/api-reference/references/nocodb-meta-openapi.json
DATA=skills/api-reference/references/nocodb-openapi.json

# All meta paths
jq -r '.paths | keys[]' "$META"

# A specific path's methods
jq '.paths."/api/v3/meta/bases/{baseId}/tables/{tableId}/views"' "$META"

# Hook payload shape
jq '.components.schemas.HookV3Create' "$META"

# All field-type option schemas
jq -r '.components.schemas | keys[] | select(startswith("FieldOptions_"))' "$META"

# A specific field type
jq '.components.schemas.FieldOptions_Formula' "$META"

# Widget option types
jq -r '.components.schemas | keys[] | select(startswith("WidgetOptions"))' "$META"

Field Types Catalog

The plugin supports 30 field types plus 4 system types that auto-populate. Full per-type config payloads are in references/field-types.md. Quick list:

SingleLineText, LongText, PhoneNumber, URL, Email, Number, Decimal, Currency, Percent, Duration, Date, DateTime, Time, Year, SingleSelect, MultiSelect, Rating, Checkbox, Attachment, JSON, Geometry, Links, LinkToAnotherRecord, Lookup, Rollup, Button, Formula, Barcode, QrCode, User, plus system: CreatedTime, LastModifiedTime, CreatedBy, LastModifiedBy.

Common Request Patterns

Get base info

curl -sS -H "xc-token: $NOCODB_API_TOKEN" \
  "$NOCODB_URL/api/v3/meta/bases/$BASE_ID"

List tables

curl -sS -H "xc-token: $NOCODB_API_TOKEN" \
  "$NOCODB_URL/api/v3/meta/bases/$BASE_ID/tables"

Create a table

curl -sS -X POST \
  -H "xc-token: $NOCODB_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Customers",
    "fields": [
      { "title": "Name",  "type": "SingleLineText" },
      { "title": "Email", "type": "Email" }
    ]
  }' \
  "$NOCODB_URL/api/v3/meta/bases/$BASE_ID/tables"

Create a field

curl -sS -X POST \
  -H "xc-token: $NOCODB_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Phone", "type": "PhoneNumber" }' \
  "$NOCODB_URL/api/v3/meta/bases/$BASE_ID/tables/$TABLE_ID/fields"

Update a field (rename)

curl -sS -X PATCH \
  -H "xc-token: $NOCODB_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Mobile" }' \
  "$NOCODB_URL/api/v3/meta/bases/$BASE_ID/fields/$FIELD_ID"

Create a Kanban view

curl -sS -X POST \
  -H "xc-token: $NOCODB_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Pipeline",
    "type":  "kanban",
    "options": { "fk_grp_col_id": "<singleSelectColumnId>" }
  }' \
  "$NOCODB_URL/api/v3/meta/bases/$BASE_ID/tables/$TABLE_ID/views"

Create a hook

curl -sS -X POST \
  -H "xc-token: $NOCODB_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Slack on new high-priority bug",
    "event": "record",
    "operation": ["insert"],
    "notification": {
      "type": "Messaging",
      "payload": {
        "channel": "Slack",
        "webhook_url": "https://hooks.slack.com/services/T0/B0/XXXX",
        "body": ":bug: {{record.Title}}"
      }
    },
    "active": true
  }' \
  "$NOCODB_URL/api/v3/meta/bases/$BASE_ID/tables/$TABLE_ID/hooks"

List records (Data API)

curl -sS -H "xc-token: $NOCODB_API_TOKEN" \
  "$NOCODB_URL/api/v3/data/$BASE_ID/$TABLE_ID/records?limit=10"

Errors

The error response schemas are referenced as 0, 1, 2, 3 in both spec files:

For schema-specific symptoms, see the troubleshoot skill.

See Also

• references/nocodb-meta-openapi.json — full Meta API spec (15 303 lines, 41 paths)
• references/nocodb-openapi.json — full Data API spec (10 889 lines, 7 paths)
• references/meta-api-endpoints.md — domain-grouped Meta API reference with payload shapes
• references/field-types.md — every field type with a minimal payload example
• cli-reference skill — equivalent operations via the nc command
• table-management / field-management / view-management / webhooks / dashboards / workflows — task-oriented skills built on this reference