# Knowledge bases

## What this covers

Documents your agents answer from. A base holds markdown or plain-text documents, read in the background; an agent links up to 3 bases with `knowledge_base_ids`. Small knowledge sits whole in the agent's prompt and larger knowledge is searched during the call, by keyword and, optionally, by meaning on your own Google or OpenAI account. Dvaarik charges nothing for it.

Every example below runs as written once these are exported:

```bash
export DVAARIK_API_KEY="dvk_..."        # project API key, server side only
export DVAARIK_TOKEN="<account access token>"   # console session, from POST /console/auth/login
export BASE_ID="<uuid>"
export DOCUMENT_ID="<uuid>"
export PROJECT_ID="<uuid>"
```

A `<value>` inside a JSON body is a value you supply. Responses are JSON; every error body is `{ "detail": … }`. Each schema is expanded once per page, where it first appears.

### Machine door errors

Raised by the project-key dependency before any handler on this page runs.

| Status | Cause |
| --- | --- |
| `401` | `Missing API key` or `Invalid API key` — the `X-Api-Key` header is absent, unknown, or revoked. |
| `403` | `API key is not scoped to a project`, `Project unavailable`, or `API key is missing the required scope '<scope>'`. |
| `429` | The project's `api_rpm` ceiling was exceeded. Honour `Retry-After`; `X-RateLimit-*` headers are on every response. |

Scopes used on this page: `voice:read`, `voice:write`. Mint a key with only these.

### Account door errors

| Status | Cause |
| --- | --- |
| `401` | No account session was presented, or it is invalid or expired. Refresh once, then re-authenticate. |
| `403` | The account is suspended or its email is not verified. |

## Operations — project API key

Call these from your own server with a project key. Never from a browser or a mobile bundle.

### GET `/v2/knowledge-bases`

List the project's knowledge bases with their documents, ready documents, characters and search.

| Detail | Value |
| --- | --- |
| Door | Project API key — `X-Api-Key: $DVAARIK_API_KEY` |
| Scope | `voice:read` |
| Operation | `listKnowledgeBases` |
| Success | `200` `KnowledgeBasePage` |

#### `KnowledgeBasePage`

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `data` | KnowledgeBaseInfo[] | yes |  |

#### `KnowledgeBaseInfo`

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `created_at` | date-time | yes |  |
| `description` | string or null | yes |  |
| `document_count` | integer | yes |  |
| `embedding_account_id` | uuid or null | yes |  |
| `id` | uuid | yes |  |
| `name` | string | yes |  |
| `ready_chars` | integer | no | default 0 |
| `ready_count` | integer | yes |  |
| `revision` | integer | yes |  |
| `search` | "hybrid" or "keyword" | yes |  |
| `total_chars` | integer | yes |  |
| `updated_at` | date-time | yes |  |

#### `Unprocessable`

A 422 from a route that also refuses with a sentence: FastAPI's list of field errors when the body or query does not parse, or one sentence when it parsed and was refused.

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `detail` | string or ValidationErrorItem[] | yes | A sentence for the developer, or the list of fields that failed validation. |

| Error | When |
| --- | --- |
| `401` | No API key was sent in X-Api-Key, or it is invalid or revoked. |
| `403` | The API key lacks the scope this route needs, or its account or project is unavailable. |
| `422` | The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field. |
| `429` | The project's requests-per-minute limit is reached; Retry-After says when to try again. |

Plus the machine-door errors above. Full list on the [errors page](/docs/errors).

```bash
curl -sS -X GET "https://api.developers.dvaarik.com/v2/knowledge-bases" \
  -H "X-Api-Key: $DVAARIK_API_KEY"
```

### POST `/v2/knowledge-bases`

Make a knowledge base, at most 10 per project. Leave out `embedding_account_id` for keyword search, which needs no setup; name a verified Google or OpenAI account of this project for keyword + meaning search on it.

| Detail | Value |
| --- | --- |
| Door | Project API key — `X-Api-Key: $DVAARIK_API_KEY` |
| Scope | `voice:write` |
| Operation | `createKnowledgeBase` |
| Success | `201` `KnowledgeBaseInfo` |

Request body: `KnowledgeBaseCreate`.

#### `KnowledgeBaseCreate`

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `description` | string or null | no |  |
| `embedding_account_id` | uuid or null | no |  |
| `name` | string | yes |  |

| Error | When |
| --- | --- |
| `401` | No API key was sent in X-Api-Key, or it is invalid or revoked. |
| `403` | The API key lacks the scope this route needs, or its account or project is unavailable. |
| `409` | A limit or the resource's state refuses this change; the sentence says which. |
| `422` | The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field. |
| `429` | The project's requests-per-minute limit is reached; Retry-After says when to try again. |

Plus the machine-door errors above. Full list on the [errors page](/docs/errors).

```bash
curl -sS -X POST "https://api.developers.dvaarik.com/v2/knowledge-bases" \
  -H "X-Api-Key: $DVAARIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Prices and policies"
  }'
```

### DELETE `/v2/knowledge-bases/{base_id}`

Delete the base with its documents and passages. Every agent that read it gets a new version.

| Detail | Value |
| --- | --- |
| Door | Project API key — `X-Api-Key: $DVAARIK_API_KEY` |
| Scope | `voice:write` |
| Operation | `deleteKnowledgeBase` |
| Success | `204` `no body` |

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `base_id` | path | uuid | yes |  |

| Error | When |
| --- | --- |
| `401` | No API key was sent in X-Api-Key, or it is invalid or revoked. |
| `403` | The API key lacks the scope this route needs, or its account or project is unavailable. |
| `404` | The addressed resource does not exist in this key's project. One in another project is deliberately indistinguishable from one that never existed. |
| `422` | The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field. |
| `429` | The project's requests-per-minute limit is reached; Retry-After says when to try again. |

Plus the machine-door errors above. Full list on the [errors page](/docs/errors).

```bash
curl -sS -X DELETE "https://api.developers.dvaarik.com/v2/knowledge-bases/$BASE_ID" \
  -H "X-Api-Key: $DVAARIK_API_KEY"
```

### GET `/v2/knowledge-bases/{base_id}`

Read one knowledge base.

| Detail | Value |
| --- | --- |
| Door | Project API key — `X-Api-Key: $DVAARIK_API_KEY` |
| Scope | `voice:read` |
| Operation | `getKnowledgeBase` |
| Success | `200` `KnowledgeBaseInfo` |

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `base_id` | path | uuid | yes |  |

| Error | When |
| --- | --- |
| `401` | No API key was sent in X-Api-Key, or it is invalid or revoked. |
| `403` | The API key lacks the scope this route needs, or its account or project is unavailable. |
| `404` | The addressed resource does not exist in this key's project. One in another project is deliberately indistinguishable from one that never existed. |
| `422` | The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field. |
| `429` | The project's requests-per-minute limit is reached; Retry-After says when to try again. |

Plus the machine-door errors above. Full list on the [errors page](/docs/errors).

```bash
curl -sS -X GET "https://api.developers.dvaarik.com/v2/knowledge-bases/$BASE_ID" \
  -H "X-Api-Key: $DVAARIK_API_KEY"
```

### PATCH `/v2/knowledge-bases/{base_id}`

Rename it or change its search. Only the fields you send change. The same `embedding_account_id` again retries what is not fully indexed; another account, or `null`, reads every document again.

| Detail | Value |
| --- | --- |
| Door | Project API key — `X-Api-Key: $DVAARIK_API_KEY` |
| Scope | `voice:write` |
| Operation | `updateKnowledgeBase` |
| Success | `200` `KnowledgeBaseInfo` |

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `base_id` | path | uuid | yes |  |

Request body: `KnowledgeBaseUpdate`.

#### `KnowledgeBaseUpdate`

Fields left out stay as they are; `embedding_account_id: null` turns meaning-based search off. Saving the SAME `embedding_account_id` again re-indexes every document that is not fully embedded (the retry after a provider failure); an account with the same provider re-embeds nothing that already has vectors; any other change re-indexes every document.

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `description` | string or null | no |  |
| `embedding_account_id` | uuid or null | no |  |
| `name` | string or null | no |  |

| Error | When |
| --- | --- |
| `401` | No API key was sent in X-Api-Key, or it is invalid or revoked. |
| `403` | The API key lacks the scope this route needs, or its account or project is unavailable. |
| `404` | The addressed resource does not exist in this key's project. One in another project is deliberately indistinguishable from one that never existed. |
| `409` | A limit or the resource's state refuses this change; the sentence says which. |
| `422` | The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field. |
| `429` | The project's requests-per-minute limit is reached; Retry-After says when to try again. |

Plus the machine-door errors above. Full list on the [errors page](/docs/errors).

```bash
curl -sS -X PATCH "https://api.developers.dvaarik.com/v2/knowledge-bases/$BASE_ID" \
  -H "X-Api-Key: $DVAARIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "embedding_account_id": "<verified google or openai provider account uuid>"
  }'
```

### GET `/v2/knowledge-bases/{base_id}/documents`

List the base's documents with status, size and error. Ask again until each is `ready` or `failed`.

| Detail | Value |
| --- | --- |
| Door | Project API key — `X-Api-Key: $DVAARIK_API_KEY` |
| Scope | `voice:read` |
| Operation | `listKnowledgeDocuments` |
| Success | `200` `KnowledgeDocumentPage` |

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `base_id` | path | uuid | yes |  |

#### `KnowledgeDocumentPage`

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `data` | KnowledgeDocumentInfo[] | yes |  |

#### `KnowledgeDocumentInfo`

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `base_id` | uuid | yes |  |
| `chunk_count` | integer | yes |  |
| `content_chars` | integer | yes |  |
| `created_at` | date-time | yes |  |
| `embedded` | boolean | yes |  |
| `error` | string or null | yes |  |
| `id` | uuid | yes |  |
| `indexed_version` | integer or null | yes |  |
| `kind` | string | yes |  |
| `name` | string | yes |  |
| `status` | "queued" or "indexing" or "ready" or "failed" | yes |  |
| `updated_at` | date-time | yes |  |
| `version` | integer | yes |  |

| Error | When |
| --- | --- |
| `401` | No API key was sent in X-Api-Key, or it is invalid or revoked. |
| `403` | The API key lacks the scope this route needs, or its account or project is unavailable. |
| `404` | The addressed resource does not exist in this key's project. One in another project is deliberately indistinguishable from one that never existed. |
| `422` | The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field. |
| `429` | The project's requests-per-minute limit is reached; Retry-After says when to try again. |

Plus the machine-door errors above. Full list on the [errors page](/docs/errors).

```bash
curl -sS -X GET "https://api.developers.dvaarik.com/v2/knowledge-bases/$BASE_ID/documents" \
  -H "X-Api-Key: $DVAARIK_API_KEY"
```

### POST `/v2/knowledge-bases/{base_id}/documents`

Add a document, at most 50 per base. It is saved `queued` and read in the background; agents use it once it is `ready`.

| Detail | Value |
| --- | --- |
| Door | Project API key — `X-Api-Key: $DVAARIK_API_KEY` |
| Scope | `voice:write` |
| Operation | `createKnowledgeDocument` |
| Success | `201` `KnowledgeDocumentInfo` |

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `base_id` | path | uuid | yes |  |
| `name` | query | string | yes | The document's name, 1 to 200 characters. A raw upload (text/markdown, text/plain or application/pdf body) is named only by this and is refused without it. A JSON body carries its own `name`, which is the one used; this parameter is not read for JSON. |

Request body: `KnowledgeDocumentCreate`.

#### `KnowledgeDocumentCreate`

A document as JSON. Raw uploads send the text itself as the body instead.

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `content` | string | yes | min length 1; max length 500000 |
| `kind` | "markdown" or "text" | no | default "markdown" |
| `name` | string | yes |  |

| Error | When |
| --- | --- |
| `401` | No API key was sent in X-Api-Key, or it is invalid or revoked. |
| `403` | The API key lacks the scope this route needs, or its account or project is unavailable. |
| `404` | The addressed resource does not exist in this key's project. One in another project is deliberately indistinguishable from one that never existed. |
| `409` | A limit or the resource's state refuses this change; the sentence says which. |
| `413` | The request body is larger than this route accepts; the sentence names the limit. |
| `415` | This route does not read that Content-Type; the sentence names the ones it does. |
| `422` | The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field. |
| `429` | The project's requests-per-minute limit is reached; Retry-After says when to try again. |
| `503` | A bounded worker this request needs is busy; Retry-After says when to try again. |

Plus the machine-door errors above. Full list on the [errors page](/docs/errors).

```bash
curl -sS -X POST "https://api.developers.dvaarik.com/v2/knowledge-bases/$BASE_ID/documents?name=<name>" \
  -H "X-Api-Key: $DVAARIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "<content>",
    "name": "<name>"
  }'
```

### DELETE `/v2/knowledge-bases/{base_id}/documents/{document_id}`

Delete a document and its passages. Agents stop using it at once.

| Detail | Value |
| --- | --- |
| Door | Project API key — `X-Api-Key: $DVAARIK_API_KEY` |
| Scope | `voice:write` |
| Operation | `deleteKnowledgeDocument` |
| Success | `204` `no body` |

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `base_id` | path | uuid | yes |  |
| `document_id` | path | uuid | yes |  |

| Error | When |
| --- | --- |
| `401` | No API key was sent in X-Api-Key, or it is invalid or revoked. |
| `403` | The API key lacks the scope this route needs, or its account or project is unavailable. |
| `404` | The addressed resource does not exist in this key's project. One in another project is deliberately indistinguishable from one that never existed. |
| `422` | The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field. |
| `429` | The project's requests-per-minute limit is reached; Retry-After says when to try again. |

Plus the machine-door errors above. Full list on the [errors page](/docs/errors).

```bash
curl -sS -X DELETE "https://api.developers.dvaarik.com/v2/knowledge-bases/$BASE_ID/documents/$DOCUMENT_ID" \
  -H "X-Api-Key: $DVAARIK_API_KEY"
```

### GET `/v2/knowledge-bases/{base_id}/documents/{document_id}`

Read one document, with the text of its latest upload.

| Detail | Value |
| --- | --- |
| Door | Project API key — `X-Api-Key: $DVAARIK_API_KEY` |
| Scope | `voice:read` |
| Operation | `getKnowledgeDocument` |
| Success | `200` `KnowledgeDocumentDetail` |

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `base_id` | path | uuid | yes |  |
| `document_id` | path | uuid | yes |  |

#### `KnowledgeDocumentDetail`

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `base_id` | uuid | yes |  |
| `chunk_count` | integer | yes |  |
| `content` | string | yes |  |
| `content_chars` | integer | yes |  |
| `created_at` | date-time | yes |  |
| `embedded` | boolean | yes |  |
| `error` | string or null | yes |  |
| `id` | uuid | yes |  |
| `indexed_version` | integer or null | yes |  |
| `kind` | string | yes |  |
| `name` | string | yes |  |
| `status` | "queued" or "indexing" or "ready" or "failed" | yes |  |
| `updated_at` | date-time | yes |  |
| `version` | integer | yes |  |

| Error | When |
| --- | --- |
| `401` | No API key was sent in X-Api-Key, or it is invalid or revoked. |
| `403` | The API key lacks the scope this route needs, or its account or project is unavailable. |
| `404` | The addressed resource does not exist in this key's project. One in another project is deliberately indistinguishable from one that never existed. |
| `422` | The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field. |
| `429` | The project's requests-per-minute limit is reached; Retry-After says when to try again. |

Plus the machine-door errors above. Full list on the [errors page](/docs/errors).

```bash
curl -sS -X GET "https://api.developers.dvaarik.com/v2/knowledge-bases/$BASE_ID/documents/$DOCUMENT_ID" \
  -H "X-Api-Key: $DVAARIK_API_KEY"
```

### PUT `/v2/knowledge-bases/{base_id}/documents/{document_id}`

Replace a document's text. The previous version keeps answering until the new one is ready.

| Detail | Value |
| --- | --- |
| Door | Project API key — `X-Api-Key: $DVAARIK_API_KEY` |
| Scope | `voice:write` |
| Operation | `replaceKnowledgeDocument` |
| Success | `200` `KnowledgeDocumentInfo` |

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `base_id` | path | uuid | yes |  |
| `document_id` | path | uuid | yes |  |
| `name` | query | string | yes | The document's name, 1 to 200 characters. A raw upload (text/markdown, text/plain or application/pdf body) is named only by this and is refused without it. A JSON body carries its own `name`, which is the one used; this parameter is not read for JSON. |

Request body: `KnowledgeDocumentCreate`.

| Error | When |
| --- | --- |
| `401` | No API key was sent in X-Api-Key, or it is invalid or revoked. |
| `403` | The API key lacks the scope this route needs, or its account or project is unavailable. |
| `404` | The addressed resource does not exist in this key's project. One in another project is deliberately indistinguishable from one that never existed. |
| `409` | A limit or the resource's state refuses this change; the sentence says which. |
| `413` | The request body is larger than this route accepts; the sentence names the limit. |
| `415` | This route does not read that Content-Type; the sentence names the ones it does. |
| `422` | The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field. |
| `429` | The project's requests-per-minute limit is reached; Retry-After says when to try again. |
| `503` | A bounded worker this request needs is busy; Retry-After says when to try again. |

Plus the machine-door errors above. Full list on the [errors page](/docs/errors).

```bash
curl -sS -X PUT "https://api.developers.dvaarik.com/v2/knowledge-bases/$BASE_ID/documents/$DOCUMENT_ID?name=<name>" \
  -H "X-Api-Key: $DVAARIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "<content>",
    "name": "<name>"
  }'
```

### POST `/v2/knowledge-bases/{base_id}/reindex`

Queue every document that is not fully indexed again (`202`): the retry after a provider failure. Vectors already made are reused, not bought twice.

| Detail | Value |
| --- | --- |
| Door | Project API key — `X-Api-Key: $DVAARIK_API_KEY` |
| Scope | `voice:write` |
| Operation | `reindexKnowledgeBase` |
| Success | `202` `KnowledgeReindexResult` |

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `base_id` | path | uuid | yes |  |

#### `KnowledgeReindexResult`

What `POST .../reindex` queued. Poll the documents until each is `ready` or `failed`.

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `queued` | integer | yes |  |

| Error | When |
| --- | --- |
| `401` | No API key was sent in X-Api-Key, or it is invalid or revoked. |
| `403` | The API key lacks the scope this route needs, or its account or project is unavailable. |
| `404` | The addressed resource does not exist in this key's project. One in another project is deliberately indistinguishable from one that never existed. |
| `422` | The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field. |
| `429` | The project's requests-per-minute limit is reached; Retry-After says when to try again. |

Plus the machine-door errors above. Full list on the [errors page](/docs/errors).

```bash
curl -sS -X POST "https://api.developers.dvaarik.com/v2/knowledge-bases/$BASE_ID/reindex" \
  -H "X-Api-Key: $DVAARIK_API_KEY"
```

### POST `/v2/knowledge-bases/{base_id}/search`

Try a question: exactly the passages an agent's `search_knowledge` tool gets on a call, with the mode used and the time taken.

| Detail | Value |
| --- | --- |
| Door | Project API key — `X-Api-Key: $DVAARIK_API_KEY` |
| Scope | `voice:read` |
| Operation | `searchKnowledgeBase` |
| Success | `200` `KnowledgeSearchResult` |

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `base_id` | path | uuid | yes |  |

Request body: `KnowledgeSearchRequest`.

#### `KnowledgeSearchRequest`

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `query` | string | yes | min length 2; max length 500 |

#### `KnowledgeSearchResult`

Exactly what an agent's `search_knowledge` tool receives for this question, plus timing.

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `elapsed_ms` | integer | yes |  |
| `mode` | "hybrid" or "keyword" | yes |  |
| `passages` | KnowledgePassage[] | yes |  |
| `status` | "ok" or "no_match" or "unavailable" | yes |  |

#### `KnowledgePassage`

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `document` | string | yes |  |
| `section` | string | yes |  |
| `text` | string | yes |  |

| Error | When |
| --- | --- |
| `401` | No API key was sent in X-Api-Key, or it is invalid or revoked. |
| `403` | The API key lacks the scope this route needs, or its account or project is unavailable. |
| `404` | The addressed resource does not exist in this key's project. One in another project is deliberately indistinguishable from one that never existed. |
| `422` | The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field. |
| `429` | The project's requests-per-minute limit is reached; Retry-After says when to try again. |

Plus the machine-door errors above. Full list on the [errors page](/docs/errors).

```bash
curl -sS -X POST "https://api.developers.dvaarik.com/v2/knowledge-bases/$BASE_ID/search" \
  -H "X-Api-Key: $DVAARIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What time do you open on Saturday?"
  }'
```

## Operations — account session

The same resource through the console door. These are what the web console calls; both doors return the same shapes.

### GET `/console/v2/projects/{project_id}/knowledge-bases`

List the project's knowledge bases with their documents, ready documents, characters and search.

| Detail | Value |
| --- | --- |
| Door | Account session — `Authorization: Bearer $DVAARIK_TOKEN` |
| Operation | `consoleListKnowledgeBases` |
| Success | `200` `KnowledgeBasePage` |

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `project_id` | path | uuid | yes |  |

| Error | When |
| --- | --- |
| `401` | No account session was presented, or it is invalid or expired. |
| `403` | The account is suspended or its email is not verified. |
| `404` | The project or the addressed resource does not exist for this owner. A resource owned by another developer is deliberately indistinguishable from one that never existed. |
| `422` | The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field. |

Plus the account-door errors above. Full list on the [errors page](/docs/errors).

```bash
curl -sS -X GET "https://api.developers.dvaarik.com/console/v2/projects/$PROJECT_ID/knowledge-bases" \
  -H "Authorization: Bearer $DVAARIK_TOKEN"
```

### POST `/console/v2/projects/{project_id}/knowledge-bases`

Make a knowledge base, at most 10 per project. Leave out `embedding_account_id` for keyword search, which needs no setup; name a verified Google or OpenAI account of this project for keyword + meaning search on it.

| Detail | Value |
| --- | --- |
| Door | Account session — `Authorization: Bearer $DVAARIK_TOKEN` |
| Operation | `consoleCreateKnowledgeBase` |
| Success | `201` `KnowledgeBaseInfo` |

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `project_id` | path | uuid | yes |  |

Request body: `KnowledgeBaseCreate`.

| Error | When |
| --- | --- |
| `401` | No account session was presented, or it is invalid or expired. |
| `403` | The account is suspended or its email is not verified. |
| `404` | The project or the addressed resource does not exist for this owner. A resource owned by another developer is deliberately indistinguishable from one that never existed. |
| `409` | The project or resource is in a state that refuses this change. |
| `422` | The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field. |

Plus the account-door errors above. Full list on the [errors page](/docs/errors).

```bash
curl -sS -X POST "https://api.developers.dvaarik.com/console/v2/projects/$PROJECT_ID/knowledge-bases" \
  -H "Authorization: Bearer $DVAARIK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Prices and policies"
  }'
```

### DELETE `/console/v2/projects/{project_id}/knowledge-bases/{base_id}`

Delete the base with its documents and passages. Every agent that read it gets a new version.

| Detail | Value |
| --- | --- |
| Door | Account session — `Authorization: Bearer $DVAARIK_TOKEN` |
| Operation | `consoleDeleteKnowledgeBase` |
| Success | `204` `no body` |

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `base_id` | path | uuid | yes |  |
| `project_id` | path | uuid | yes |  |

| Error | When |
| --- | --- |
| `401` | No account session was presented, or it is invalid or expired. |
| `403` | The account is suspended or its email is not verified. |
| `404` | The project or the addressed resource does not exist for this owner. A resource owned by another developer is deliberately indistinguishable from one that never existed. |
| `409` | The project or resource is in a state that refuses this change. |
| `422` | The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field. |

Plus the account-door errors above. Full list on the [errors page](/docs/errors).

```bash
curl -sS -X DELETE "https://api.developers.dvaarik.com/console/v2/projects/$PROJECT_ID/knowledge-bases/$BASE_ID" \
  -H "Authorization: Bearer $DVAARIK_TOKEN"
```

### GET `/console/v2/projects/{project_id}/knowledge-bases/{base_id}`

Read one knowledge base.

| Detail | Value |
| --- | --- |
| Door | Account session — `Authorization: Bearer $DVAARIK_TOKEN` |
| Operation | `consoleGetKnowledgeBase` |
| Success | `200` `KnowledgeBaseInfo` |

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `base_id` | path | uuid | yes |  |
| `project_id` | path | uuid | yes |  |

| Error | When |
| --- | --- |
| `401` | No account session was presented, or it is invalid or expired. |
| `403` | The account is suspended or its email is not verified. |
| `404` | The project or the addressed resource does not exist for this owner. A resource owned by another developer is deliberately indistinguishable from one that never existed. |
| `422` | The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field. |

Plus the account-door errors above. Full list on the [errors page](/docs/errors).

```bash
curl -sS -X GET "https://api.developers.dvaarik.com/console/v2/projects/$PROJECT_ID/knowledge-bases/$BASE_ID" \
  -H "Authorization: Bearer $DVAARIK_TOKEN"
```

### PATCH `/console/v2/projects/{project_id}/knowledge-bases/{base_id}`

Rename it or change its search. Only the fields you send change. The same `embedding_account_id` again retries what is not fully indexed; another account, or `null`, reads every document again.

| Detail | Value |
| --- | --- |
| Door | Account session — `Authorization: Bearer $DVAARIK_TOKEN` |
| Operation | `consoleUpdateKnowledgeBase` |
| Success | `200` `KnowledgeBaseInfo` |

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `base_id` | path | uuid | yes |  |
| `project_id` | path | uuid | yes |  |

Request body: `KnowledgeBaseUpdate`.

| Error | When |
| --- | --- |
| `401` | No account session was presented, or it is invalid or expired. |
| `403` | The account is suspended or its email is not verified. |
| `404` | The project or the addressed resource does not exist for this owner. A resource owned by another developer is deliberately indistinguishable from one that never existed. |
| `409` | The project or resource is in a state that refuses this change. |
| `422` | The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field. |

Plus the account-door errors above. Full list on the [errors page](/docs/errors).

```bash
curl -sS -X PATCH "https://api.developers.dvaarik.com/console/v2/projects/$PROJECT_ID/knowledge-bases/$BASE_ID" \
  -H "Authorization: Bearer $DVAARIK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "embedding_account_id": "<verified google or openai provider account uuid>"
  }'
```

### GET `/console/v2/projects/{project_id}/knowledge-bases/{base_id}/documents`

List the base's documents with status, size and error. Ask again until each is `ready` or `failed`.

| Detail | Value |
| --- | --- |
| Door | Account session — `Authorization: Bearer $DVAARIK_TOKEN` |
| Operation | `consoleListKnowledgeDocuments` |
| Success | `200` `KnowledgeDocumentPage` |

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `base_id` | path | uuid | yes |  |
| `project_id` | path | uuid | yes |  |

| Error | When |
| --- | --- |
| `401` | No account session was presented, or it is invalid or expired. |
| `403` | The account is suspended or its email is not verified. |
| `404` | The project or the addressed resource does not exist for this owner. A resource owned by another developer is deliberately indistinguishable from one that never existed. |
| `422` | The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field. |

Plus the account-door errors above. Full list on the [errors page](/docs/errors).

```bash
curl -sS -X GET "https://api.developers.dvaarik.com/console/v2/projects/$PROJECT_ID/knowledge-bases/$BASE_ID/documents" \
  -H "Authorization: Bearer $DVAARIK_TOKEN"
```

### POST `/console/v2/projects/{project_id}/knowledge-bases/{base_id}/documents`

Add a document, at most 50 per base. It is saved `queued` and read in the background; agents use it once it is `ready`.

| Detail | Value |
| --- | --- |
| Door | Account session — `Authorization: Bearer $DVAARIK_TOKEN` |
| Operation | `consoleCreateKnowledgeDocument` |
| Success | `201` `KnowledgeDocumentInfo` |

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `base_id` | path | uuid | yes |  |
| `project_id` | path | uuid | yes |  |
| `name` | query | string | yes | The document's name, 1 to 200 characters. A raw upload (text/markdown, text/plain or application/pdf body) is named only by this and is refused without it. A JSON body carries its own `name`, which is the one used; this parameter is not read for JSON. |

Request body: `KnowledgeDocumentCreate`.

| Error | When |
| --- | --- |
| `401` | No account session was presented, or it is invalid or expired. |
| `403` | The account is suspended or its email is not verified. |
| `404` | The project or the addressed resource does not exist for this owner. A resource owned by another developer is deliberately indistinguishable from one that never existed. |
| `409` | The project or resource is in a state that refuses this change. |
| `413` | The request body is larger than this route accepts; the sentence names the limit. |
| `415` | This route does not read that Content-Type; the sentence names the ones it does. |
| `422` | The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field. |
| `503` | A bounded worker this request needs is busy; Retry-After says when to try again. |

Plus the account-door errors above. Full list on the [errors page](/docs/errors).

```bash
curl -sS -X POST "https://api.developers.dvaarik.com/console/v2/projects/$PROJECT_ID/knowledge-bases/$BASE_ID/documents?name=<name>" \
  -H "Authorization: Bearer $DVAARIK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "<content>",
    "name": "<name>"
  }'
```

### DELETE `/console/v2/projects/{project_id}/knowledge-bases/{base_id}/documents/{document_id}`

Delete a document and its passages. Agents stop using it at once.

| Detail | Value |
| --- | --- |
| Door | Account session — `Authorization: Bearer $DVAARIK_TOKEN` |
| Operation | `consoleDeleteKnowledgeDocument` |
| Success | `204` `no body` |

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `base_id` | path | uuid | yes |  |
| `document_id` | path | uuid | yes |  |
| `project_id` | path | uuid | yes |  |

| Error | When |
| --- | --- |
| `401` | No account session was presented, or it is invalid or expired. |
| `403` | The account is suspended or its email is not verified. |
| `404` | The project or the addressed resource does not exist for this owner. A resource owned by another developer is deliberately indistinguishable from one that never existed. |
| `409` | The project or resource is in a state that refuses this change. |
| `422` | The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field. |

Plus the account-door errors above. Full list on the [errors page](/docs/errors).

```bash
curl -sS -X DELETE "https://api.developers.dvaarik.com/console/v2/projects/$PROJECT_ID/knowledge-bases/$BASE_ID/documents/$DOCUMENT_ID" \
  -H "Authorization: Bearer $DVAARIK_TOKEN"
```

### GET `/console/v2/projects/{project_id}/knowledge-bases/{base_id}/documents/{document_id}`

Read one document, with the text of its latest upload.

| Detail | Value |
| --- | --- |
| Door | Account session — `Authorization: Bearer $DVAARIK_TOKEN` |
| Operation | `consoleGetKnowledgeDocument` |
| Success | `200` `KnowledgeDocumentDetail` |

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `base_id` | path | uuid | yes |  |
| `document_id` | path | uuid | yes |  |
| `project_id` | path | uuid | yes |  |

| Error | When |
| --- | --- |
| `401` | No account session was presented, or it is invalid or expired. |
| `403` | The account is suspended or its email is not verified. |
| `404` | The project or the addressed resource does not exist for this owner. A resource owned by another developer is deliberately indistinguishable from one that never existed. |
| `422` | The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field. |

Plus the account-door errors above. Full list on the [errors page](/docs/errors).

```bash
curl -sS -X GET "https://api.developers.dvaarik.com/console/v2/projects/$PROJECT_ID/knowledge-bases/$BASE_ID/documents/$DOCUMENT_ID" \
  -H "Authorization: Bearer $DVAARIK_TOKEN"
```

### PUT `/console/v2/projects/{project_id}/knowledge-bases/{base_id}/documents/{document_id}`

Replace a document's text. The previous version keeps answering until the new one is ready.

| Detail | Value |
| --- | --- |
| Door | Account session — `Authorization: Bearer $DVAARIK_TOKEN` |
| Operation | `consoleReplaceKnowledgeDocument` |
| Success | `200` `KnowledgeDocumentInfo` |

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `base_id` | path | uuid | yes |  |
| `document_id` | path | uuid | yes |  |
| `project_id` | path | uuid | yes |  |
| `name` | query | string | yes | The document's name, 1 to 200 characters. A raw upload (text/markdown, text/plain or application/pdf body) is named only by this and is refused without it. A JSON body carries its own `name`, which is the one used; this parameter is not read for JSON. |

Request body: `KnowledgeDocumentCreate`.

| Error | When |
| --- | --- |
| `401` | No account session was presented, or it is invalid or expired. |
| `403` | The account is suspended or its email is not verified. |
| `404` | The project or the addressed resource does not exist for this owner. A resource owned by another developer is deliberately indistinguishable from one that never existed. |
| `409` | The project or resource is in a state that refuses this change. |
| `413` | The request body is larger than this route accepts; the sentence names the limit. |
| `415` | This route does not read that Content-Type; the sentence names the ones it does. |
| `422` | The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field. |
| `503` | A bounded worker this request needs is busy; Retry-After says when to try again. |

Plus the account-door errors above. Full list on the [errors page](/docs/errors).

```bash
curl -sS -X PUT "https://api.developers.dvaarik.com/console/v2/projects/$PROJECT_ID/knowledge-bases/$BASE_ID/documents/$DOCUMENT_ID?name=<name>" \
  -H "Authorization: Bearer $DVAARIK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "<content>",
    "name": "<name>"
  }'
```

### POST `/console/v2/projects/{project_id}/knowledge-bases/{base_id}/reindex`

Queue every document that is not fully indexed again (`202`): the retry after a provider failure. Vectors already made are reused, not bought twice.

| Detail | Value |
| --- | --- |
| Door | Account session — `Authorization: Bearer $DVAARIK_TOKEN` |
| Operation | `consoleReindexKnowledgeBase` |
| Success | `202` `KnowledgeReindexResult` |

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `base_id` | path | uuid | yes |  |
| `project_id` | path | uuid | yes |  |

| Error | When |
| --- | --- |
| `401` | No account session was presented, or it is invalid or expired. |
| `403` | The account is suspended or its email is not verified. |
| `404` | The project or the addressed resource does not exist for this owner. A resource owned by another developer is deliberately indistinguishable from one that never existed. |
| `409` | The project or resource is in a state that refuses this change. |
| `422` | The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field. |

Plus the account-door errors above. Full list on the [errors page](/docs/errors).

```bash
curl -sS -X POST "https://api.developers.dvaarik.com/console/v2/projects/$PROJECT_ID/knowledge-bases/$BASE_ID/reindex" \
  -H "Authorization: Bearer $DVAARIK_TOKEN"
```

### POST `/console/v2/projects/{project_id}/knowledge-bases/{base_id}/search`

Try a question: exactly the passages an agent's `search_knowledge` tool gets on a call, with the mode used and the time taken.

| Detail | Value |
| --- | --- |
| Door | Account session — `Authorization: Bearer $DVAARIK_TOKEN` |
| Operation | `consoleSearchKnowledgeBase` |
| Success | `200` `KnowledgeSearchResult` |

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `base_id` | path | uuid | yes |  |
| `project_id` | path | uuid | yes |  |

Request body: `KnowledgeSearchRequest`.

| Error | When |
| --- | --- |
| `401` | No account session was presented, or it is invalid or expired. |
| `403` | The account is suspended or its email is not verified. |
| `404` | The project or the addressed resource does not exist for this owner. A resource owned by another developer is deliberately indistinguishable from one that never existed. |
| `422` | The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field. |

Plus the account-door errors above. Full list on the [errors page](/docs/errors).

```bash
curl -sS -X POST "https://api.developers.dvaarik.com/console/v2/projects/$PROJECT_ID/knowledge-bases/$BASE_ID/search" \
  -H "Authorization: Bearer $DVAARIK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What time do you open on Saturday?"
  }'
```

---

Source: https://developers.dvaarik.com/docs/api/knowledge-bases · every page as one file: https://developers.dvaarik.com/docs.md