RAG-POC/docs/api.md

1.8 KiB

Internal API reference

All routes are under /internal/knowledge-graph. Health is unauthenticated; other routes require an internal signed JWT from the BFF.

Endpoints

Method and path Permission Behavior
GET /health none process liveness
GET /ready none database and PgVector readiness
POST /jobs stage 1: 18; downstream: 16 queue stages 1-8
GET /jobs/{jobId} 1 durable job and stage status
POST /jobs/{jobId}/retry 16 requeue a failed job
POST /query 17 synchronous retrieval
POST /answer 17 synchronous retrieval plus cited answer

Permission bits are Read=1, Add=2, Edit=4, Delete=8, and Execute=16.

Job request

{
  "corpus": "product-knowledge",
  "from_stage": 1,
  "through_stage": 8,
  "input_jsonl": "/app/artifacts/mcp-documents.jsonl",
  "model_file": "/app/src/templates/knowledge_model.json",
  "reset": false
}

Long-running job submission returns 202 Accepted with a job_id. Query and answer remain synchronous and bounded.

Query and answer requests

{
  "corpus": "product-knowledge",
  "question": "Who created Atlas?",
  "top_k": 8
}

Retrieval returns vector context, bounded graph_context, and traceable sources. Answer generation asks the LLM to cite those sources as [S1], [S2], and so on.

JWT contract

The verifier expects HS256 in the current implementation and validates iss, aud, sub, iat, exp, jti, and a feature permission mask:

{
  "iss": "knowledgegraph-bff",
  "aud": "knowledgegraph-service",
  "sub": "internal-caller-id",
  "iat": 1791930000,
  "exp": 1791930600,
  "jti": "request-id",
  "features": {
    "KnowledgeGraph": 31
  }
}

The BFF remains the policy enforcement point. Do not substitute unsigned headers for the token.