72 lines
1.8 KiB
Markdown
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.
|
|
|