Relations API

The Relations API allows you to create and manage relationships between entities, building a knowledge graph.

Relation Object

Field	Type	Description
`id`	string	Unique relation identifier
`sourceId`	string	Source entity ID
`targetId`	string	Target entity ID
`type`	string	Relationship type
`metadata`	object	Custom metadata
`createdAt`	string	ISO 8601 timestamp

Relationship Types

Common relationship types (you can define your own):

Type	Description	Example
`WORKS_FOR`	Employment relationship	John WORKS_FOR Acme Corp
`KNOWS`	Personal connection	John KNOWS Jane
`LOCATED_IN`	Geographic location	Acme Corp LOCATED_IN San Francisco
`PART_OF`	Membership/hierarchy	Engineering PART_OF Acme Corp
`CREATED`	Authorship/creation	John CREATED Project X
`RELATED_TO`	General relationship	Topic A RELATED_TO Topic B

Create Relation

Create a new relationship between two entities.

POST /v1/relations

Request Body

Field	Type	Required	Description
`sourceId`	string	Yes	Source entity ID
`targetId`	string	Yes	Target entity ID
`type`	string	Yes	Relationship type
`metadata`	object	No	Custom metadata

Example Request

curl -X POST https://api.memokit.dev/v1/relations \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceId": "ent_john123",
    "targetId": "ent_acme456",
    "type": "WORKS_FOR",
    "metadata": {
      "startDate": "2023-01-15",
      "role": "Senior Engineer"
    }
  }'

Response

{
  "id": "rel_abc123",
  "sourceId": "ent_john123",
  "targetId": "ent_acme456",
  "type": "WORKS_FOR",
  "metadata": {
    "startDate": "2023-01-15",
    "role": "Senior Engineer"
  },
  "createdAt": "2024-01-15T10:30:00Z"
}

List Relations

Retrieve a paginated list of relations.

GET /v1/relations

Query Parameters

Parameter	Type	Required	Description
`sourceId`	string	No	Filter by source entity
`targetId`	string	No	Filter by target entity
`type`	string	No	Filter by relationship type
`page`	number	No	Page number (default: 1)
`limit`	number	No	Items per page (default: 20, max: 100)

Example Request

curl -X GET "https://api.memokit.dev/v1/relations?sourceId=ent_john123" \
  -H "Authorization: Bearer mk_your_api_key"

Response

{
  "items": [
    {
      "id": "rel_abc123",
      "sourceId": "ent_john123",
      "targetId": "ent_acme456",
      "type": "WORKS_FOR",
      "source": {
        "id": "ent_john123",
        "name": "John Smith",
        "type": "PERSON"
      },
      "target": {
        "id": "ent_acme456",
        "name": "Acme Corp",
        "type": "ORGANIZATION"
      },
      "createdAt": "2024-01-15T10:30:00Z"
    },
    {
      "id": "rel_def456",
      "sourceId": "ent_john123",
      "targetId": "ent_jane789",
      "type": "KNOWS",
      "source": {
        "id": "ent_john123",
        "name": "John Smith",
        "type": "PERSON"
      },
      "target": {
        "id": "ent_jane789",
        "name": "Jane Doe",
        "type": "PERSON"
      },
      "createdAt": "2024-01-14T15:20:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 2,
    "totalPages": 1
  }
}

Get Relation

Retrieve a specific relation by ID.

GET /v1/relations/:id

Path Parameters

Parameter	Type	Description
`id`	string	Relation ID

Example Request

curl -X GET https://api.memokit.dev/v1/relations/rel_abc123 \
  -H "Authorization: Bearer mk_your_api_key"

Response

{
  "id": "rel_abc123",
  "sourceId": "ent_john123",
  "targetId": "ent_acme456",
  "type": "WORKS_FOR",
  "source": {
    "id": "ent_john123",
    "name": "John Smith",
    "type": "PERSON"
  },
  "target": {
    "id": "ent_acme456",
    "name": "Acme Corp",
    "type": "ORGANIZATION"
  },
  "metadata": {
    "startDate": "2023-01-15",
    "role": "Senior Engineer"
  },
  "createdAt": "2024-01-15T10:30:00Z"
}

Delete Relation

Delete a relation permanently.

DELETE /v1/relations/:id

Path Parameters

Parameter	Type	Description
`id`	string	Relation ID

Example Request

curl -X DELETE https://api.memokit.dev/v1/relations/rel_abc123 \
  -H "Authorization: Bearer mk_your_api_key"

Response

{
  "success": true,
  "id": "rel_abc123"
}

Error Codes

Code	Description
`RELATION_NOT_FOUND`	The specified relation does not exist
`SOURCE_ENTITY_NOT_FOUND`	The source entity does not exist
`TARGET_ENTITY_NOT_FOUND`	The target entity does not exist
`INVALID_RELATION_TYPE`	The relation type is not valid

Relations API

On this page