Arke
ReferenceAPI Reference

Search

Cross-collection semantic search

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

Find similar collections

POST
/search/similar/collections

Authorization

bearerAuth
AuthorizationBearer <token>

Supabase JWT token

In: header

Request Body

application/json

pi*string

Collection PI to find similar collections for

limit?number

Maximum results to return

Default10
Range1 <= value <= 100
refresh?boolean

Force fresh query, bypassing cache

Defaultfalse
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

application/json

curl -X POST "https://arke-v1.arke.institute/search/similar/collections" \  -H "Content-Type: application/json" \  -d '{    "pi": "string"  }'
{
  "results": [
    {
      "pi": "string",
      "label": "string",
      "score": 0,
      "created_at": "string",
      "updated_at": "string",
      "entity_preview": {
        "id": "01KCOLLECTION123456789ABCD",
        "type": "collection",
        "label": "Research Papers Collection",
        "collection_pi": "01JCOLLECTION123456789AB",
        "description_preview": "A curated collection of academic research papers...",
        "created_at": "2026-01-10T00:00:00.000Z",
        "updated_at": "2026-01-15T12:00: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": {
    "source_pi": "string",
    "result_count": 0,
    "cached": true,
    "cached_at": "string"
  }
}
{
  "error": "Validation failed",
  "details": {
    "issues": [
      {
        "path": [
          "properties",
          "label"
        ],
        "message": "Required"
      }
    ]
  }
}
{
  "error": "Entity not found"
}
{
  "error": "Service unavailable",
  "details": {
    "service": "pinecone"
  }
}

Find similar items across collections

POST
/search/similar/items

Authorization

bearerAuth
AuthorizationBearer <token>

Supabase JWT token

In: header

Request Body

application/json

pi*string

Entity PI to find similar items for

collection_pi*string

Entity's collection PI

limit?number

Maximum results to return

Default20
Range1 <= value <= 100
tier1_limit?number

Number of similar collections to search

Default10
Range1 <= value <= 50
tier2_limit?number

Items to fetch per collection

Default5
Range1 <= value <= 20
include_same_collection?boolean

Include results from the same collection

Defaulttrue
refresh?boolean

Force fresh query, bypassing cache

Defaultfalse
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

application/json

curl -X POST "https://arke-v1.arke.institute/search/similar/items" \  -H "Content-Type: application/json" \  -d '{    "pi": "string",    "collection_pi": "string"  }'
{
  "results": [
    {
      "pi": "string",
      "type": "string",
      "label": "string",
      "collection_pi": "string",
      "score": 0,
      "created_at": "string",
      "updated_at": "string",
      "entity_preview": {
        "id": "01KENTITY123456789ABCDEFGH",
        "type": "document",
        "label": "Similar Research Paper",
        "collection_pi": "01JCOLLECTION123456789AB",
        "description_preview": "Related findings on distributed systems...",
        "created_at": "2026-01-08T00:00:00.000Z",
        "updated_at": "2026-01-12T10:00: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": {
    "source_pi": "string",
    "collections_searched": 0,
    "result_count": 0,
    "cached": true,
    "cached_at": "string"
  }
}
{
  "error": "Validation failed",
  "details": {
    "issues": [
      {
        "path": [
          "properties",
          "label"
        ],
        "message": "Required"
      }
    ]
  }
}
{
  "error": "Entity not found"
}
{
  "error": "Service unavailable",
  "details": {
    "service": "pinecone"
  }
}

Search collections by text

POST
/search/collections

Authorization

bearerAuth
AuthorizationBearer <token>

Supabase JWT token

In: header

Request Body

application/json

query*string

Search query text

Length1 <= length <= 500
limit?number

Maximum results to return

Default10
Range1 <= value <= 100
types?array<>

Filter by collection types

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/search/collections" \  -H "Content-Type: application/json" \  -d '{    "query": "string"  }'
{
  "results": [
    {
      "pi": "string",
      "label": "string",
      "type": "string",
      "score": 0,
      "created_at": "string",
      "updated_at": "string",
      "entity_preview": {
        "id": "01KCOLLECTION123456789ABCD",
        "type": "collection",
        "label": "Machine Learning Papers",
        "collection_pi": "01JCOLLECTION123456789AB",
        "description_preview": "A collection of papers on neural networks and deep learning...",
        "created_at": "2026-01-05T00:00:00.000Z",
        "updated_at": "2026-01-10T08:00: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",
    "result_count": 0
  }
}
{
  "error": "Validation failed",
  "details": {
    "issues": [
      {
        "path": [
          "properties",
          "label"
        ],
        "message": "Required"
      }
    ]
  }
}
{
  "error": "Service unavailable",
  "details": {
    "service": "pinecone"
  }
}

Search agents by text

POST
/search/agents

Authorization

bearerAuth
AuthorizationBearer <token>

Supabase JWT token

In: header

Request Body

application/json

query*string

Search query text

Length1 <= length <= 500
limit?number

Maximum results to return

Default10
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"
scope?string

Search scope. "official" (default) searches only the pre-approved Arke agents collection. "all" searches all agents network-wide (not recommended - may include duplicates, outdated, or unapproved agents).

Default"official"
Value in"official" | "all"

Response Body

application/json

application/json

application/json

curl -X POST "https://arke-v1.arke.institute/search/agents" \  -H "Content-Type: application/json" \  -d '{    "query": "string"  }'
{
  "results": [
    {
      "pi": "string",
      "label": "string",
      "score": 0,
      "collection_pi": "string",
      "status": "string",
      "created_at": "string",
      "updated_at": "string",
      "entity_preview": {
        "id": "01KAGENT123456789ABCDEFGHI",
        "type": "agent",
        "label": "Document Analyzer Agent",
        "collection_pi": "01JCOLLECTION123456789AB",
        "description_preview": "An AI agent that analyzes documents and extracts key insights...",
        "created_at": "2026-01-01T00:00:00.000Z",
        "updated_at": "2026-01-15T16:00: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",
    "result_count": 0
  }
}
{
  "error": "Validation failed",
  "details": {
    "issues": [
      {
        "path": [
          "properties",
          "label"
        ],
        "message": "Required"
      }
    ]
  }
}
{
  "error": "Service unavailable",
  "details": {
    "service": "pinecone"
  }
}

Search entities within collection(s)

POST
/search/entities

Authorization

bearerAuth
AuthorizationBearer <token>

Supabase JWT token

In: header

Request Body

application/json

collection_pi?string

Single collection PI to search within

collection_pis?array<>

Multiple collection PIs to search (max 20)

Itemsitems <= 20
query*string

Search query text

Length1 <= length <= 500
limit?number

Maximum total results to return

Default20
Range1 <= value <= 100
types?array<>

Filter by entity types

per_collection_limit?number

Max results per collection for diversity

Range1 <= value <= 50
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/search/entities" \  -H "Content-Type: application/json" \  -d '{    "query": "string"  }'
{
  "results": [
    {
      "pi": "string",
      "label": "string",
      "type": "string",
      "score": 0,
      "collection_pi": "string",
      "created_at": "string",
      "updated_at": "string",
      "entity_preview": {
        "id": "01KENTITY123456789ABCDEFGH",
        "type": "document",
        "label": "Research Findings Report",
        "collection_pi": "01JCOLLECTION123456789AB",
        "description_preview": "Detailed analysis of experimental results...",
        "created_at": "2026-01-10T00:00:00.000Z",
        "updated_at": "2026-01-14T09:00: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": {
    "collection_pis": [
      "string"
    ],
    "query": "string",
    "collections_searched": 0,
    "result_count": 0
  }
}
{
  "error": "Validation failed",
  "details": {
    "issues": [
      {
        "path": [
          "properties",
          "label"
        ],
        "message": "Required"
      }
    ]
  }
}
{
  "error": "Service unavailable",
  "details": {
    "service": "pinecone"
  }
}

Discover entities across all collections

POST
/search/discover

Authorization

bearerAuth
AuthorizationBearer <token>

Supabase JWT token

In: header

Request Body

application/json

query*string

Search query text

Length1 <= length <= 500
limit?number

Maximum total results to return

Default20
Range1 <= value <= 100
types?array<>

Filter by entity types

collection_limit?number

Number of collections to search

Default10
Range1 <= value <= 50
per_collection_limit?number

Max results per collection

Default5
Range1 <= value <= 20
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/search/discover" \  -H "Content-Type: application/json" \  -d '{    "query": "string"  }'
{
  "results": [
    {
      "pi": "string",
      "label": "string",
      "type": "string",
      "score": 0,
      "collection_pi": "string",
      "created_at": "string",
      "updated_at": "string",
      "entity_preview": {
        "id": "01KENTITY123456789ABCDEFGH",
        "type": "file",
        "label": "Discovered Document.pdf",
        "collection_pi": "01JCOLLECTION123456789AB",
        "description_preview": "A document discovered through semantic search...",
        "created_at": "2026-01-08T00:00:00.000Z",
        "updated_at": "2026-01-12T14:00: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_searched": 0,
    "result_count": 0
  }
}
{
  "error": "Validation failed",
  "details": {
    "issues": [
      {
        "path": [
          "properties",
          "label"
        ],
        "message": "Required"
      }
    ]
  }
}
{
  "error": "Service unavailable",
  "details": {
    "service": "pinecone"
  }
}

Relationships

Previous Page

Users

Next Page