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

# Facts and Wiki

> Canonical admin APIs for durable facts and managed wiki pages.

The canonical memory surface has two resources:

* `/admin/facts` reads the fact ledger and accepts explicit user pins.
* `/admin/wiki/pages` manages versioned wiki pages.

All endpoints require the usual Bearer token. See [Authentication](/api-reference/authentication).

## Facts

### List and search

`GET /admin/facts` lists facts. `GET /admin/facts/search?query=...` searches them.
Both accept `subject`, `include_inactive`, and `limit` (1–100). Use the returned
`next_after` object's `created_at` and `fact_id` as `after_created_at` and
`after_fact_id` together to continue a page.

```bash theme={null}
curl "http://localhost:6877/admin/facts/search?query=coffee&limit=20" \
  -H "Authorization: Bearer $API_KEY"
```

Responses contain `facts`, `total`, `has_more`, and `next_after`. Read one fact
with `GET /admin/facts/{fact_id}`; its response contains `fact`.

### Pin

`POST /admin/facts` persists one explicit user pin. Send a stable `request_id`
to make retries idempotent:

```bash theme={null}
curl -X POST http://localhost:6877/admin/facts \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"request_id":"result-2026-07-30-1","text":"Keep this result."}'
```

Other fact changes use the plan-and-commit agent tools rather than generic
HTTP mutation endpoints.

### Batch read

`POST /admin/facts/batch` reads up to the server's batch limit in one request:

```bash theme={null}
curl -X POST http://localhost:6877/admin/facts/batch \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fact_ids":["fact_1","fact_2"]}'
```

## Wiki pages

These `/admin` endpoints are the Desktop/backend concurrency interface, so they
expose internal page and revision identifiers. Agent wiki tools do not: they use
managed paths and keep this bookkeeping inside the server.

### Read

* `GET /admin/wiki/pages` lists active pages. Pass `include_redirects=true` to include redirects.
* `GET /admin/wiki/pages/{page_id}` reads one page, including `content`.
* `GET /admin/wiki/pages/{page_id}/history?limit=50` returns commit history (1–200).
* `GET /admin/wiki/pages/{page_id}/diff` returns a diff. It accepts optional `base`, `target`, `offset`, `limit`, and `tail`.
* `GET /admin/wiki/pages/{page_id}/links` returns outgoing links and backlinks.

Page responses include `page_id`, `path`, `resource_state`, `title`, `excerpt`,
`aliases`, `lifecycle`, `redirect_to`, `metadata`, `version`,
`repository_head`, `created_at`, and `updated_at`. Detail responses also include
`content`.

### Create

`POST /admin/wiki/pages` requires `path`, `title`, and `expected_head`. It also
accepts `body`, `page_id`, `aliases`, and `metadata`.

```bash theme={null}
curl -X POST http://localhost:6877/admin/wiki/pages \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path":"notes/coffee.md","title":"Coffee","body":"# Coffee\n","expected_head":null}'
```

### Update, archive, and restore

`PUT /admin/wiki/pages/{page_id}` requires `content`, `expected_version`, and
`expected_head`. Archive and restore use `POST` and require
`expected_version` and `expected_head`:

```bash theme={null}
curl -X POST http://localhost:6877/admin/wiki/pages/page_123/archive \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expected_version":"rev_123","expected_head":"commit_123"}'
```

Writes are optimistic: supply the version and repository head you read. A stale
write returns `409` with the current revision, head, and, when available, content.
Invalid paths or request values return `422`; unknown resources return `404`.

Restore one historical revision with:

```text theme={null}
POST /admin/wiki/pages/{page_id}/history/{commit_id}/restore
```

The request uses the current `expected_version` and `expected_head`, just like
other wiki writes.