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

# The Knowledge Context object

> Documents and notes that Lumos agents use, how product scopes decide which parts of Lumos read them, and how to write them as multipart form data.

A knowledge context, called an entry on this page, is one document or note that Lumos agents use
when they answer access questions. A security policy written in prose, an onboarding runbook, and a
note that explains why an app needs manager approval are each an entry.

Unlike the rest of v1, this object isn't a copy of something Lumos discovered in a connected app.
You write it. What agents learn from it depends on its `content` and on the `product_scopes` you
give it.

```json The Knowledge Context object theme={null}
{
  "id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
  "title": "Production database access policy",
  "content": "Access to production databases requires **manager approval** and expires after 8 hours.",
  "generic_tags": ["security", "databases"],
  "application_tags": [
    { "id": "2b3c4d5e-6f70-8901-bcde-f12345678901", "name": "Snowflake" }
  ],
  "product_scopes": ["appstore", "access-reviews"],
  "created_at": "2026-03-14T09:12:00Z",
  "updated_at": "2026-04-02T16:45:00Z"
}
```

## Attributes

| Field | Type | Description |
| - | - | - |
| `id` | string | Unique identifier for the entry. Always present. |
| `title` | string | Title of the entry. Always present, and unique within your organization. |
| `content` | string | Body text. Markdown is supported. |
| `file_url` | string | URL of the attached file, if the entry has one. |
| `generic_tags` | array | Freeform tag strings. Always present, possibly empty. |
| `application_tags` | array | App tags on the entry, each `{ id, name }`. Always present, possibly empty. |
| `product_scopes` | array | The parts of Lumos that can read this entry. See [Product scopes](#product-scopes). |
| `created_at` | string | ISO 8601 creation timestamp. |
| `updated_at` | string | ISO 8601 last-updated timestamp. |

[List Knowledge Context](https://docs.lumos.com/api-reference/v1/knowledge/list-knowledge-context.md) returns a field that
has no value as `null`. The other endpoints leave it out, so an entry without a file has no
`file_url`.

An entry needs either `content` or a file, but not both. Send `content` for prose, or attach a file
and omit `content`.

`application_tags` is read-only. The create and update bodies don't take it.

## Product scopes

`product_scopes` names the parts of Lumos that can read the entry. An entry scoped only to
`access-reviews` doesn't inform an AppStore request decision.

| Scope | Consumer |
| - | - |
| `appstore` | AppStore access requests. |
| `access-reviews` | Access Reviews. |
| `albus-chat` | The Albus agent. |
| `albus-deep-research` | Albus deep research. |
| `global` | Every consumer. |
| `identity-intelligence` | Identity intelligence. |
| `role-mining` | Role mining. |

`product_scopes` takes these values in the create and update bodies and in the list filter. Any
other value, such as `APPSTORE`, returns `400`.

Use `global` for general policy, and a narrower scope for guidance that applies in only one context.
To audit what a product can see, filter the list by `product_scopes`.

## Writing entries

Unlike every other v1 object, an entry's writes aren't JSON. Both
[Create Knowledge Context](https://docs.lumos.com/api-reference/v1/knowledge/create-knowledge-context.md) and
[Update Knowledge Context](https://docs.lumos.com/api-reference/v1/knowledge/update-knowledge-context.md) take
`multipart/form-data`, because either one can carry a file upload.

```bash theme={null}
curl -s -X POST 'https://api.lumos.com/v1/knowledge/context' \
  --header 'Authorization: Bearer lsk_your_token' \
  --form 'title=Production database access policy' \
  --form 'content=Access to production databases requires manager approval.' \
  --form 'generic_tags=security' \
  --form 'product_scopes=appstore'
```

Add `--form 'file=@runbook.pdf'` to attach a file. Omit it for a text-only entry.

`title` must be unique within your organization, so a create or update that reuses an existing
title returns `409` with `code` set to `knowledge.already_exists`.

> [!WARNING]
>
> On update, tag and scope lists **replace** rather than append. Sending `generic_tags` with one
> value leaves the entry with exactly that one tag, discarding the rest. Read the entry, modify the
> list client-side, and send the full list back.

Other update rules:

* A field you omit, or send empty, keeps its value.
* To replace the attachment, send a new `file`.
* To remove an attachment without replacing it, send `clear_attachment=true`. Omitting `file` alone
  leaves the existing file in place.
* Sending `file` together with `clear_attachment=true`, or no fields at all, returns `400`.

## Deleting

[Delete Knowledge Context](https://docs.lumos.com/api-reference/v1/knowledge/delete-knowledge-context.md) removes the entry.
It stops appearing in list results, agents stop using it, and
[Get Knowledge Context](https://docs.lumos.com/api-reference/v1/knowledge/get-knowledge-context.md) returns `404` with
`code` set to `knowledge.not_found`. You can't restore it through the API, so contact your Lumos
representative if you deleted an entry you need.

## Endpoints

| Endpoint | Path |
| - | - |
| [List Knowledge Context](https://docs.lumos.com/api-reference/v1/knowledge/list-knowledge-context.md) | `GET /v1/knowledge/context` |
| [Create Knowledge Context](https://docs.lumos.com/api-reference/v1/knowledge/create-knowledge-context.md) | `POST /v1/knowledge/context` |
| [Get Knowledge Context](https://docs.lumos.com/api-reference/v1/knowledge/get-knowledge-context.md) | `GET /v1/knowledge/context/{knowledge_context_id}` |
| [Update Knowledge Context](https://docs.lumos.com/api-reference/v1/knowledge/update-knowledge-context.md) | `PATCH /v1/knowledge/context/{knowledge_context_id}` |
| [Delete Knowledge Context](https://docs.lumos.com/api-reference/v1/knowledge/delete-knowledge-context.md) | `DELETE /v1/knowledge/context/{knowledge_context_id}` |