1.8 KiB
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.