Arke
ReferenceAPI Reference

Collections

Collection and permission management

Create a new collection

POST
/collections

Authorization

bearerAuth
AuthorizationBearer <token>

Supabase JWT token

In: header

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})$
label*string

Collection display name

Length1 <= length <= 200
description?string

Collection description

Lengthlength <= 2000
display_image_url?string

URL for collection display image

Formaturi
roles?

Custom role definitions (defaults to owner/editor/viewer/public)

properties?

Additional properties to store

relationships?array<>

Initial relationships

Response Body

application/json

application/json

application/json

application/json

curl -X POST "https://arke-v1.arke.institute/collections" \  -H "Content-Type: application/json" \  -d '{    "label": "The Pequod\'s Archive"  }'
{
  "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"
}

Get collection by ID

GET
/collections/{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})$

Response Body

application/json

application/json

application/json

curl -X GET "https://arke-v1.arke.institute/collections/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"
}

Update collection properties

PUT
/collections/{id}

Authorization

bearerAuth
AuthorizationBearer <token>

Supabase JWT token

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

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

label?string

Updated collection display name

Length1 <= length <= 200
description?string

Updated collection description

Lengthlength <= 2000
display_image_url?string

Updated display image URL

Formaturi

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PUT "https://arke-v1.arke.institute/collections/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"
  }
}

Add a new role

POST
/collections/{id}/roles

Authorization

bearerAuth
AuthorizationBearer <token>

Supabase JWT token

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

role*string

Name of the new role

Length1 <= length <= 50
actions*array<>

Actions this role can perform

Items1 <= items

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://arke-v1.arke.institute/collections/01KDETYWYWM0MJVKM8DK3AEXPY/roles" \  -H "Content-Type: application/json" \  -d '{    "role": "harpooner",    "actions": [      "entity:view",      "entity:create",      "entity:update"    ]  }'
{
  "id": "01KDETYWYWM0MJVKM8DK3AEXPY",
  "cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
  "prev_cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
  "ver": 1,
  "roles": {
    "captain": [
      "*:view",
      "*:update",
      "*:create",
      "collection:manage"
    ],
    "harpooner": [
      "*:view",
      "*:update",
      "*:create"
    ],
    "crew": [
      "*:view",
      "entity:create"
    ],
    "public": [
      "entity:view",
      "collection:view"
    ]
  }
}
{
  "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"
}

Delete a role

DELETE
/collections/{id}/roles/{role}

Authorization

bearerAuth
AuthorizationBearer <token>

Supabase JWT token

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})$
role*string

Role name

Length1 <= length <= 50

Response Body

application/json

application/json

application/json

application/json

curl -X DELETE "https://arke-v1.arke.institute/collections/01KDETYWYWM0MJVKM8DK3AEXPY/roles/harpooner"
{
  "id": "01KDETYWYWM0MJVKM8DK3AEXPY",
  "cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
  "prev_cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
  "ver": 1,
  "roles": {
    "captain": [
      "*:view",
      "*:update",
      "*:create",
      "collection:manage"
    ],
    "harpooner": [
      "*:view",
      "*:update",
      "*:create"
    ],
    "crew": [
      "*:view",
      "entity:create"
    ],
    "public": [
      "entity:view",
      "collection:view"
    ]
  }
}
{
  "error": "Unauthorized: Missing or invalid authentication token"
}
{
  "error": "Forbidden: You do not have permission to perform this action"
}
{
  "error": "Entity not found"
}

Update role actions

PUT
/collections/{id}/roles/{role}

Authorization

bearerAuth
AuthorizationBearer <token>

Supabase JWT token

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})$
role*string

Role name

Length1 <= length <= 50

Request Body

application/json

actions*array<>

Updated actions for this role

Items1 <= items

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X PUT "https://arke-v1.arke.institute/collections/01KDETYWYWM0MJVKM8DK3AEXPY/roles/harpooner" \  -H "Content-Type: application/json" \  -d '{    "actions": [      "entity:view",      "entity:create",      "entity:update",      "entity:delete"    ]  }'
{
  "id": "01KDETYWYWM0MJVKM8DK3AEXPY",
  "cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
  "prev_cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
  "ver": 1,
  "roles": {
    "captain": [
      "*:view",
      "*:update",
      "*:create",
      "collection:manage"
    ],
    "harpooner": [
      "*:view",
      "*:update",
      "*:create"
    ],
    "crew": [
      "*:view",
      "entity:create"
    ],
    "public": [
      "entity:view",
      "collection:view"
    ]
  }
}
{
  "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"
}

List collection members

GET
/collections/{id}/members

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

include_expired?string

Include expired memberships in response

Default"false"
Value in"true" | "false"

Response Body

application/json

application/json

application/json

curl -X GET "https://arke-v1.arke.institute/collections/01KDETYWYWM0MJVKM8DK3AEXPY/members"
{
  "collection_id": "string",
  "members": [
    {
      "userId": "string",
      "role": "string",
      "userLabel": "string",
      "expires_at": "2019-08-24T14:15:22Z",
      "granted_at": "2019-08-24T14:15:22Z",
      "granted_by": "string",
      "is_expired": true
    }
  ],
  "groups": [
    {
      "groupId": "string",
      "role": "string",
      "groupLabel": "string"
    }
  ],
  "wildcards": [
    {
      "role": "string"
    }
  ]
}
{
  "error": "Forbidden: You do not have permission to perform this action"
}
{
  "error": "Entity not found"
}

Assign user to role

POST
/collections/{id}/members

Authorization

bearerAuth
AuthorizationBearer <token>

Supabase JWT token

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

user_id*string

User entity ID to assign the role to

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

Role name to assign

Length1 <= length <= 50
expires_in?integer

Seconds until this role assignment expires (omit for permanent access)

Range0 <= value

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://arke-v1.arke.institute/collections/01KDETYWYWM0MJVKM8DK3AEXPY/members" \  -H "Content-Type: application/json" \  -d '{    "user_id": "01JQ3EQ3EG000000000000000",    "role": "harpooner"  }'
{
  "id": "01KDETYWYWM0MJVKM8DK3AEXPY",
  "cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
  "prev_cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
  "ver": 1,
  "member_added": {
    "user_id": "string",
    "role": "string",
    "expires_at": "2025-01-15T00:00:00.000Z",
    "granted_at": "2025-01-01T12:00:00.000Z",
    "granted_by": "string"
  }
}
{
  "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"
}

Remove user from role

DELETE
/collections/{id}/members/{userId}

Authorization

bearerAuth
AuthorizationBearer <token>

Supabase JWT token

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})$
userId*string

User 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

role*string

Role to remove user from

Length1 <= length

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X DELETE "https://arke-v1.arke.institute/collections/01KDETYWYWM0MJVKM8DK3AEXPY/members/01JQ3EQ3EG000000000000000?role=crew"
{
  "id": "01KDETYWYWM0MJVKM8DK3AEXPY",
  "cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
  "prev_cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
  "ver": 1,
  "member_removed": {
    "user_id": "string",
    "role": "string"
  }
}
{
  "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"
}

Set root entity

PUT
/collections/{id}/root

Authorization

bearerAuth
AuthorizationBearer <token>

Supabase JWT token

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
entity_id*string

Entity ID to set as the root of this collection. Entity must already have a collection relationship pointing to this collection.

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

application/json

curl -X PUT "https://arke-v1.arke.institute/collections/01KDETYWYWM0MJVKM8DK3AEXPY/root" \  -H "Content-Type: application/json" \  -d '{    "expect_tip": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",    "entity_id": "01JQ3EQ3EG000000000000000"  }'
{
  "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",
  "root_entity_id": "string"
}
{
  "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"
  }
}

List entities in a collection

GET
/collections/{id}/entities

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

type?string

Filter entities by type

limit?integer

Maximum number of entities to return

Default1000
Range1 <= value <= 10000
offset?integer

Number of entities to skip

Default0
Range0 <= value
expand?string

Expand entity data. "preview" adds lightweight previews, "full" adds complete manifests. Maximum 100 entities when using expand.

Value in"preview" | "full"

Response Body

application/json

application/json

application/json

curl -X GET "https://arke-v1.arke.institute/collections/01KDETYWYWM0MJVKM8DK3AEXPY/entities"
{
  "collection_id": "string",
  "entities": [
    {
      "pi": "string",
      "type": "document",
      "label": "My Document",
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "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"
      },
      "entity": {
        "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"
      }
    }
  ],
  "pagination": {
    "offset": 0,
    "limit": 0,
    "count": 0,
    "has_more": true
  }
}
{
  "error": "Forbidden: You do not have permission to perform this action"
}
{
  "error": "Entity not found"
}
Empty

Auth

Previous Page

Documentation

Next Page