Entities
Generic entity CRUD
Create a new entity
Authorization
bearerAuth Supabase JWT token
In: header
Request Body
application/json
Optional note describing this change
Custom entity ID (generated if not provided)
^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$Entity type identifier
1 <= length <= 100Entity properties (type-specific). Text properties may contain inline entity references using the arke: URI scheme (e.g., Label) for domain-agnostic linking.
Entity relationships
Parent collection ID (creates collection relationship)
^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$Response Body
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://arke-v1.arke.institute/entities" \ -H "Content-Type: application/json" \ -d '{ "type": "document" }'{
"id": "01KDETYWYWM0MJVKM8DK3AEXPY",
"cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
"type": "collection",
"properties": {
"label": "The Pequod's Archive",
"description": "A collection of whaling documents"
},
"relationships": [
{
"predicate": "crew",
"peer": "01KDETYWYWM0MJVKM8DK3AEXPY",
"peer_type": "collection"
}
],
"ver": 1,
"created_at": "2025-12-26T12:00:00.000Z",
"ts": 1735214400000,
"edited_by": {
"user_id": "01JCAPTAINAHAB000000000000",
"user_label": "Captain Ahab",
"method": "manual"
},
"prev_cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy"
}{
"error": "Validation failed",
"details": {
"issues": [
{
"path": [
"properties",
"label"
],
"message": "Required"
}
]
}
}{
"error": "Unauthorized: Missing or invalid authentication token"
}{
"error": "Forbidden: You do not have permission to perform this action"
}{
"error": "Conflict: entity was modified",
"details": {
"expected": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
"actual": "bafyreinewabc123456789defghijklmnopqrstuvwxyz"
}
}Batch create entities
Authorization
bearerAuth Supabase JWT token
In: header
Request Body
application/json
Array of entities to create (1-100)
1 <= items <= 100Default collection for entities that do not specify one
^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$Response Body
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://arke-v1.arke.institute/entities/batch" \ -H "Content-Type: application/json" \ -d '{ "entities": [ { "type": "string" } ] }'{
"results": [
{
"success": true,
"index": 0,
"id": "01KDETYWYWM0MJVKM8DK3AEXPY",
"cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
"type": "string",
"ver": 1
}
],
"summary": {
"total": 0,
"succeeded": 0,
"failed": 0
}
}{
"results": [
{
"success": true,
"index": 0,
"id": "01KDETYWYWM0MJVKM8DK3AEXPY",
"cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
"type": "string",
"ver": 1
}
],
"summary": {
"total": 0,
"succeeded": 0,
"failed": 0
}
}{
"error": "Validation failed",
"details": {
"issues": [
{
"path": [
"properties",
"label"
],
"message": "Required"
}
]
}
}{
"error": "Unauthorized: Missing or invalid authentication token"
}{
"error": "Forbidden: You do not have permission to perform this action"
}Get entity by ID
Path Parameters
Entity ID (ULID)
^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$Query Parameters
Comma-separated list of fields to expand. Supports: relationships[:preview|full]
Maximum number of relationships to expand (1-500, default 100). When exceeded, relationships beyond the limit are returned without peer data.
1 <= value <= 500Response Body
application/json
application/json
application/json
curl -X GET "https://arke-v1.arke.institute/entities/01KDETYWYWM0MJVKM8DK3AEXPY"{
"id": "01KDETYWYWM0MJVKM8DK3AEXPY",
"cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
"type": "collection",
"properties": {
"label": "The Pequod's Archive",
"description": "A collection of whaling documents"
},
"relationships": [
{
"predicate": "crew",
"peer": "01KDETYWYWM0MJVKM8DK3AEXPY",
"peer_type": "collection"
}
],
"ver": 1,
"created_at": "2025-12-26T12:00:00.000Z",
"ts": 1735214400000,
"edited_by": {
"user_id": "01JCAPTAINAHAB000000000000",
"user_label": "Captain Ahab",
"method": "manual"
},
"prev_cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy"
}{
"error": "Forbidden: You do not have permission to perform this action"
}{
"error": "Entity not found"
}Delete entity
Authorization
bearerAuth Supabase JWT token
In: header
Path Parameters
Entity ID (ULID)
^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$Request Body
application/json
Current tip CID for CAS validation. Request fails with 409 if this does not match.
1 <= lengthOptional note describing this change
Reason for deleting the entity
length <= 500Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X DELETE "https://arke-v1.arke.institute/entities/01KDETYWYWM0MJVKM8DK3AEXPY" \ -H "Content-Type: application/json" \ -d '{ "expect_tip": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy" }'{
"id": "01KDETYWYWM0MJVKM8DK3AEXPY",
"cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
"deleted_at": "2019-08-24T14:15:22Z",
"ver": 1,
"prev_cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy"
}{
"error": "Validation failed",
"details": {
"issues": [
{
"path": [
"properties",
"label"
],
"message": "Required"
}
]
}
}{
"error": "Unauthorized: Missing or invalid authentication token"
}{
"error": "Forbidden: You do not have permission to perform this action"
}{
"error": "Entity not found"
}{
"error": "Conflict: entity was modified",
"details": {
"expected": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
"actual": "bafyreinewabc123456789defghijklmnopqrstuvwxyz"
}
}Update entity
Authorization
bearerAuth Supabase JWT token
In: header
Path Parameters
Entity ID (ULID)
^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$Request Body
application/json
Current tip CID for CAS validation. Request fails with 409 if this does not match.
1 <= lengthOptional note describing this change
Properties to add or update (deep merged)
Properties to remove. Use string[] for top-level keys (e.g., ["old_field"]), or nested objects for deep removal (e.g., { config: { options: ["debug"] } }). Dot notation like "config.options.debug" is NOT supported.
Relationships to add or update (upsert semantics)
Relationships to remove
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X PUT "https://arke-v1.arke.institute/entities/01KDETYWYWM0MJVKM8DK3AEXPY" \ -H "Content-Type: application/json" \ -d '{ "expect_tip": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy" }'{
"id": "01KDETYWYWM0MJVKM8DK3AEXPY",
"cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
"type": "collection",
"properties": {
"label": "The Pequod's Archive",
"description": "A collection of whaling documents"
},
"relationships": [
{
"predicate": "crew",
"peer": "01KDETYWYWM0MJVKM8DK3AEXPY",
"peer_type": "collection"
}
],
"ver": 1,
"created_at": "2025-12-26T12:00:00.000Z",
"ts": 1735214400000,
"edited_by": {
"user_id": "01JCAPTAINAHAB000000000000",
"user_label": "Captain Ahab",
"method": "manual"
},
"prev_cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy"
}{
"error": "Validation failed",
"details": {
"issues": [
{
"path": [
"properties",
"label"
],
"message": "Required"
}
]
}
}{
"error": "Unauthorized: Missing or invalid authentication token"
}{
"error": "Forbidden: You do not have permission to perform this action"
}{
"error": "Entity not found"
}{
"error": "Conflict: entity was modified",
"details": {
"expected": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
"actual": "bafyreinewabc123456789defghijklmnopqrstuvwxyz"
}
}Get entity preview
Path Parameters
Entity ID (ULID)
^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$Response Body
application/json
application/json
application/json
curl -X GET "https://arke-v1.arke.institute/entities/01KDETYWYWM0MJVKM8DK3AEXPY/preview"{
"id": "01KDETYWYWM0MJVKM8DK3AEXPY",
"type": "file",
"label": "Research Paper.pdf",
"collection_pi": "01JCOLLECTION123456789AB",
"description_preview": "A comprehensive study on distributed systems architecture...",
"created_at": "2026-01-12T00:00:00.000Z",
"updated_at": "2026-01-12T10:30:00.000Z"
}{
"error": "Forbidden: You do not have permission to perform this action"
}{
"error": "Entity not found"
}Get entity tip CID
Path Parameters
Entity ID (ULID)
^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$Response Body
application/json
application/json
curl -X GET "https://arke-v1.arke.institute/entities/01KDETYWYWM0MJVKM8DK3AEXPY/tip"{
"id": "01KDETYWYWM0MJVKM8DK3AEXPY",
"cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy"
}{
"error": "Entity not found"
}Cascade delete entity and related entities
Authorization
bearerAuth Supabase JWT token
In: header
Path Parameters
Entity ID (ULID)
^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$Request Body
application/json
Current tip CID for CAS validation. Request fails with 409 if this does not match.
1 <= lengthOptional note describing this change
Collection to scope the cascade delete. Only entities in this collection will be deleted. Permission check is performed on this collection.
^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$Predicate patterns to follow during cascade traversal. Supports wildcards:
"child"- exact match only"has_*"- matches has_document, has_image, etc."*_copy"- matches file_copy, document_copy, etc."*"- matches ALL predicates
Important: The collection predicate NEVER cascades, even if "*" is specified. This protects the collection structure from accidental deletion.
1 <= itemsOnly delete entities where edited_by.user_id matches this PI. Useful for cleaning up entities created by a specific agent.
^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$Maximum relationship depth to traverse (default: 10, max: 20)
101 <= value <= 20Reason for deleting the entities (applied to all deleted entities)
length <= 500Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X DELETE "https://arke-v1.arke.institute/entities/01KDETYWYWM0MJVKM8DK3AEXPY/cascade" \ -H "Content-Type: application/json" \ -d '{ "expect_tip": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy", "collection_id": "01KDETYWYWM0MJVKM8DK3AEXPY", "cascade_predicates": [ "child", "has_*" ] }'{
"root": {
"id": "01KDETYWYWM0MJVKM8DK3AEXPY",
"cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
"deleted_at": "2019-08-24T14:15:22Z",
"ver": 1,
"prev_cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy"
},
"deleted": [
{
"id": "01KDETYWYWM0MJVKM8DK3AEXPY",
"cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
"type": "file",
"depth": 1
}
],
"skipped": [
{
"id": "01KDETYWYWM0MJVKM8DK3AEXPY",
"type": "file",
"reason": "not_in_collection"
}
],
"summary": {
"total_traversed": 0,
"total_deleted": 0,
"total_skipped": 0,
"max_depth_reached": 0
}
}{
"error": "Validation failed",
"details": {
"issues": [
{
"path": [
"properties",
"label"
],
"message": "Required"
}
]
}
}{
"error": "Unauthorized: Missing or invalid authentication token"
}{
"error": "Forbidden: You do not have permission to perform this action"
}{
"error": "Entity not found"
}{
"error": "Conflict: entity was modified",
"details": {
"expected": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
"actual": "bafyreinewabc123456789defghijklmnopqrstuvwxyz"
}
}Restore deleted entity
Authorization
bearerAuth Supabase JWT token
In: header
Path Parameters
Entity ID (ULID)
^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$Request Body
application/json
Current tip CID for CAS validation. Request fails with 409 if this does not match.
1 <= lengthOptional note describing this change
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://arke-v1.arke.institute/entities/01KDETYWYWM0MJVKM8DK3AEXPY/restore" \ -H "Content-Type: application/json" \ -d '{ "expect_tip": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy" }'{
"id": "01KDETYWYWM0MJVKM8DK3AEXPY",
"cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
"type": "collection",
"properties": {
"label": "The Pequod's Archive",
"description": "A collection of whaling documents"
},
"relationships": [
{
"predicate": "crew",
"peer": "01KDETYWYWM0MJVKM8DK3AEXPY",
"peer_type": "collection"
}
],
"ver": 1,
"created_at": "2025-12-26T12:00:00.000Z",
"ts": 1735214400000,
"edited_by": {
"user_id": "01JCAPTAINAHAB000000000000",
"user_label": "Captain Ahab",
"method": "manual"
},
"prev_cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
"restored_from_ver": 1
}{
"error": "Validation failed",
"details": {
"issues": [
{
"path": [
"properties",
"label"
],
"message": "Required"
}
]
}
}{
"error": "Unauthorized: Missing or invalid authentication token"
}{
"error": "Forbidden: You do not have permission to perform this action"
}{
"error": "Entity not found"
}{
"error": "Conflict: entity was modified",
"details": {
"expected": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
"actual": "bafyreinewabc123456789defghijklmnopqrstuvwxyz"
}
}Get entity collection
Path Parameters
Entity ID (ULID)
^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$Response Body
application/json
application/json
application/json
curl -X GET "https://arke-v1.arke.institute/entities/01KDETYWYWM0MJVKM8DK3AEXPY/collection"{
"collection_id": "01KDETYWYWM0MJVKM8DK3AEXPY"
}{
"error": "Forbidden: You do not have permission to perform this action"
}{
"error": "Entity not found"
}Get entity tree
Path Parameters
Entity ID (ULID)
^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$Query Parameters
Maximum tree depth (1-4)
21 <= value <= 4Constrain results to entities in this collection
^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$Comma-separated predicates to follow (e.g., "contains,references")
Maximum number of nodes to return
1001 <= value <= 1000Response Body
application/json
application/json
application/json
curl -X GET "https://arke-v1.arke.institute/entities/01KDETYWYWM0MJVKM8DK3AEXPY/tree"{
"root": {
"pi": "01KDETYWYWM0MJVKM8DK3AEXPY",
"label": "string",
"type": "string",
"depth": 0,
"children": [
{
"pi": "01KDETYWYWM0MJVKM8DK3AEXPY",
"label": "string",
"type": "string",
"depth": 0,
"children": []
}
]
},
"total_nodes": 0,
"truncated": true
}{
"error": "Forbidden: You do not have permission to perform this action"
}{
"error": "Entity not found"
}Get diff between entity versions
Path Parameters
Entity ID (ULID)
^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$Query Parameters
CID of the "from" version. Defaults to prev of "to" version.
1 <= lengthCID of the "to" version. Defaults to current tip.
1 <= lengthOutput format: "semantic" (default) or "patch" (RFC 6902)
"semantic""semantic" | "patch"Response Body
application/json
application/json
application/json
application/json
curl -X GET "https://arke-v1.arke.institute/entities/01KDETYWYWM0MJVKM8DK3AEXPY/diff"{
"entity_id": "01KDETYWYWM0MJVKM8DK3AEXPY",
"from": {
"cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
"ver": 1,
"ts": "2025-12-26T12:00:00.000Z"
},
"to": {
"cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
"ver": 1,
"ts": "2025-12-26T12:00:00.000Z"
},
"format": "semantic",
"changes": {
"properties": {
"added": {
"email": "new@example.com"
},
"removed": {
"deprecated_field": "old value"
},
"changed": {
"name": {
"from": "Old Name",
"to": "New Name"
}
}
},
"relationships": {
"added": [
{
"predicate": "crew",
"peer": "01KDETYWYWM0MJVKM8DK3AEXPY",
"peer_type": "collection"
}
],
"removed": [
{
"predicate": "crew",
"peer": "01KDETYWYWM0MJVKM8DK3AEXPY",
"peer_type": "collection"
}
],
"changed": [
{
"predicate": "string",
"peer": "string",
"peer_type": "string",
"peer_label": "string",
"properties": {
"from": null,
"to": null
}
}
]
}
}
}{
"error": "Validation failed",
"details": {
"issues": [
{
"path": [
"properties",
"label"
],
"message": "Required"
}
]
}
}{
"error": "Forbidden: You do not have permission to perform this action"
}{
"error": "Entity not found"
}Get your permissions for an entity
Authorization
bearerAuth Supabase JWT token
In: header
Path Parameters
Entity ID (ULID)
^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$Response Body
application/json
application/json
application/json
application/json
curl -X GET "https://arke-v1.arke.institute/entities/01KDETYWYWM0MJVKM8DK3AEXPY/permissions"{
"entity_id": "01KDETYWYWM0MJVKM8DK3AEXPY",
"entity_type": "file",
"allowed_actions": [
"entity:view",
"entity:update",
"file:download"
],
"resolution": {
"method": "collection",
"collection_id": "01KDETYWYWM0MJVKM8DK3AEXPY",
"role": "editor"
}
}{
"error": "Unauthorized: Missing or invalid authentication token"
}{
"error": "Forbidden: You do not have permission to perform this action"
}{
"error": "Entity not found"
}