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

# Knowledge Bases

> Create and manage knowledge bases, their prompt settings, external A2A agents, and memory.

A knowledge base groups the documents, prompt configuration, and agents that answer questions for a tenant. All endpoints are served under `/knowledge-bases` and accept either an API key or a user session.

<Note>
  All endpoints on this page are **\[User+Key]** — call them with `Authorization: Bearer sk_...` or a signed-in session.
</Note>

## Endpoints

| Method   | Path                                       | Description                        | Auth        |
| -------- | ------------------------------------------ | ---------------------------------- | ----------- |
| `GET`    | `/knowledge-bases`                         | List knowledge bases for a tenant  | \[User+Key] |
| `GET`    | `/knowledge-bases/:id`                     | Get a knowledge base               | \[User+Key] |
| `GET`    | `/knowledge-bases/:id/prompt`              | Get prompt settings                | \[User+Key] |
| `POST`   | `/knowledge-bases`                         | Create a knowledge base            | \[User+Key] |
| `PATCH`  | `/knowledge-bases/:id`                     | Update a knowledge base            | \[User+Key] |
| `DELETE` | `/knowledge-bases/:id`                     | Delete a knowledge base            | \[User+Key] |
| `GET`    | `/knowledge-bases/:id/a2a-agents`          | List registered external agents    | \[User+Key] |
| `POST`   | `/knowledge-bases/:id/a2a-agents`          | Register an external agent         | \[User+Key] |
| `GET`    | `/knowledge-bases/:id/a2a-agents/:agentId` | Get a registered external agent    | \[User+Key] |
| `PATCH`  | `/knowledge-bases/:id/a2a-agents/:agentId` | Update a registered external agent | \[User+Key] |
| `DELETE` | `/knowledge-bases/:id/a2a-agents/:agentId` | Remove a registered external agent | \[User+Key] |
| `GET`    | `/knowledge-bases/:id/memories`            | List knowledge base memories       | \[User+Key] |
| `GET`    | `/knowledge-bases/:id/memories/graph`      | Get the memory graph               | \[User+Key] |
| `DELETE` | `/knowledge-bases/:id/memories/:memoryId`  | Delete a memory                    | \[User+Key] |

## List knowledge bases

`GET /knowledge-bases`

Returns the knowledge bases in a tenant.

<ParamField query="tenant_id" type="string" required>
  The tenant whose knowledge bases to list.
</ParamField>

```bash theme={null}
curl "https://api.autosage.ai/api/v1/knowledge-bases?tenant_id=TENANT_ID" \
  -H "Authorization: Bearer sk_live_your_key_here"
```

## Get a knowledge base

`GET /knowledge-bases/:id`

Returns a single knowledge base, including its name, description, status, and memory mode.

```bash theme={null}
curl "https://api.autosage.ai/api/v1/knowledge-bases/KB_ID" \
  -H "Authorization: Bearer sk_live_your_key_here"
```

## Get prompt settings

`GET /knowledge-bases/:id/prompt`

Returns the prompt configuration that shapes how answers are generated: `persona`, `instructions`, `customPrompt`, `mainCustomPrompt`, `sqlCustomPrompt`, `sqlAgentInstructions`, `sqlAnsweringInstructions`, and `chartInstructions`. See [Prompts](/knowledge-bases/prompts) for how these combine.

```bash theme={null}
curl "https://api.autosage.ai/api/v1/knowledge-bases/KB_ID/prompt" \
  -H "Authorization: Bearer sk_live_your_key_here"
```

## Create a knowledge base

`POST /knowledge-bases`

Creates a knowledge base in a tenant. Creation is subject to the tenant's knowledge base quota.

<ParamField body="tenant_id" type="string" required>
  The tenant that will own the knowledge base.
</ParamField>

<ParamField body="name" type="string" required>
  Human-readable name.
</ParamField>

<ParamField body="description" type="string">
  Short description of the content.
</ParamField>

<ParamField body="persona" type="string">
  Optional prompt field describing the assistant's voice and role.
</ParamField>

<ParamField body="instructions" type="string">
  Optional additional answering instructions.
</ParamField>

<ParamField body="customPrompt" type="string">
  Optional prompt override. See [Prompts](/knowledge-bases/prompts) for precedence.
</ParamField>

<ParamField body="mainCustomPrompt" type="string">
  Optional full prompt override for Deep mode.
</ParamField>

Creation also accepts `sqlCustomPrompt`, `sqlAgentInstructions`, `sqlAnsweringInstructions`, and `chartInstructions` for connected-data behavior. Use `/swagger` for their complete constraints.

```bash theme={null}
curl -X POST "https://api.autosage.ai/api/v1/knowledge-bases" \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "TENANT_ID",
    "name": "Support docs",
    "description": "Product help center content"
  }'
```

## Update a knowledge base

`PATCH /knowledge-bases/:id`

Updates metadata, status, memory behavior, agent sharing, and prompt fields. Send only the fields you want to change.

<ParamField body="name" type="string">
  Human-readable name.
</ParamField>

<ParamField body="description" type="string">
  Short description of the content.
</ParamField>

<ParamField body="status" type="string">
  Lifecycle status of the knowledge base.
</ParamField>

<ParamField body="kbMemoryMode" type="string">
  One of `disabled`, `subject`, or `kb_restricted`. Controls how durable memory is scoped. See [Memory modes](/knowledge-bases/memory-modes).
</ParamField>

<ParamField body="agent_sharing" type="object">
  Agent sharing configuration, e.g. `{ "inbound_delegation_enabled": true }`. See [Agent sharing](/knowledge-bases/agent-sharing).
</ParamField>

<ParamField body="persona" type="string">
  Prompt persona field.
</ParamField>

<ParamField body="instructions" type="string">
  Additional answering instructions.
</ParamField>

<ParamField body="customPrompt" type="string">
  Prompt override field.
</ParamField>

<ParamField body="mainCustomPrompt" type="string">
  Deep-mode prompt override field.
</ParamField>

The connected-data prompt fields accepted during creation can also be updated here. Send `null` to clear a nullable prompt field.

```bash theme={null}
curl -X PATCH "https://api.autosage.ai/api/v1/knowledge-bases/KB_ID" \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated help center content",
    "kbMemoryMode": "kb_restricted"
  }'
```

## Delete a knowledge base

`DELETE /knowledge-bases/:id`

Deletes the knowledge base. This removes its documents and associated data, and archives any agents built on it.

<Warning>
  Deletion is destructive and cannot be undone. Documents and derived data are removed, and dependent agents are archived.
</Warning>

```bash theme={null}
curl -X DELETE "https://api.autosage.ai/api/v1/knowledge-bases/KB_ID" \
  -H "Authorization: Bearer sk_live_your_key_here"
```

## External (A2A) agents

Register external agents so agents in this knowledge base can delegate to them. This outbound delegation setup is independent of `agent_sharing`, which controls whether other knowledge bases can delegate into this one.

### List external agents

`GET /knowledge-bases/:id/a2a-agents`

```bash theme={null}
curl "https://api.autosage.ai/api/v1/knowledge-bases/KB_ID/a2a-agents" \
  -H "Authorization: Bearer sk_live_your_key_here"
```

### Register an external agent

`POST /knowledge-bases/:id/a2a-agents`

<ParamField body="name" type="string" required>
  Display name for the external agent.
</ParamField>

<ParamField body="cardUrl" type="string" required>
  URL of the external agent's capability card.
</ParamField>

<ParamField body="description" type="string">
  What the agent does.
</ParamField>

<ParamField body="headers" type="string">
  Optional serialized request-header configuration. Stored encrypted.
</ParamField>

<ParamField body="metadata" type="string">
  Optional serialized metadata attached to the registration. Stored encrypted.
</ParamField>

<Note>
  `headers` and `metadata` are stored encrypted at rest. Authorized reads return their decrypted values, so treat registration responses as sensitive.
</Note>

```bash theme={null}
curl -X POST "https://api.autosage.ai/api/v1/knowledge-bases/KB_ID/a2a-agents" \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Billing specialist",
    "cardUrl": "https://partner.example.com/agent-card.json",
    "description": "Answers billing and invoicing questions"
  }'
```

### Get, update, or remove an external agent

`GET`, `PATCH`, and `DELETE /knowledge-bases/:id/a2a-agents/:agentId` read, modify, and remove a single registration. `PATCH` accepts the same fields as registration; send only what changes.

## Memories

Knowledge base memory-management endpoints return isolated data only when `kbMemoryMode` is set to `kb_restricted`. See [Memory modes](/knowledge-bases/memory-modes).

### List memories

`GET /knowledge-bases/:id/memories`

Supports optional `limit`, `offset`, and `q` query parameters. Other memory modes return `memories: null` rather than tenant-wide memory.

```bash theme={null}
curl "https://api.autosage.ai/api/v1/knowledge-bases/KB_ID/memories" \
  -H "Authorization: Bearer sk_live_your_key_here"
```

### Get the memory graph

`GET /knowledge-bases/:id/memories/graph`

Returns memories as a graph of entities and relationships.

### Delete a memory

`DELETE /knowledge-bases/:id/memories/:memoryId`

Removes a single memory.

<Tip>
  Full request and response schemas for every field are available in the interactive explorer at `/swagger`.
</Tip>

## Next steps

<CardGroup cols={3}>
  <Card title="Knowledge bases" icon="database" href="/knowledge-bases/overview">
    What a knowledge base is and how to structure content.
  </Card>

  <Card title="Prompts" icon="pen" href="/knowledge-bases/prompts">
    Shape persona, instructions, and answering behavior.
  </Card>

  <Card title="RAG lifecycle" icon="diagram-project" href="/developers/lifecycles/rag">
    How retrieval and grounded answers work end to end.
  </Card>
</CardGroup>