OpenAPI Specification
openapi: 3.0.0
info:
title: NocoDB Data Attachments Links API
version: '2.0'
description: RESTful API for querying and manipulating records across tables and views in any NocoDB base. Supports full CRUD operations on rows, filtering via where-clause operators, pagination, sorting, field selection, and bulk operations. Available in v2 and v3; v3 adds quoted-value support for special characters in query parameters.
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
security:
- xcToken: []
- bearerAuth: []
tags:
- name: Links
description: Link relationship operations between records
paths:
/api/v2/tables/{tableId}/links/{fieldId}/records/{recordId}:
get:
summary: List linked records
operationId: table-row-links-list
description: List all linked records for a specific link field on a record.
tags:
- Links
parameters:
- $ref: '#/components/parameters/tableId'
- name: fieldId
in: path
required: true
schema:
type: string
description: The link field identifier
- $ref: '#/components/parameters/recordId'
- $ref: '#/components/parameters/fields'
- $ref: '#/components/parameters/sort'
- $ref: '#/components/parameters/where'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/limit'
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Paginated'
- type: object
properties:
list:
type: array
items:
type: object
'400':
$ref: '#/components/responses/BadRequest'
security:
- xcToken: []
- bearerAuth: []
post:
summary: Link records
operationId: table-row-links-add
description: Link one or more records to a specific link field on a record.
tags:
- Links
parameters:
- $ref: '#/components/parameters/tableId'
- name: fieldId
in: path
required: true
schema:
type: string
- $ref: '#/components/parameters/recordId'
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- type: object
- type: array
items:
type: object
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
'400':
$ref: '#/components/responses/BadRequest'
security:
- xcToken: []
- bearerAuth: []
delete:
summary: Unlink records
operationId: table-row-links-remove
description: Remove links between records for a specific link field.
tags:
- Links
parameters:
- $ref: '#/components/parameters/tableId'
- name: fieldId
in: path
required: true
schema:
type: string
- $ref: '#/components/parameters/recordId'
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- type: object
- type: array
items:
type: object
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
'400':
$ref: '#/components/responses/BadRequest'
security:
- xcToken: []
- bearerAuth: []
components:
parameters:
tableId:
name: tableId
in: path
required: true
schema:
type: string
description: Unique identifier of the NocoDB table
offset:
name: offset
in: query
schema:
type: integer
default: 0
description: Number of rows to skip (for pagination)
fields:
name: fields
in: query
schema:
type: string
description: Comma-separated list of field names to include in the response
where:
name: where
in: query
schema:
type: string
description: 'Filter expression using NocoDB where-clause syntax. Example: (field,eq,value)~and(field2,gt,5)'
recordId:
name: recordId
in: path
required: true
schema:
type: string
description: Primary key value of the record
limit:
name: limit
in: query
schema:
type: integer
default: 25
maximum: 1000
description: Maximum number of rows to return per page
sort:
name: sort
in: query
schema:
type: string
description: Sort specification. Prefix field name with '-' for descending order. Multiple sorts can be comma-separated.
schemas:
Paginated:
title: Paginated
type: object
properties:
pageSize:
type: integer
totalRows:
type: integer
isFirstPage:
type: boolean
isLastPage:
type: boolean
page:
type: number
responses:
BadRequest:
description: BadRequest
content:
application/json:
schema:
type: object
properties:
msg:
type: string
example: 'BadRequest [Error]: <ERROR MESSAGE>'
required:
- msg
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.'
externalDocs:
description: NocoDB Developer Resources
url: https://nocodb.com/docs/product-docs/developer-resources/rest-apis