Arke
ReferenceAPI Reference

Users

User profile management

Get current user

GET
/users/me

Authorization

bearerAuth
AuthorizationBearer <token>

Supabase JWT token

In: header

Response Body

application/json

application/json

curl -X GET "https://arke-v1.arke.institute/users/me"
{
  "id": "01KDETYWYWM0MJVKM8DK3AEXPY",
  "cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
  "type": "user",
  "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": "Unauthorized: Missing or invalid authentication token"
}
Empty

Get user by ID

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

PUT
/users/{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 display name

Length1 <= length

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

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

List API keys

GET
/users/me/keys

Authorization

bearerAuth
AuthorizationBearer <token>

Supabase JWT token

In: header

Response Body

application/json

application/json

curl -X GET "https://arke-v1.arke.institute/users/me/keys"
{
  "keys": [
    {
      "key_prefix": "uk_xKj9",
      "label": "Production",
      "created_at": "2025-12-28T00:00:00.000Z",
      "expires_at": "2026-03-28T00:00:00.000Z",
      "last_used_at": "2025-12-28T10:30:00.000Z"
    }
  ]
}
{
  "error": "Unauthorized: Missing or invalid authentication token"
}

Create API key

POST
/users/me/keys

Authorization

bearerAuth
AuthorizationBearer <token>

Supabase JWT token

In: header

Request Body

application/json

label?string

Human-readable label for the key

Lengthlength <= 100
expires_in?integer

Time until expiration in seconds (default: 90 days, max: 365 days)

Range0 <= value <= 31536000

Response Body

application/json

application/json

curl -X POST "https://arke-v1.arke.institute/users/me/keys" \  -H "Content-Type: application/json" \  -d '{}'
{
  "key": "uk_xKj92mNpQrStUvWxYz1234567890abcdef1234567890abcdef12345678",
  "key_prefix": "uk_xKj9",
  "expires_at": "2026-03-28T00:00:00.000Z"
}
{
  "error": "Unauthorized: Missing or invalid authentication token"
}

Revoke API key

DELETE
/users/me/keys/{prefix}

Authorization

bearerAuth
AuthorizationBearer <token>

Supabase JWT token

In: header

Path Parameters

prefix*string

API key prefix (e.g., uk_xKj9)

Length4 <= length <= 12

Response Body

application/json

application/json

curl -X DELETE "https://arke-v1.arke.institute/users/me/keys/uk_xKj9"
Empty
{
  "error": "Unauthorized: Missing or invalid authentication token"
}
{
  "error": "Entity not found"
}

List collections user has access to

GET
/users/{id}/collections

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

predicate?string

Filter by role predicate (e.g., owner, editor)

limit?string

Maximum number of results (default: 100, max: 1000)

offset?string

Pagination offset

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://arke-v1.arke.institute/users/01KDETYWYWM0MJVKM8DK3AEXPY/collections"
{
  "user_id": "01JUSER123456789ABCDEFGH",
  "collections": [
    {
      "pi": "01JCOLLECTION123456789AB",
      "label": "My Research Collection",
      "predicate": "owner",
      "created_at": "2026-01-12T00:00:00.000Z"
    }
  ],
  "pagination": {
    "offset": 0,
    "limit": 0,
    "count": 0,
    "has_more": true
  }
}
{
  "error": "Unauthorized: Missing or invalid authentication token"
}
{
  "error": "Forbidden: You do not have permission to perform this action"
}
{
  "error": "Entity not found"
}
Empty

Search across user collections

POST
/users/me/search

Authorization

bearerAuth
AuthorizationBearer <token>

Supabase JWT token

In: header

Request Body

application/json

query*string

Search query text for semantic matching

Length1 <= length <= 500
type?string

Filter results to specific entity type

role?string

Filter collections by user role (only search collections where user has this role)

Value in"owner" | "editor" | "viewer"
include_public?boolean

Include results from public-domain namespace (default: false)

Defaultfalse
limit?integer

Maximum number of results to return (default: 20, max: 100)

Default20
Range1 <= value <= 100
expand?string

Entity expansion mode. Default: "preview" for lightweight previews, "full" for complete manifests, "none" for no expansion.

Value in"preview" | "full" | "none"

Response Body

application/json

application/json

application/json

curl -X POST "https://arke-v1.arke.institute/users/me/search" \  -H "Content-Type: application/json" \  -d '{    "query": "medical research"  }'
{
  "results": [
    {
      "pi": "01KDETYWYWM0MJVKM8DK3AEXPY",
      "type": "file",
      "label": "Research Paper.pdf",
      "collection_pi": "01JCOLLECTION123456789AB",
      "score": 0.87,
      "created_at": "2026-01-12T00:00:00.000Z",
      "updated_at": "2026-01-12T10:30:00.000Z",
      "entity_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"
      }
    }
  ],
  "metadata": {
    "query": "string",
    "collections_queried": 0,
    "collections_total": 0,
    "include_public": true,
    "execution_time_ms": 0,
    "result_count": 0
  }
}
{
  "error": "Validation failed",
  "details": {
    "issues": [
      {
        "path": [
          "properties",
          "label"
        ],
        "message": "Required"
      }
    ]
  }
}
{
  "error": "Unauthorized: Missing or invalid authentication token"
}
Empty

Search

Previous Page

Eidos Schema

Reference for the arke/eidos@v2 base entity schema.