BuildEntities
Create Entities
How to create new entities on the Arke network.
Basic Creation
POST /entities
Content-Type: application/json
Authorization: Bearer <token>
{
"type": "file",
"properties": {
"name": "My Document",
"description": "A research paper"
},
"collection_id": "01JCOLLECTION..."
}Required Fields
| Field | Description |
|---|---|
type | Entity type (file, folder, collection, etc.) |
collection_id | Collection to place the entity in |
Optional Fields
| Field | Description |
|---|---|
properties | Key-value metadata |
relationships | Initial relationships to other entities |
note | Version note for this creation |
Response
{
"id": "01JXXXXXXXXXXXXXXXXXXXXXXXXX",
"cid": "bafyreig...",
"type": "file",
"ver": 1,
"properties": {
"name": "My Document",
"description": "A research paper"
},
"relationships": [],
"created_at": "2026-01-28T12:00:00.000Z"
}Creating with Relationships
You can create an entity with initial relationships:
{
"type": "file",
"properties": { "name": "Child Document" },
"collection_id": "01JCOLLECTION...",
"relationships": [
{
"predicate": "parent",
"peer": "01JPARENT..."
}
]
}Batch Creation Pattern
When creating many entities with a shared parent, maximize parallelism:
- Create all children in parallel with upward
parentrelationships in their POST bodies - Do one GET to fetch the parent's current tip
- Do one PUT to the parent with
relationships_addcontaining allcontainsrelationships
For 100 children: 100 parallel POSTs + 1 GET + 1 PUT = 102 requests total.