Arke
ReferenceAPI Reference

Folders

Folder hierarchy management

Create folder

POST
/folders

Authorization

bearerAuth
AuthorizationBearer <token>

Supabase JWT token

In: header

Request Body

application/json

note?string

Optional note describing this change

label*string

Display name for the folder

Length1 <= length
description?string

Short description

rich_description?string

Rich content description (markdown)

metadata?

Flexible metadata

properties?

Additional properties to store

relationships?array<>

Relationships to create

collection?string

Collection to add folder to (for permissions). Shortcut for adding a collection relationship.

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

Parent folder ID (creates bidirectional relationship)

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 POST "https://arke-v1.arke.institute/folders" \  -H "Content-Type: application/json" \  -d '{    "label": "Research Documents"  }'
{
  "id": "01KDETYWYWM0MJVKM8DK3AEXPY",
  "cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
  "type": "folder",
  "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"
  }
}
{
  "error": "Validation failed",
  "details": {
    "issues": [
      {
        "path": [
          "properties",
          "label"
        ],
        "message": "Required"
      }
    ]
  }
}
{
  "error": "Unauthorized: Missing or invalid authentication token"
}
{
  "error": "Internal server error"
}

Get folder

GET
/folders/{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/folders/01KDETYWYWM0MJVKM8DK3AEXPY"
{
  "id": "01KDETYWYWM0MJVKM8DK3AEXPY",
  "cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
  "type": "folder",
  "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 folder

PUT
/folders/{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

New display name

Length1 <= length
description?string

New description

rich_description?string

New rich description

metadata?

New metadata (deep merged)

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PUT "https://arke-v1.arke.institute/folders/01KDETYWYWM0MJVKM8DK3AEXPY" \  -H "Content-Type: application/json" \  -d '{    "expect_tip": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy"  }'
{
  "id": "01KDETYWYWM0MJVKM8DK3AEXPY",
  "cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
  "type": "folder",
  "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 child to folder

POST
/folders/{id}/children

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

child_id*string

Child entity ID to add (file or folder)

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

Expected CID of child (CAS guard, optional if child in open season)

Length1 <= length

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://arke-v1.arke.institute/folders/01KDETYWYWM0MJVKM8DK3AEXPY/children" \  -H "Content-Type: application/json" \  -d '{    "expect_tip": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",    "child_id": "01KDETYWYWM0MJVKM8DK3AEXPY"  }'
{
  "folder": {
    "id": "01KDETYWYWM0MJVKM8DK3AEXPY",
    "cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
    "type": "folder",
    "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"
  },
  "child": {
    "id": "01KDETYWYWM0MJVKM8DK3AEXPY",
    "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"
  }
}

Remove child from folder

DELETE
/folders/{id}/children/{childId}

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

Child entity ID

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

expect_child_tip*string

Expected CID of child (CAS guard)

Length1 <= length

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X DELETE "https://arke-v1.arke.institute/folders/01KDETYWYWM0MJVKM8DK3AEXPY/children/01JFILE456ABCDEFGHJKMNPQRS" \  -H "Content-Type: application/json" \  -d '{    "expect_tip": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",    "expect_child_tip": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy"  }'
{
  "folder": {
    "id": "01KDETYWYWM0MJVKM8DK3AEXPY",
    "cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
    "type": "folder",
    "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"
  },
  "child": {
    "id": "01KDETYWYWM0MJVKM8DK3AEXPY",
    "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"
  }
}

Bulk add children to folder

POST
/folders/{id}/children/bulk

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

children*array<>

Children to add (max 50 per request)

Items1 <= items <= 50

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://arke-v1.arke.institute/folders/01KDETYWYWM0MJVKM8DK3AEXPY/children/bulk" \  -H "Content-Type: application/json" \  -d '{    "expect_tip": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",    "children": [      {        "id": "01JFILE123ABCDEFGHJKMNPQRS"      },      {        "id": "01JFOLDER456ABCDEFGHJKMNPQ",        "type": "folder"      }    ]  }'
{
  "folder": {
    "id": "01KDETYWYWM0MJVKM8DK3AEXPY",
    "cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
    "type": "folder",
    "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"
  },
  "added": [
    {
      "id": "01KDETYWYWM0MJVKM8DK3AEXPY",
      "cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy"
    }
  ],
  "skipped": [
    "01KDETYWYWM0MJVKM8DK3AEXPY"
  ]
}
{
  "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 parent to folder

POST
/folders/{id}/parents

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

parent_id*string

Parent folder or collection ID to add

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

Expected CID of parent (CAS guard, optional if parent in open season)

Length1 <= length

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://arke-v1.arke.institute/folders/01KDETYWYWM0MJVKM8DK3AEXPY/parents" \  -H "Content-Type: application/json" \  -d '{    "expect_tip": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",    "parent_id": "01KDETYWYWM0MJVKM8DK3AEXPY"  }'
{
  "folder": {
    "id": "01KDETYWYWM0MJVKM8DK3AEXPY",
    "cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
    "type": "folder",
    "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"
  },
  "parent": {
    "id": "01KDETYWYWM0MJVKM8DK3AEXPY",
    "cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
    "type": "folder",
    "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"
  }
}

Remove parent from folder

DELETE
/folders/{id}/parents/{parentId}

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

Parent folder ID

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

expect_parent_tip*string

Expected CID of parent (CAS guard)

Length1 <= length

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X DELETE "https://arke-v1.arke.institute/folders/01KDETYWYWM0MJVKM8DK3AEXPY/parents/01JPARENT78ABCDEFGHJKMNPQR" \  -H "Content-Type: application/json" \  -d '{    "expect_tip": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",    "expect_parent_tip": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy"  }'
{
  "folder": {
    "id": "01KDETYWYWM0MJVKM8DK3AEXPY",
    "cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
    "type": "folder",
    "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"
  },
  "parent": {
    "id": "01KDETYWYWM0MJVKM8DK3AEXPY",
    "cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
    "type": "folder",
    "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"
  }
}

Files

Previous Page

Graph

Next Page