Arke
ReferenceAPI Reference

Entities

Entity CRUD operations for all types (files, folders, etc.)

Create a new entity

POST
/entities

Authorization

AuthorizationBearer <token>

Supabase JWT token. Use Authorization: Bearer <jwt>. Only for JWT tokens from Supabase auth - do NOT use Bearer with API keys.

In: header

Query Parameters

validate_relationships?string

Validate that relationship targets exist. Defaults to true for single entity operations, false for batch. When true, requests with >500 unique relationship targets are rejected.

Value in"true" | "false"

Request Body

application/json

note?string

Optional note describing this change

id?string

Custom entity ID (generated if not provided)

Match^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$
type*string

Entity type identifier

Length1 <= length <= 100
properties?

Entity properties (type-specific). Text properties may contain inline entity references using the arke: URI scheme (e.g., Label) for domain-agnostic linking.

relationships?array<>

Entity relationships

collection?string

Parent collection ID (creates collection relationship)

Match^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$
sync_index?boolean

Wait for collection index update before returning. Use when checking for duplicates immediately after creation. Adds ~1-5ms latency per collection.

Defaultfalse

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://api.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

POST
/entities/batch

Authorization

AuthorizationBearer <token>

Supabase JWT token. Use Authorization: Bearer <jwt>. Only for JWT tokens from Supabase auth - do NOT use Bearer with API keys.

In: header

Query Parameters

validate_relationships?string

Validate that relationship targets exist. Defaults to true for single entity operations, false for batch. When true, requests with >500 unique relationship targets are rejected.

Value in"true" | "false"

Request Body

application/json

entities*array<>

Array of entities to create (1-100)

Items1 <= items <= 100
default_collection?string

Default collection for entities that do not specify one

Match^(?: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://api.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"
}

Batch get entities by ID

POST
/entities/batch-get

Request Body

application/json

ids*array<>

Entity IDs to fetch (max 100)

Items1 <= items <= 100

Response Body

application/json

application/json

curl -X POST "https://api.arke.institute/entities/batch-get" \  -H "Content-Type: application/json" \  -d '{    "ids": [      "01JENTITY123456789012345",      "01JENTITY234567890123456"    ]  }'
{
  "entities": [
    {
      "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"
    }
  ],
  "not_found": [
    "01KDETYWYWM0MJVKM8DK3AEXPY"
  ]
}
{
  "error": "Validation failed",
  "details": {
    "issues": [
      {
        "path": [
          "properties",
          "label"
        ],
        "message": "Required"
      }
    ]
  }
}

Get entity by ID

GET
/entities/{id}

Path Parameters

id*string

Entity ID (ULID)

Match^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$

Query Parameters

expand?string

Comma-separated list of fields to expand. Supports: relationships[:preview|full]

expand_limit?integer

Maximum number of relationships to expand (1-500, default 100). When exceeded, relationships beyond the limit are returned without peer data.

Range1 <= value <= 500

Response Body

application/json

application/json

application/json

curl -X GET "https://api.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

DELETE
/entities/{id}

Authorization

AuthorizationBearer <token>

Supabase JWT token. Use Authorization: Bearer <jwt>. Only for JWT tokens from Supabase auth - do NOT use Bearer with API keys.

In: header

Path Parameters

id*string

Entity ID (ULID)

Match^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$

Request Body

application/json

expect_tip*string

Current tip CID for CAS validation. Request fails with 409 if this does not match.

Length1 <= length
note?string

Optional note describing this change

reason?string

Reason for deleting the entity

Lengthlength <= 500
sync_index?boolean

Wait for collection index removal before returning. Use when checking index immediately after deletion.

Defaultfalse

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X DELETE "https://api.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

PUT
/entities/{id}

Authorization

AuthorizationBearer <token>

Supabase JWT token. Use Authorization: Bearer <jwt>. Only for JWT tokens from Supabase auth - do NOT use Bearer with API keys.

In: header

Path Parameters

id*string

Entity ID (ULID)

Match^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$

Query Parameters

validate_relationships?string

Validate that relationship targets exist. Defaults to true for single entity operations, false for batch. When true, requests with >500 unique relationship targets are rejected.

Value in"true" | "false"

Request Body

application/json

expect_tip*string

Current tip CID for CAS validation. Request fails with 409 if this does not match.

Length1 <= length
note?string

Optional note describing this change

properties?

Properties to add or update (deep merged)

properties_remove?array<>|

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_add?array<>

Relationships to add or update (upsert semantics)

relationships_remove?array<>

Relationships to remove

sync_index?boolean

Wait for collection index update before returning. Use when checking index immediately after update.

Defaultfalse

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PUT "https://api.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

GET
/entities/{id}/preview

Path Parameters

id*string

Entity ID (ULID)

Match^(?: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://api.arke.institute/entities/01KDETYWYWM0MJVKM8DK3AEXPY/preview"
{
  "id": "01KDETYWYWM0MJVKM8DK3AEXPY",
  "type": "file",
  "label": "Research Paper.pdf",
  "collection_id": "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

GET
/entities/{id}/tip

Path Parameters

id*string

Entity ID (ULID)

Match^(?: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://api.arke.institute/entities/01KDETYWYWM0MJVKM8DK3AEXPY/tip"
{
  "id": "01KDETYWYWM0MJVKM8DK3AEXPY",
  "cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy"
}
{
  "error": "Entity not found"
}
DELETE
/entities/{id}/cascade

Authorization

AuthorizationBearer <token>

Supabase JWT token. Use Authorization: Bearer <jwt>. Only for JWT tokens from Supabase auth - do NOT use Bearer with API keys.

In: header

Path Parameters

id*string

Entity ID (ULID)

Match^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$

Request Body

application/json

expect_tip*string

Current tip CID for CAS validation. Request fails with 409 if this does not match.

Length1 <= length
note?string

Optional note describing this change

collection_id*string

Collection to scope the cascade delete. Only entities in this collection will be deleted. Permission check is performed on this collection.

Match^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$
cascade_predicates*array<>

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.

Items1 <= items
edited_by_filter?string

Only delete entities where edited_by.user_id matches this PI. Useful for cleaning up entities created by a specific agent.

Match^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$
max_depth?integer

Maximum relationship depth to traverse (default: 10, max: 20)

Default10
Range1 <= value <= 20
reason?string

Reason for deleting the entities (applied to all deleted entities)

Lengthlength <= 500

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X DELETE "https://api.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

POST
/entities/{id}/restore

Authorization

AuthorizationBearer <token>

Supabase JWT token. Use Authorization: Bearer <jwt>. Only for JWT tokens from Supabase auth - do NOT use Bearer with API keys.

In: header

Path Parameters

id*string

Entity ID (ULID)

Match^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$

Request Body

application/json

expect_tip*string

Current tip CID for CAS validation. Request fails with 409 if this does not match.

Length1 <= length
note?string

Optional note describing this change

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://api.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

GET
/entities/{id}/collection

Path Parameters

id*string

Entity ID (ULID)

Match^(?: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://api.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

GET
/entities/{id}/tree

Path Parameters

id*string

Entity ID (ULID)

Match^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$

Query Parameters

depth?integer

Maximum tree depth (1-4)

Default2
Range1 <= value <= 4
collection?string

Constrain results to entities in this collection

Match^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$
predicates?string

Comma-separated predicates to follow (e.g., "contains,references")

limit?integer

Maximum number of nodes to return

Default100
Range1 <= value <= 1000

Response Body

application/json

application/json

application/json

curl -X GET "https://api.arke.institute/entities/01KDETYWYWM0MJVKM8DK3AEXPY/tree"
{
  "root": {
    "id": "01KDETYWYWM0MJVKM8DK3AEXPY",
    "label": "string",
    "type": "string",
    "depth": 0,
    "children": [
      {
        "id": "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

GET
/entities/{id}/diff

Path Parameters

id*string

Entity ID (ULID)

Match^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$

Query Parameters

from?string

CID of the "from" version. Defaults to prev of "to" version.

Length1 <= length
to?string

CID of the "to" version. Defaults to current tip.

Length1 <= length
format?string

Output format: "semantic" (default) or "patch" (RFC 6902)

Default"semantic"
Value in"semantic" | "patch"

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://api.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

GET
/entities/{id}/permissions

Authorization

AuthorizationBearer <token>

Supabase JWT token. Use Authorization: Bearer <jwt>. Only for JWT tokens from Supabase auth - do NOT use Bearer with API keys.

In: header

Path Parameters

id*string

Entity ID (ULID)

Match^(?: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://api.arke.institute/entities/01KDETYWYWM0MJVKM8DK3AEXPY/permissions"
{
  "entity_id": "01KDETYWYWM0MJVKM8DK3AEXPY",
  "entity_type": "file",
  "allowed_actions": [
    "entity:view",
    "entity:update"
  ],
  "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"
}

Download content for any entity

GET
/entities/{id}/content

Path Parameters

id*string

Entity ID (ULID)

Match^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$

Query Parameters

key?string

Content key to download (resolved to CID from entity metadata)

cid?string

Direct CID to download (alternative to key)

Response Body

application/octet-stream

application/json

application/json

curl -X GET "https://api.arke.institute/entities/01KDETYWYWM0MJVKM8DK3AEXPY/content"
"string"
{
  "error": "Forbidden: You do not have permission to perform this action"
}
{
  "error": "Entity not found"
}

Upload content for any entity

POST
/entities/{id}/content

Authorization

AuthorizationBearer <token>

Supabase JWT token. Use Authorization: Bearer <jwt>. Only for JWT tokens from Supabase auth - do NOT use Bearer with API keys.

In: header

Path Parameters

id*string

Entity ID (ULID)

Match^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$

Query Parameters

key*string

Version key for this content (e.g., "v1", "original", "thumbnail")

Length1 <= length <= 255
filename?string

Filename for Content-Disposition header on download

Lengthlength <= 255

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://api.arke.institute/entities/01KDETYWYWM0MJVKM8DK3AEXPY/content?key=v1"
{
  "id": "01KABC123...",
  "cid": "bafyrei...",
  "content": {
    "key": "v1",
    "cid": "bafyreih5iy6dqwbcslkqpx6bxwj7qy3z5x...",
    "size": 12345,
    "content_type": "application/pdf",
    "filename": "document.pdf",
    "uploaded_at": "2025-01-15T10:00:00Z"
  },
  "prev_cid": "bafyrei..."
}
{
  "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"
  }
}
{
  "error": "Validation failed",
  "details": {
    "issues": [
      {
        "path": [
          "string"
        ],
        "message": "string"
      }
    ]
  }
}

Rename content key

PATCH
/entities/{id}/content

Authorization

AuthorizationBearer <token>

Supabase JWT token. Use Authorization: Bearer <jwt>. Only for JWT tokens from Supabase auth - do NOT use Bearer with API keys.

In: header

Path Parameters

id*string

Entity ID (ULID)

Match^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$

Request Body

application/json

old_key*string

Current content key to rename

Length1 <= length <= 255
new_key*string

New key name

Length1 <= length <= 255
expect_tip*string

Expected current tip CID for CAS protection

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://api.arke.institute/entities/01KDETYWYWM0MJVKM8DK3AEXPY/content" \  -H "Content-Type: application/json" \  -d '{    "old_key": "thumbnail",    "new_key": "thumbnail_v1",    "expect_tip": "bafyrei..."  }'
{
  "id": "01KABC123...",
  "cid": "bafyrei...",
  "old_key": "thumbnail",
  "new_key": "thumbnail_v1",
  "content_cid": "bafyreih5iy6dqwbcslkqpx6bxwj7qy3z5x...",
  "prev_cid": "bafyrei..."
}
{
  "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"
  }
}

Remove content by key or CID

DELETE
/entities/{id}/content

Authorization

AuthorizationBearer <token>

Supabase JWT token. Use Authorization: Bearer <jwt>. Only for JWT tokens from Supabase auth - do NOT use Bearer with API keys.

In: header

Path Parameters

id*string

Entity ID (ULID)

Match^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$

Query Parameters

key?string

Content key to remove

Length1 <= length <= 255
cid?string

Content CID to remove (alternative to key)

expect_tip*string

Expected current tip CID for CAS protection

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X DELETE "https://api.arke.institute/entities/01KDETYWYWM0MJVKM8DK3AEXPY/content?expect_tip=bafyrei..."
{
  "id": "01KABC123...",
  "cid": "bafyrei...",
  "removed_key": "thumbnail",
  "prev_cid": "bafyrei..."
}
{
  "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 presigned URL for direct upload

POST
/entities/{id}/content/upload-url

Authorization

AuthorizationBearer <token>

Supabase JWT token. Use Authorization: Bearer <jwt>. Only for JWT tokens from Supabase auth - do NOT use Bearer with API keys.

In: header

Path Parameters

id*string

Entity ID (ULID)

Match^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$

Request Body

application/json

cid*string

Content-addressed identifier (computed by client before upload)

Length1 <= length
content_type*string

MIME type of the content to upload

Length1 <= length
size*integer

Expected file size in bytes (max 500 MB)

Range0 <= value <= 524288000

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://api.arke.institute/entities/01KDETYWYWM0MJVKM8DK3AEXPY/content/upload-url" \  -H "Content-Type: application/json" \  -d '{    "cid": "bafyreih5iy6dqwbcslkqpx6bxwj7qy3z5x...",    "content_type": "application/pdf",    "size": 10485760  }'
{
  "upload_url": "https://xxx.r2.cloudflarestorage.com/...",
  "r2_key": "01KABC123.../v1",
  "expires_at": "2025-01-15T10:15:00Z"
}
{
  "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"
}

Complete presigned URL upload

POST
/entities/{id}/content/complete

Authorization

AuthorizationBearer <token>

Supabase JWT token. Use Authorization: Bearer <jwt>. Only for JWT tokens from Supabase auth - do NOT use Bearer with API keys.

In: header

Path Parameters

id*string

Entity ID (ULID)

Match^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$

Request Body

application/json

key*string

Version key used in upload-url request

Length1 <= length <= 255
cid*string

Content-addressed identifier computed by client

size*integer

Actual file size in bytes

Range0 <= value
content_type*string

MIME type of the uploaded content

filename?string

Original filename for Content-Disposition

Lengthlength <= 255
expect_tip*string

Expected current tip CID for CAS protection

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://api.arke.institute/entities/01KDETYWYWM0MJVKM8DK3AEXPY/content/complete" \  -H "Content-Type: application/json" \  -d '{    "key": "v1",    "cid": "bafyreih5iy6dqwbcslkqpx6bxwj7qy3z5x...",    "size": 10485760,    "content_type": "application/pdf",    "expect_tip": "bafyrei..."  }'
{
  "id": "01KABC123...",
  "cid": "bafyrei...",
  "content": {
    "key": "v1",
    "cid": "bafyreih5iy6dqwbcslkqpx6bxwj7qy3z5x...",
    "size": 12345,
    "content_type": "application/pdf",
    "filename": "document.pdf",
    "uploaded_at": "2025-01-15T10:00:00Z"
  },
  "prev_cid": "bafyrei..."
}
{
  "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"
  }
}

Queue additive updates (fire-and-forget)

POST
/updates/additive

Authorization

AuthorizationBearer <token>

Supabase JWT token. Use Authorization: Bearer <jwt>. Only for JWT tokens from Supabase auth - do NOT use Bearer with API keys.

In: header

Request Body

application/json

updates*array<>

Updates to queue (1-1000 items). Updates to the same entity from the same actor are merged.

Items1 <= items <= 1000

Response Body

application/json

application/json

application/json

curl -X POST "https://api.arke.institute/updates/additive" \  -H "Content-Type: application/json" \  -d '{    "updates": [      {        "entity_id": "01KDETYWYWM0MJVKM8DK3AEXPY"      }    ]  }'
{
  "queued": [
    {
      "entity_id": "01KDETYWYWM0MJVKM8DK3AEXPY",
      "queue_id": 1
    }
  ],
  "failed": [
    {
      "entity_id": "01KDETYWYWM0MJVKM8DK3AEXPY",
      "error": "Entity not found"
    }
  ],
  "summary": {
    "total": 10,
    "queued": 9,
    "failed": 1
  }
}
{
  "error": "Validation failed",
  "details": {
    "issues": [
      {
        "path": [
          "properties",
          "label"
        ],
        "message": "Required"
      }
    ]
  }
}
{
  "error": "Unauthorized: Missing or invalid authentication token"
}

Documentation

Previous Page

Events

Next Page