Create Entities

Basic Creation

POST /entities
Content-Type: application/json
Authorization: Bearer <token>

{
  "type": "file",
  "properties": {
    "label": "Father Mapple's Sermon",
    "description": "A sermon on Jonah delivered at the Whaleman's Chapel"
  },
  "collection": "01KFNR0H0Q791Y1SMZWEQ09FGV"
}

Required Fields

Field	Description
`type`	Entity type (file, folder, collection, etc.)

Recommended Fields

Field	Description
`collection`	Collection to place the entity in (for permissions)

Optional Fields

Field	Description
`properties`	Key-value metadata
`relationships`	Initial relationships to other entities
`note`	Version note for this creation

Response

{
  "id": "01KFNR849AZNBWE9DYJRZR7PSA",
  "cid": "bafyreig...",
  "type": "file",
  "ver": 1,
  "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" }
  ],
  "created_at": "2026-01-28T12:00:00.000Z",
  "ts": 1738065600000,
  "edited_by": { "user_id": "01JUSER...", "method": "manual" }
}

Creating with Relationships

You can create an entity with initial relationships:

{
  "type": "file",
  "properties": { "label": "Chapter 1. Loomings" },
  "collection": "01KFNR0H0Q791Y1SMZWEQ09FGV",
  "relationships": [
    {
      "predicate": "in",
      "peer": "01KFNR81RMVAX2BBMMBW51V97D",
      "peer_type": "folder"
    }
  ]
}

Batch Creation

Use POST /entities/batch to create multiple entities in a single request:

POST /entities/batch
Content-Type: application/json
Authorization: Bearer <token>

{
  "default_collection": "01KFNR0H0Q791Y1SMZWEQ09FGV",
  "entities": [
    {
      "type": "file",
      "properties": { "label": "Chapter 1. Loomings" },
      "relationships": [{ "predicate": "in", "peer": "01KFNR81RMVAX2BBMMBW51V97D", "peer_type": "folder" }]
    },
    {
      "type": "file",
      "properties": { "label": "Chapter 2. The Carpet-Bag" },
      "relationships": [{ "predicate": "in", "peer": "01KFNR81RMVAX2BBMMBW51V97D", "peer_type": "folder" }]
    },
    {
      "type": "file",
      "properties": { "label": "Chapter 3. The Spouter-Inn" },
      "relationships": [{ "predicate": "in", "peer": "01KFNR81RMVAX2BBMMBW51V97D", "peer_type": "folder" }]
    }
  ]
}

Batch Options

Field	Description
`entities`	Array of entities to create (max 100)
`default_collection`	Collection for entities without explicit `collection` field

Each entity in the array follows the same schema as single creates. You can override collection per-entity if needed.

Batch Response

Returns per-entity results with HTTP 201 (all succeed) or 207 (partial success):

{
  "results": [
    { "success": true, "index": 0, "id": "01KCHAP1...", "cid": "bafyrei...", "type": "file", "ver": 1 },
    { "success": true, "index": 1, "id": "01KCHAP2...", "cid": "bafyrei...", "type": "file", "ver": 1 },
    { "success": false, "index": 2, "error": "Validation failed", "code": "VALIDATION_ERROR" }
  ],
  "summary": {
    "total": 3,
    "succeeded": 2,
    "failed": 1
  }
}

Batch + Folder Relationships

When creating children with a shared parent folder, use the batch endpoint for children, then update the parent once:

POST /entities/batch with all children (include upward in relationships)
GET /entities/{folder_id}/tip to get current CID
PUT /entities/{folder_id} with relationships_add containing all downward contains relationships

For 100 children: 1 batch POST + 1 GET + 1 PUT = 3 requests total (vs 102 with individual POSTs).

On this page