API

Metis is part of the Astralyx API at https://api.astralyx.cloud/v1, in JSON; its paths start with /metis/. Every endpoint, with its parameters, bodies, responses and examples, is in the Metis API reference. Authentication, choosing the workspace and the error format are in the API Reference overview.

Endpoints

Method and path	What it does
GET /metis/knowledge-bases	List knowledge bases, with their state and totals
POST /metis/knowledge-bases	Create one (?dry_run=true: check only)
GET /metis/knowledge-bases/{name}	Read one
PUT /metis/knowledge-bases/{name}	Change its spec
DELETE /metis/knowledge-bases/{name}	Delete it and its index
POST /metis/knowledge-bases/{name}/search	Search: {"query", "top_k", "filters", "mode", "rerank"} → results with citations
GET /metis/knowledge-bases/{name}/status	The index's phase, progress, totals and first errors
GET /metis/knowledge-bases/{name}/documents	Its documents (?failed=true&source=&prefix=&offset=&limit=)
POST /metis/knowledge-bases/{name}/reindex	Look for changes now ({"full": true}: read everything again)
POST /metis/knowledge-bases/{name}/evaluate	Recall@k and MRR of an evaluation set (cases, or file: "<drive>:<path>")

Roles

Role in the workspace	May
viewer	List and read knowledge bases, their status and documents; search them.
editor, admin	Also create, change, delete, reindex and evaluate them.
auditor	Nothing.

With custom roles, the permissions are knowledge-bases:read, read-content (documents and their errors), create, update, delete, search, reindex and evaluate.

A search

$ curl -fsS -X POST "$ASTRALYX_API/metis/knowledge-bases/handbook/search" \
    -H "Authorization: Bearer $ASTRALYX_TOKEN" -H 'content-type: application/json' \
    -d '{"query": "How many vacation days do I have?", "top_k": 3, "filters": {"path_prefix": "handbook/"}}'

{
  "query": "How many vacation days do I have?",
  "mode": "hybrid",
  "reranked": true,
  "results": [
    {
      "score": 0.97,
      "text": "Each person has 25 vacation days a year. Ask your manager two weeks ahead.",
      "citation": {
        "source": "docs",
        "document": "handbook/leave.md",
        "title": "Leave policy",
        "kind": "md",
        "headings": ["Leave policy", "Vacation"],
        "line": 7,
        "snippet": "Each person has 25 vacation days a year."
      },
      "scores": {"dense": 0.83, "keyword": 7.41, "fused": 0.0328, "rerank": 0.97}
    }
  ],
  "took": {"embed_ms": 21, "retrieve_ms": 4, "rerank_ms": 38, "total_ms": 64}
}

Error codes are listed in the specification.