Linked Records API

Create links between records in different tables and manage relationships.

6 endpoints

Endpoints

POST

/api/v1/linkedRecords/createLinkField

Create a link field to connect two tables. Params: tableId (source table), name (field name), linkedTableId (target table), linkType ("one_to_one", "one_to_many", "many_to_many"), linkDisplayMode ("COUNT", "LABELS", "CHIPS"), allowMultipleLinks (boolean), createReciprocal (default true, creates reverse link in target table).

Parameters

`tableId`	stringrequired	Source table ID from listTables
`name`	stringrequired	Name for the link field
`description`	string	Optional description
`linkedTableId`	stringrequired	Target table ID to link to
`linkType`	stringrequired	Relationship type: "one_to_one", "one_to_many", or "many_to_many"
`linkDisplayMode`	string	Display mode: "COUNT", "LABELS", or "CHIPS"
`allowMultipleLinks`	boolean	Allow linking to multiple records
`linkOnDelete`	string	What happens to linking rows when a linked record is deleted: RESTRICT blocks the delete while links exist; CASCADE deletes the linking rows too (chains, capped at 500 rows per delete); SET_NULL (default) / NO_ACTION just remove the connection
`linkOnUpdate`	string	Action on update
`createReciprocal`	boolean	Create reciprocal field in target table

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/linkedRecords/createLinkField \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "tableId": "example",
  "name": "example",
  "description": "example"
}'

POST

/api/v1/linkedRecords/linkRecords

Link records together. Params: tableId (source), recordId (source row ID), fieldId (link field ID), linkedRecordIds (array of target row IDs, at most 1,000 a call), preserveOrder.

Parameters

`tableId`	stringrequired	Source table ID
`recordId`	stringrequired	Source row ID to link from
`fieldId`	stringrequired	Link field ID
`linkedRecordIds`	arrayrequired	Array of target row IDs to link to (at most 1,000)
`preserveOrder`	boolean	Preserve order of linked records

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/linkedRecords/linkRecords \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "tableId": "example",
  "recordId": "example",
  "fieldId": "example"
}'

POST

/api/v1/linkedRecords/unlinkRecords

Remove links. Params: tableId, recordId, fieldId, linkedRecordIds (array of IDs to unlink, at most 1,000 a call). Act only on what the person named or picked.

Parameters

`tableId`	stringrequired	Source table ID
`recordId`	stringrequired	Source row ID
`fieldId`	stringrequired	Link field ID
`linkedRecordIds`	arrayrequired	Array of target row IDs to unlink (at most 1,000)

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/linkedRecords/unlinkRecords \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "tableId": "example",
  "recordId": "example",
  "fieldId": "example"
}'

POST

/api/v1/linkedRecords/getLinkedRecords

Get linked records for a row. Params: tableId, recordId, fieldId, limit (a whole number from 1 to 200, default 50; at most 200), offset (a whole number from 0 to 100,000, at most 100,000), sortBy (field to sort by), sortDirection ("asc"|"desc"). Always returns the summarized shape { id, primaryFieldValue, metadata } per linked record — the "expand" flag is currently accepted but ignored (no full-record payload), so fetch the target rows directly if you need all fields.

Parameters

`tableId`	stringrequired	Source table ID
`recordId`	stringrequired	Source row ID
`fieldId`	stringrequired	Link field ID
`expand`	boolean	Include full record data
`limit`	integer	Max records to return: a whole number from 1 to 200 (default 50; at most 200)
`offset`	integer	Skip records for pagination: a whole number from 0 to 100,000 (at most 100,000)
`sortBy`	string	Field to sort by
`sortDirection`	string	Sort direction

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/linkedRecords/getLinkedRecords \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "tableId": "example",
  "recordId": "example",
  "fieldId": "example"
}'

POST

/api/v1/linkedRecords/bulkLinkRecords

Bulk link operations. Params: tableId, fieldId, operations (array of {sourceRecordId, targetRecordIds, operation: "link"|"unlink"|"replace"}): at most 100 operations a call, each with at most 1,000 targetRecordIds, and at most 1,000 targetRecordIds in total across all the operations of one call (link, replace and unlink alike): split a bigger change into several calls.

Parameters

`tableId`	stringrequired	Source table ID
`fieldId`	stringrequired	Link field ID
`operations`	arrayrequired	Array of link operations to perform (at most 100; at most 1,000 target IDs in total across all operations)

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/linkedRecords/bulkLinkRecords \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "tableId": "example",
  "fieldId": "example",
  "operations": {}
}'

POST

/api/v1/linkedRecords/reorderLinkedRecords

Change link order. Params: tableId, recordId, fieldId, orderedRecordIds (array in desired order, at most 1,000).

Parameters

`tableId`	stringrequired	Source table ID
`recordId`	stringrequired	Source row ID
`fieldId`	stringrequired	Link field ID
`orderedRecordIds`	arrayrequired	Target row IDs in desired order (at most 1,000)

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/linkedRecords/reorderLinkedRecords \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "tableId": "example",
  "recordId": "example",
  "fieldId": "example"
}'