# Knowledge

> The Knowledge operations of the Hub REST API (10 operations).

URL: https://docs.synap.live/docs/reference/hub-api/knowledge · Generated from Synap-core/backend@c31e261ab (main)

Paths are relative to `/api/hub` on a pod.

## GET /knowledge

List knowledge entries

Pod-wide procedural docs addressed by string key. When workspaceId is omitted, scopes to the authenticated user's namespace.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `namespace` | query | string |  |  |
| `status` | query | string |  |  |
| `workspaceId` | query | string |  |  |
| `limit` | query | string |  |  |
| `offset` | query | string |  |  |

Responses:

- `200`: Entries
- `400`: Bad request — the wrapped door refused the input
- `403`: Forbidden
- `404`: Not found
- `409`: Conflict — a refusal the caller can act on
- `412`: Precondition failed
- `500`: Internal error

## POST /knowledge

Create a knowledge entry

Supports `Idempotency-Key`.

Request body (`application/json`): CreateKnowledgeRequest

| Field | Type | Required | Description |
|---|---|---|---|
| `key` | string | yes |  |
| `value` | object |  |  |
| `namespace` | string |  |  |
| `slug` | string |  |  |
| `status` | string |  |  |
| `workspaceId` | string \| null |  |  |
| `author` | string |  |  |

Responses:

- `200`: Created
- `202`: Proposed for review — `{ status: 'proposed', proposalId, reviewUrl, key }`
- `400`: Validation failed
- `403`: Forbidden
- `404`: Not found
- `409`: Conflict — a refusal the caller can act on
- `412`: Precondition failed
- `500`: Internal error

## GET /knowledge/search

Full-text search knowledge entries

DEPRECATED — prefer POST /knowledge/ask, whose procedural lane calls the exact same searchFullText. Still functional for existing integrations.

Deprecated.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `q` | query | string |  |  |
| `query` | query | string |  |  |
| `workspaceId` | query | string |  |  |
| `limit` | query | string |  |  |

Responses:

- `200`: Matches
- `400`: Bad request
- `403`: Forbidden
- `404`: Not found
- `409`: Conflict — a refusal the caller can act on
- `412`: Precondition failed
- `500`: Internal error

## POST /knowledge/search

Retrieval — route a query across knowledge substrates

Routes a natural-language query to the right knowledge substrate(s) — semantic (typed entities), procedural (how-to docs), episodic (captures) — and returns raw matches tagged with which substrate(s) answered. For a synthesized human-readable answer use POST /knowledge/answer instead.

Request body (`application/json`): object

| Field | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes |  |
| `workspaceId` | string |  |  |
| `projectId` | string |  |  |
| `limit` | integer |  |  |
| `compare` | boolean |  |  |
| `parseOnly` | boolean |  |  |

Responses:

- `200`: Routed retrieval result
- `400`: Bad request — the wrapped door refused the input
- `403`: Forbidden
- `404`: Not found
- `409`: Conflict — a refusal the caller can act on
- `412`: Precondition failed
- `500`: Internal error

## GET /knowledge/{key}

Get a knowledge entry by key

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes |  |
| `workspaceId` | query | string |  |  |

Responses:

- `200`: Entry
- `400`: Bad request — the wrapped door refused the input
- `403`: Forbidden
- `404`: Not found
- `409`: Conflict — a refusal the caller can act on
- `412`: Precondition failed
- `500`: Internal error

## PUT /knowledge/{key}

Upsert a knowledge entry

Supports `Idempotency-Key`.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes |  |

Request body (`application/json`): UpsertKnowledgeRequest

| Field | Type | Required | Description |
|---|---|---|---|
| `value` | object |  |  |
| `status` | string |  |  |
| `author` | string |  |  |

Responses:

- `200`: Upserted
- `400`: Validation failed
- `403`: Forbidden
- `404`: Not found
- `409`: Conflict — a refusal the caller can act on
- `412`: Precondition failed
- `500`: Internal error

## DELETE /knowledge/{key}

Archive (soft-delete) a knowledge entry

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes |  |

Responses:

- `200`: Archived
- `400`: Bad request — the wrapped door refused the input
- `403`: Forbidden
- `404`: Not found
- `409`: Conflict — a refusal the caller can act on
- `412`: Precondition failed
- `500`: Internal error

## GET /graph/traverse

BFS traversal of the entity graph

maxDepth is clamped to 3.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `userId` | query | string |  |  |
| `startEntityId` | query | string | yes |  |
| `maxDepth` | query | string |  |  |
| `relationshipTypes` | query | string |  |  |

Responses:

- `200`: Traversal results
- `400`: Bad request
- `403`: Forbidden
- `404`: Not found
- `409`: Conflict — a refusal the caller can act on
- `412`: Precondition failed
- `500`: Internal error

## POST /knowledge/ask

DEPRECATED alias of /knowledge/search — raw retrieval door

DEPRECATED alias of POST /knowledge/search; retained for back-compat. Runs the exact same retrieval handler. Prefer POST /knowledge/search (retrieval) or POST /knowledge/answer (synthesized).

Deprecated.

Request body (`application/json`): object

| Field | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes |  |
| `workspaceId` | string |  |  |
| `projectId` | string |  |  |
| `limit` | integer |  |  |
| `compare` | boolean |  |  |
| `parseOnly` | boolean |  |  |

Responses:

- `200`: Routed retrieval result (identical to /knowledge/search)
- `400`: Bad request — the wrapped door refused the input
- `403`: Forbidden
- `404`: Not found
- `409`: Conflict — a refusal the caller can act on
- `412`: Precondition failed
- `500`: Internal error

## POST /knowledge/answer

Synthesized knowledge answer — retrieve + synthesize

Retrieves matches via the unified knowledge router, then synthesizes a single concise answer over that context with one focused LLM call. Returns the answer plus the sources it drew from; answer is null when synthesis is unavailable (callers fall back to the sources list).

Request body (`application/json`): object

| Field | Type | Required | Description |
|---|---|---|---|
| `query` | string |  |  |
| `question` | string |  |  |
| `workspaceId` | string |  |  |
| `projectId` | string |  |  |
| `limit` | integer |  |  |

Responses:

- `200`: Synthesized answer with sources
- `400`: Bad request
- `403`: Forbidden
- `404`: Not found
- `409`: Conflict — a refusal the caller can act on
- `412`: Precondition failed
- `500`: Internal error