RAG-DEMO/docs/api.md

72 lines
1.8 KiB
Markdown

# 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.