> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truedy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Knowledge (Native RAG)

# Knowledge (Native RAG)

This is Truedy's only public knowledge workflow. `Knowledge Base` is a
product label for a Knowledge Space; both creation and source management use
the native RAG infrastructure. The legacy `/knowledge-bases` URL is retained
as a compatibility alias to the same space resources and does not create a
separate legacy corpus.

All endpoints require `Authorization: Bearer YOUR_API_KEY`. Use `X-Idempotency-Key` on create, update, and archive mutations when a safe retry is needed.

## Resource lifecycle

| Method   | Path                           | Purpose                                               |
| -------- | ------------------------------ | ----------------------------------------------------- |
| `GET`    | `/knowledge-spaces`            | List active spaces                                    |
| `POST`   | `/knowledge-spaces`            | Create a space                                        |
| `GET`    | `/knowledge-spaces/{space_id}` | Retrieve a space                                      |
| `PATCH`  | `/knowledge-spaces/{space_id}` | Update metadata or archive state                      |
| `DELETE` | `/knowledge-spaces/{space_id}` | Soft-archive a space                                  |
| `GET`    | `/knowledge-spaces/unified`    | List legacy and RAG resources with an explicit `kind` |

<Endpoint method="GET" path="/api/public/v1/knowledge-spaces" />

<Endpoint method="POST" path="/api/public/v1/knowledge-spaces" />

<Endpoint method="GET" path="/api/public/v1/knowledge-spaces/{space_id}" />

<Endpoint method="PATCH" path="/api/public/v1/knowledge-spaces/{space_id}" />

<Endpoint method="DELETE" path="/api/public/v1/knowledge-spaces/{space_id}" />

<Endpoint method="GET" path="/api/public/v1/knowledge-spaces/unified" />

## Sources and ingestion

Sources support `text`, `url`, `sitemap`, and private `upload` kinds. Uploads use `POST /knowledge-spaces/{space_id}/sources/upload-url`, followed by `POST /knowledge-spaces/{space_id}/sources` with the returned private storage path. Source creation returns the source, version, and queued ingestion job together.

| Method             | Path                                               | Purpose                         |
| ------------------ | -------------------------------------------------- | ------------------------------- |
| `GET/POST`         | `/knowledge-spaces/{space_id}/sources`             | List or create sources          |
| `GET/PATCH/DELETE` | `/knowledge-spaces/{space_id}/sources/{source_id}` | Read, edit, or archive a source |

<Endpoint method="GET" path="/api/public/v1/knowledge-spaces/{space_id}/sources" />

<Endpoint method="POST" path="/api/public/v1/knowledge-spaces/{space_id}/sources" />

<Endpoint method="GET" path="/api/public/v1/knowledge-spaces/{space_id}/sources/{source_id}" />

<Endpoint method="PATCH" path="/api/public/v1/knowledge-spaces/{space_id}/sources/{source_id}" />

<Endpoint method="DELETE" path="/api/public/v1/knowledge-spaces/{space_id}/sources/{source_id}" />

### Create an upload URL

<Endpoint method="POST" path="/api/public/v1/knowledge-spaces/{space_id}/sources/upload-url" />

Request body:

```json theme={null}
{
  "filename": "refund-policy.pdf",
  "content_type": "application/pdf",
  "byte_size": 184320
}
```

The response is `200 OK` with `data.bucket`, `data.path`, `data.signed_url`, `data.token`, `data.expires_in`, `data.content_type`, and `data.byte_size`. Upload the file to the returned signed URL, then create the `upload` source using the returned `path`.

### Ingestion response

Source creation returns the following response envelope:

```json theme={null}
{
  "data": {
    "source": { "id": "SOURCE_ID", "status": "active" },
    "version": { "id": "VERSION_ID", "version_number": 1, "status": "queued" },
    "job": { "id": "JOB_ID", "status": "queued", "progress_percent": 0, "stage": "queued" }
  },
  "meta": { "request_id": "...", "ts": "2026-08-20T00:00:00Z" }
}
```

Ingestion is processed asynchronously by Truedy. Use the source status returned by the list or source-detail endpoints to observe completion; job inspection and manual retry remain dashboard operations.

The compatibility `/knowledge-bases` URL maps to these same Knowledge Spaces.
New integrations should use `/knowledge-spaces` and the `knowledge` agent
reference with `{"kind":"rag_v2","id":"SPACE_ID"}`.