Read Entities

Get by ID

GET /entities/{id}
Authorization: Bearer <token>

Returns the full entity manifest including properties, relationships, version info, and audit trail.

Query Parameters

Parameter	Description
`expand`	Expand relationship data. Options: `relationships:preview` or `relationships:full`
`expand_limit`	Max relationships to expand (1-500, default 100)

Response

{
  "id": "01KFNR849AZNBWE9DYJRZR7PSA",
  "cid": "bafyreig...",
  "type": "file",
  "properties": {
    "label": "Father Mapple's Sermon",
    "description": "A sermon on Jonah delivered at the Whaleman's Chapel"
  },
  "relationships": [
    {
      "predicate": "collection",
      "peer": "01KFNR0H0Q791Y1SMZWEQ09FGV",
      "peer_type": "collection",
      "peer_label": "Moby Dick Archive"
    }
  ],
  "ver": 1,
  "created_at": "2026-01-28T12:00:00.000Z",
  "ts": 1735387200000,
  "edited_by": {
    "user_id": "01JCAPTAINAHAB000000000000",
    "method": "manual"
  }
}

Relationship Expansion

Use the expand parameter to hydrate relationship peer data:

No expansion (default): Returns relationships with stored peer_label/peer_type (may be stale if the peer was renamed).

?expand=relationships:preview: Adds peer_preview with fresh lightweight data:

{
  "predicate": "contains",
  "peer": "01KDOC...",
  "peer_label": "Old Label",
  "peer_preview": {
    "id": "01KDOC...",
    "type": "document",
    "label": "Updated Label",
    "description_preview": "This is a document with...",
    "created_at": "2025-01-15T10:00:00Z",
    "updated_at": "2025-01-20T14:30:00Z"
  }
}

?expand=relationships:full: Adds peer_entity with the complete entity manifest.

Performance: Preview expansion is recommended for most use cases. Full expansion can result in multi-MB payloads with many large entities.

When truncation occurs due to expand_limit, the response includes _expansion_metadata:

{
  "_expansion_metadata": {
    "relationships": {
      "total": 150,
      "expanded": 100,
      "truncated": true
    }
  }
}

Get Preview

GET /entities/{id}/preview
Authorization: Bearer <token>

Returns lightweight preview data for an entity. Useful for:

Link previews and hover cards
Search result enhancement
AI context management (smaller payloads)

Response

{
  "id": "01KFNR849AZNBWE9DYJRZR7PSA",
  "type": "file",
  "label": "Father Mapple's Sermon",
  "collection_pi": "01KFNR0H0Q791Y1SMZWEQ09FGV",
  "description_preview": "A sermon on Jonah delivered at the Whaleman's Chapel...",
  "created_at": "2026-01-28T12:00:00.000Z",
  "updated_at": "2026-01-28T12:00:00.000Z"
}

Performance: Single KV fetch, ~40-60ms response time, typically less than 1KB payload.

Get Tip (CID Only)

GET /entities/{id}/tip

Returns only the current manifest CID for an entity. This is a lightweight endpoint for CAS operations - single Durable Object lookup, no manifest fetch, no permission check.

No authentication required.

Response

{
  "id": "01KFNR849AZNBWE9DYJRZR7PSA",
  "cid": "bafyreig..."
}

Get Collection

GET /entities/{id}/collection
Authorization: Bearer <token>

Returns the collection ID that this entity belongs to.

Response

{
  "collection_id": "01KFNR0H0Q791Y1SMZWEQ09FGV"
}

Returns null if the entity is not in any collection. If the entity IS a collection, returns its own ID.

Get Tree

GET /entities/{id}/tree
Authorization: Bearer <token>

Returns a hierarchical tree of entities reachable from the source entity. Use this to browse collections and folders without making multiple API calls.

Query Parameters

Parameter	Description
`depth`	Max tree depth (1-4, default 2)
`collection`	Constrain to entities in this collection
`predicates`	Comma-separated predicates to follow (e.g., `contains`)
`limit`	Max nodes to return (default 100, max 1000)

Response

{
  "root": {
    "pi": "01KFNR0H0Q791Y1SMZWEQ09FGV",
    "label": "Moby Dick Archive",
    "type": "collection",
    "depth": 0,
    "children": [
      {
        "pi": "01KFNR81RMVAX2BBMMBW51V97D",
        "label": "Chapters",
        "type": "folder",
        "depth": 1,
        "children": []
      }
    ]
  },
  "total_nodes": 2,
  "truncated": false
}

Get Diff

GET /entities/{id}/diff
Authorization: Bearer <token>

Computes the difference between two versions of an entity.

Query Parameters

Parameter	Description
`from`	CID of the "from" version (defaults to prev of "to" version)
`to`	CID of the "to" version (defaults to current tip)
`format`	Output format: `semantic` (default) or `patch` (RFC 6902)

Modes

No params: Compare current tip with its previous version
to only: Compare that version with its prev
from only: Compare from that version to current tip
Both: Compare any two versions

For version 1 entities (no previous version), from is null and all content appears as added.

Semantic Response

{
  "entity_id": "01KFNR849AZNBWE9DYJRZR7PSA",
  "from": {
    "cid": "bafyrei...",
    "ver": 1,
    "ts": "2026-01-28T12:00:00.000Z"
  },
  "to": {
    "cid": "bafyrei...",
    "ver": 2,
    "ts": "2026-01-28T14:00:00.000Z"
  },
  "format": "semantic",
  "changes": {
    "properties": {
      "added": {},
      "removed": {},
      "changed": {
        "description": {
          "from": "Old description",
          "to": "New description"
        }
      }
    },
    "relationships": {
      "added": [],
      "removed": [],
      "changed": []
    }
  }
}

Patch Response (RFC 6902)

{
  "entity_id": "01KFNR849AZNBWE9DYJRZR7PSA",
  "from": { "cid": "bafyrei...", "ver": 1, "ts": "..." },
  "to": { "cid": "bafyrei...", "ver": 2, "ts": "..." },
  "format": "patch",
  "patch": [
    { "op": "replace", "path": "/properties/description", "value": "New description" }
  ]
}

Get Permissions

GET /entities/{id}/permissions
Authorization: Bearer <token>

Returns the list of actions you can perform on this entity.

Response

{
  "entity_id": "01KFNR849AZNBWE9DYJRZR7PSA",
  "entity_type": "file",
  "allowed_actions": [
    "entity:view",
    "entity:update",
    "file:download"
  ],
  "resolution": {
    "method": "collection",
    "collection_id": "01KFNR0H0Q791Y1SMZWEQ09FGV",
    "role": "editor"
  }
}

Resolution Methods

Method	Description
`collection`	Permissions from your role in the parent collection
`self`	You are checking your own user entity (self-ownership)
`open_season`	Entity is not in any collection (publicly accessible)

Actions are filtered to only those relevant to the entity type (e.g., for files: entity:* and file:* actions).

On this page