API Reference

Create Memory Relation

Explicitly link two memories with a typed, directional edge. Both endpoints must belong to the authenticated principal and share the same environment + project. Self-loops are rejected. Re-creating an existing (from, to, type) triple is a no-op and returns the existing edge.

POST/memory/{memory_id}/relations

Authentication

Accepts a JWT bearer token (Authorization: Bearer eyJ…) or an API key (X-API-Key: ms_live_…). API-key callers should send X-Project-ID unless the key is project-locked. Cross-tenant operators must send X-Tenant-ID.

Path parameters

Field	Type	Required	Description
`memory_id`	`integer`	required	Source memory id (`from` side of the edge).

Request body

Field	Type	Required	Description
`to_memory_id`	`integer`	required	Target memory id. Must differ from path id.
`relationship_type`	`string`	required	One of `similar`, `derived_from`, `continuation`, `contradiction`, `summary_of`, `detail_of`, `caused_by`, `references`, `supports`, `extends`.
`confidence`	`number`	optional	Caller confidence in `[0.0, 1.0]`. Defaults to `1.0`.
`metadata`	`object`	optional	Free-form metadata bag stored alongside the edge.

request.json

{
  "to_memory_id": 184214,
  "relationship_type": "continuation",
  "confidence": 0.9
}

Response

Returns 200 OK with the following body.

Field	Type	Required	Description
`id`	`integer`	optional	Edge id.
`from_memory_id`	`integer`	optional	Source memory id.
`to_memory_id`	`integer`	optional	Target memory id.
`relationship_type`	`string`	optional	Edge type (one of the whitelisted values).
`confidence`	`number`	optional	Caller-supplied confidence.
`metadata`	`object`	optional	Free-form metadata, may be `null`.
`created_at`	`string`	optional	RFC 3339 UTC.

200.json

{
  "id": 4501,
  "from_memory_id": 184213,
  "to_memory_id": 184214,
  "relationship_type": "continuation",
  "confidence": 0.9,
  "metadata": null,
  "created_at": "2026-05-04T12:31:00Z"
}

Errors

Status	Code	Description
400	`validation_error`	Body or query failed schema validation. The error includes the offending `field` name.
401	`unauthenticated`	Missing or invalid bearer token / API key.
403	`forbidden`	Authenticated principal lacks the required scope, role, or project access.
404	`not_found`	Target resource does not exist or is not visible to the calling tenant.
429	`rate_limited`	Per-IP or per-route limit exceeded. Respect the `Retry-After` header.
500	`internal_error`	Unhandled server error. Quote the `request_id` when contacting support.

Examples

cURL

curl -X POST https://api.memorysync.io/memory/EXAMPLE_ID/relations \
  -H "Authorization: Bearer $MEMORYSYNC_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "to_memory_id": 184214,
  "relationship_type": "continuation",
  "confidence": 0.9
}'

javascript

import { MemorySync } from 'memorysync'

const client = new MemorySync({ apiKey: process.env.MEMORYSYNC_KEY })

const result = await client.request({
  method: 'POST',
  path: '/memory/EXAMPLE_ID/relations',
  body: {
    "to_memory_id": 184214,
    "relationship_type": "continuation",
    "confidence": 0.9
  },
})
console.log(result)

python

from memorysync import Client

client = Client(api_key=os.environ["MEMORYSYNC_KEY"])

result = client.request(
    method="POST",
    path="/memory/EXAMPLE_ID/relations",
    json={
      "to_memory_id": 184214,
      "relationship_type": "continuation",
      "confidence": 0.9
    },
)
print(result)

Behavior & notes

HTTP status on creation is 201 Created. Required scope: memories:write. Both endpoints are looked up under the calling principal — 404 means the id does not exist, is not owned by the caller, or lives in a different environment/project. Any unsupported relationship_type produces 422.

← Previous

Update Memory

Summarize Memory