Arke
ReferenceAPI Reference

Files

File storage with versioning

Create file entity

POST
/files

Authorization

bearerAuth
AuthorizationBearer <token>

Supabase JWT token

In: header

Request Body

application/json

key*string

Storage key in R2. Best practice: use the CID.

Length1 <= length
filename*string

Original filename

Length1 <= length
content_type*string

MIME type of the file

Length1 <= length
size*integer

Expected file size in bytes (verified on upload)

Range0 <= value
label?string

Display label for the file. Defaults to filename if not provided.

description?string

Description of the file

properties?

Additional properties to store

relationships?array<>

Relationships to create

collection?string

Collection to add this file 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})$

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://arke-v1.arke.institute/files" \  -H "Content-Type: application/json" \  -d '{    "key": "bafkreiabc123...",    "filename": "document.pdf",    "content_type": "application/pdf",    "size": 1048576  }'
{
  "id": "01KDETYWYWM0MJVKM8DK3AEXPY",
  "cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
  "type": "file",
  "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": "Conflict: entity was modified",
  "details": {
    "expected": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
    "actual": "bafyreinewabc123456789defghijklmnopqrstuvwxyz"
  }
}
{
  "error": "Internal server error"
}

Get file metadata

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

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

key?string

New storage key. Must already exist in R2 (for regression to old version).

Length1 <= length
filename?string

New filename

Length1 <= length
content_type?string

New MIME type

Length1 <= length
size?integer

New file size in bytes

Range0 <= value
label?string

New display label

description?string

New description

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

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

Download file content

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

Response Body

application/octet-stream

application/json

application/json

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

Upload file content

POST
/files/{id}/content

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})$

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://arke-v1.arke.institute/files/01KDETYWYWM0MJVKM8DK3AEXPY/content"
{
  "id": "01KDETYWYWM0MJVKM8DK3AEXPY",
  "cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
  "type": "file",
  "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"
  }
}
{
  "error": "Validation failed",
  "details": {
    "issues": [
      {
        "path": [
          "string"
        ],
        "message": "string"
      }
    ]
  }
}
{
  "error": "Internal server error"
}

Prepare for new file version

POST
/files/{id}/reupload

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

key*string

New storage key. Must NOT already exist in R2.

Length1 <= length
content_type*string

MIME type of the new file

Length1 <= length
size*integer

Expected size of the new file in bytes (verified on upload)

Range0 <= value
filename?string

New filename (optional, keeps current if not provided)

Length1 <= length
label?string

New display label (optional, keeps current if not provided)

description?string

New description

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://arke-v1.arke.institute/files/01KDETYWYWM0MJVKM8DK3AEXPY/reupload" \  -H "Content-Type: application/json" \  -d '{    "expect_tip": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",    "key": "v2",    "content_type": "application/pdf",    "size": 2097152  }'
{
  "id": "01KDETYWYWM0MJVKM8DK3AEXPY",
  "cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
  "type": "file",
  "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"
  }
}

Events

Previous Page

Folders

Next Page