API reference

curl -s http://localhost:38888/health
# {"status":"healthy"}

# Body
# { "id": "t_acme", "name": "Acme Corp" }

curl -X POST http://localhost:38888/v1/tenants \
  -H 'content-type: application/json' \
  -d '{"id":"t_acme","name":"Acme Corp"}'

# 201 Created
# {"id":"t_acme","name":"Acme Corp","created_at":"..."}

# Body
# { "id": "i_docs", "name": "product-docs", "description": "..." }

curl -X POST http://localhost:38888/v1/tenants/t_acme/indexes \
  -H 'content-type: application/json' \
  -d '{"id":"i_docs","name":"product-docs"}'

# 201 Created → IndexInfo (id, tenant_id, name, status, num_docs, ...)

# Body
# {
#   "documents": [
#     {"id":"doc-1","text":"...","metadata":{"key":"val"},"repo_id":"..."}
#   ]
# }

curl -X POST \
  http://localhost:38888/v1/tenants/t_acme/indexes/i_docs/documents \
  -H 'content-type: application/json' \
  -d '{"documents":[{"id":"doc-1","text":"hello"}]}'

# 200 OK
# { "added": 1, "chunk_ids": ["..."] }

# Body
# {
#   "query": "...",
#   "k": 10,
#   "filter": {
#     "repo_ids": ["repo-a"],
#     "equals": { "author": "alice", "content_type": "email" }
#   }
# }

curl -X POST \
  http://localhost:38888/v1/tenants/t_acme/indexes/i_docs/search \
  -H 'content-type: application/json' \
  -d '{"query":"how does search work","k":5}'

# 200 OK
# {
#   "results": [
#     {"id":"...","text":"...","score":0.82,"metadata":{...}}
#   ],
#   "total": 5
# }

# Start a hot-swap
curl -X PATCH \
  http://localhost:38888/v1/tenants/t_acme/indexes/i_docs/embedding-model \
  -H 'content-type: application/json' \
  -d '{"embedding_model":"nomic-embed-text:v1.5"}'

# 202 Accepted
# {"job_id":"job_...","status":"running","progress":0}

# Poll
curl http://localhost:38888/v1/jobs/job_...
# {"job_id":"job_...","status":"running","progress":0.42,
#  "processed":420,"total":1000,"started_at":"..."}

# Per-node sidecar (port = http-port + 1)
curl http://localhost:38889/cluster/members

# Returns the gossip member list with node_id, zone, address, status.

curl http://localhost:38888/metrics | head -20

# graphann_search_requests_total{tenant="t_acme",index="i_docs"} 1234
# graphann_search_latency_seconds_bucket{le="0.05"} 980
# ...

# 404 Not Found
# {"error":"Index not found","code":"not_found"}

# 400 Bad Request
# {"error":"Invalid tenant ID format","code":"bad_request"}

# 429 Too Many Requests
# {"error":"Documents per index quota exceeded","code":"quota_exceeded"}