Relationships

Link and unlink records; list a record's links.

Start with: relationships_link, relationships_link_batch, relationships_list, relationships_unlink.

4 operations. Discover them from an agent with agentdb_capabilities {"category": "relationships"}.

#`relationships_link`

stable added in 0.2.0-alpha.4 or earlier changes data

Link two records using a relationship defined on the source record's object type.

MCP tool: relationships_link
REST: POST /v1/workspaces/{ws}/links scope records:write

Arguments

Argument	Type	Required	Description
`relationship`	`string`	yes	Relationship type name.
`source_record_id`	`string`	yes	Id of the record the link starts from.
`target_record_id`	`string`	yes	Id of the record the link points to.
`idempotency_key`	`string`		Optional retry key ([A-Za-z0-9._:-], max 255). Repeating a call with the same key and arguments returns the original result without writing again.
`workspace`	`string`		Workspace id (preferred), slug or exact name. Omit for the default workspace. Resolve names once with workspace_select.

Example

MCP

{
  "tool": "relationships_link",
  "arguments": {
    "relationship": "works_at",
    "source_record_id": "rec_example",
    "target_record_id": "rec_example_company"
  }
}

MCP via agentdb_execute

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "relationships_link",
    "arguments": {
      "relationship": "works_at",
      "source_record_id": "rec_example",
      "target_record_id": "rec_example_company"
    }
  }
}

REST

curl -s -X POST "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/links" \
  -H "Authorization: Bearer $AGENTDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"relationship":"works_at","source_record_id":"rec_example","target_record_id":"rec_example_company"}'

#`relationships_link_batch`

stable added in 0.2.0-alpha.4 or earlier changes data

Create up to 500 links of one relationship in one transaction. Name each side by record id (source_record_id/target_record_id) or by one unique field value (source_key/target_key, e.g. {"email": "a@x.example"} -> {"name": "Acme"}). atomic=true (default): any failing link rejects the batch with BATCH_REJECTED and nothing is written. atomic=false: valid links are saved and failures are listed. skip_existing=true reports already-linked pairs as exists instead of failing. client_ref on a link is echoed in its result.

MCP tool: relationships_link_batch
REST: POST /v1/workspaces/{ws}/links/batch scope records:write

Arguments

Argument	Type	Required	Description
`source_object`	`string`	yes	Object type of the records the links start from.
`relationship`	`string`	yes	Relationship type name.
`atomic`	`boolean`		boolean, default true
`skip_existing`	`boolean`		boolean, default false
`links`	`object[]`	yes	The links (up to 500). Name records by id or by a unique field value. (max 500 items)
`idempotency_key`	`string`		Optional retry key ([A-Za-z0-9._:-], max 255). Repeating a call with the same key and arguments returns the original result without writing again.
`workspace`	`string`		Workspace id (preferred), slug or exact name. Omit for the default workspace. Resolve names once with workspace_select.

Example

MCP

{
  "tool": "relationships_link_batch",
  "arguments": {
    "source_object": "contact",
    "relationship": "works_at",
    "links": [
      {
        "client_ref": "line 2",
        "source_key": {
          "email": "ada@example.test"
        },
        "target_key": {
          "name": "Example Ltd"
        }
      }
    ]
  }
}

MCP via agentdb_execute

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "relationships_link_batch",
    "arguments": {
      "source_object": "contact",
      "relationship": "works_at",
      "links": [
        {
          "client_ref": "line 2",
          "source_key": {
            "email": "ada@example.test"
          },
          "target_key": {
            "name": "Example Ltd"
          }
        }
      ]
    }
  }
}

REST

curl -s -X POST "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/links/batch" \
  -H "Authorization: Bearer $AGENTDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"source_object":"contact","relationship":"works_at","links":[{"client_ref":"line 2","source_key":{"email":"ada@example.test"},"target_key":{"name":"Example Ltd"}}]}'

#`relationships_list`

stable added in 0.2.0-alpha.4 or earlier read-only

List records linked to a record. direction 'outgoing' follows a relationship defined on this record's object; 'incoming' finds records that link to it. Page with after=next_after.

MCP tool: relationships_list
REST: GET /v1/workspaces/{ws}/records/{record}/related scope records:read

Arguments

Argument	Type	Required	Description
`relationship`	`string`	yes	Relationship type name.
`direction`	`"outgoing" \| "incoming"`		string, one of: outgoing, incoming, default "outgoing"
`limit`	`integer`		integer, 1–200, default 50
`after`	`string`		string
`include_archived`	`boolean`		boolean
`record_id`	`string`	yes	Record id (rec_...)
`workspace`	`string`		Workspace id (preferred), slug or exact name. Omit for the default workspace. Resolve names once with workspace_select.

Example

MCP

{
  "tool": "relationships_list",
  "arguments": {
    "record_id": "rec_example",
    "relationship": "works_at",
    "direction": "outgoing"
  }
}

MCP via agentdb_execute

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "relationships_list",
    "arguments": {
      "record_id": "rec_example",
      "relationship": "works_at",
      "direction": "outgoing"
    }
  }
}

REST

curl -s "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/records/rec_example/related" \
  -H "Authorization: Bearer $AGENTDB_TOKEN"

#`relationships_unlink`

stable added in 0.2.0-alpha.4 or earlier changes data destructive

Remove one link between records. The records themselves are not changed.

MCP tool: relationships_unlink
REST: DELETE /v1/workspaces/{ws}/links/{link} scope records:write

Arguments

Argument	Type	Required	Description
`link_id`	`string`	yes	Link id (lnk_...) from relationships_link or relationships_list
`idempotency_key`	`string`		Optional retry key ([A-Za-z0-9._:-], max 255). Repeating a call with the same key and arguments returns the original result without writing again.
`workspace`	`string`		Workspace id (preferred), slug or exact name. Omit for the default workspace. Resolve names once with workspace_select.

Example

link_id comes from relationships_link or relationships_list.

MCP

{
  "tool": "relationships_unlink",
  "arguments": {
    "link_id": "lnk_example"
  }
}

MCP via agentdb_execute

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "relationships_unlink",
    "arguments": {
      "link_id": "lnk_example"
    }
  }
}

REST

curl -s -X DELETE "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/links/lnk_example" \
  -H "Authorization: Bearer $AGENTDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Relationships

#relationships_link

Arguments

Example

#relationships_link_batch

Arguments

Example

#relationships_list

Arguments

Example

#relationships_unlink

Arguments

Example

#`relationships_link`

#`relationships_link_batch`

#`relationships_list`

#`relationships_unlink`