# 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 ```json { "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 ```json { "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: ```json { "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.