# Using the Knowledge Base with AI Agents

HTML version: [Using the Knowledge Base with AI Agents](https://support.gladstonesoftware.cloud/api-integrations/using-the-knowledge-base-with-ai-agents)

## Problem

You are building an integration with the Gladstone GO platform and want an AI coding agent,
such as an assistant in your editor or a command-line agent, to read the API reference and
guides for you.

You want it to find the right endpoint quickly and read its details accurately, rather than
guess.

## Resolution

Every page on this site is served as plain HTML at its own address, so an agent that browses
the web, such as one using a web search or open-page tool, can read any page directly, without
running JavaScript. The home page, `https://support.gladstonesoftware.cloud/`, lists every guide,
every endpoint with its method, path and what it is for, and every knowledge base article, so an
agent opened there can choose and follow a link.

An agent that reads markdown, such as a coding agent in your editor, does better with the
markdown version of the site, described below. It is the same content, generated from the same
source on every release, with no navigation, styling or script around it.

### The index: `llms.txt`

```text
https://support.gladstonesoftware.cloud/llms.txt
```

This is a single markdown file that lists every page on the site, grouped the same way as the
sidebar:

- **Guides**: authentication, the glossary, and the end-to-end booking, joining and payment
  flows
- **API reference**: every endpoint, by group and subgroup, with its HTTP method, its path and
  a one-line description of what it is for
- **Knowledge base**: a link to each product area's own index (see below), then any
  articles not yet in a product area, by category

Each entry links to that page's markdown file by its full address, so an agent can open it
directly. The index holds titles, one-line summaries and
links only. It does not contain the pages themselves, so the agent reads the index, follows
the links it needs, and fetches only those pages.

### Each API group: `/reference/<group>/llms.txt`

Each API group also has its own index, listing only that group's endpoints, with a longer
description of each:

```text
https://support.gladstonesoftware.cloud/reference/bookings/llms.txt
https://support.gladstonesoftware.cloud/reference/members/llms.txt
```

If you already know which part of the API your integration uses, point the agent at that
group's index rather than the site-wide one. It is smaller, and keeps the agent to that area.

The file follows the [llms.txt](https://llmstxt.org) convention, which some tools look for on
their own.

### Any single page: add `.md`

Every page listed in the index has a markdown version at its own address with `.md` added:

| Page | Markdown |
|---|---|
| `https://support.gladstonesoftware.cloud/guides/booking` | `https://support.gladstonesoftware.cloud/guides/booking.md` |
| `https://support.gladstonesoftware.cloud/reference/bookings/list-all-available-sessions-version-2` | `https://support.gladstonesoftware.cloud/reference/bookings/list-all-available-sessions-version-2.md` |
| `https://support.gladstonesoftware.cloud/api-integrations/using-the-knowledge-base-with-ai-agents` | `https://support.gladstonesoftware.cloud/api-integrations/using-the-knowledge-base-with-ai-agents.md` |

Links inside a markdown page point at other markdown pages, so an agent that follows a link
from one page lands on another markdown page. Unlike the links in the `llms.txt` indexes, these
are relative, so resolve them against the address of the page they appear in.

Each endpoint page starts with its method and path and the products and features your
integration must be granted to call it. Where more than one is listed, your integration needs
**any one** of them, not all. See
[Authenticating with Gladstone APIs](../guides/authenticating-with-gladstone-apis.md) for how
products and features are granted.

### Knowledge base articles in one file: `llms-full.txt`

Some agents work better with a whole set of articles in context at once, such as an assistant
answering questions about one product. For those, knowledge base articles are also published
concatenated:

| Address | Holds | Size |
|---|---|---|
| `https://support.gladstonesoftware.cloud/kb/llms-full.txt` | Every knowledge base article, in every product area | about 1.3 MB |
| `https://support.gladstonesoftware.cloud/<area>/llms-full.txt` | One product area's knowledge base articles (see below) | a few KB to a few hundred KB |

There is no combined file for the guides or the API reference. Most agents' fetch tools read
only the start of a large file and silently drop the rest, so an agent given every endpoint in
one file could miss the one it needed. For the API, start from `llms.txt`: each endpoint there
has a one-line description of what it is for, so the agent can choose and then fetch only the
pages it needs. The addresses `/llms-full.txt` and `/apis/llms-full.txt`, which used to hold
guides and endpoints, now redirect to `llms.txt`.

Pick the narrowest file that covers the job. An agent answering questions about one product
needs that product area's file, not `/kb/llms-full.txt`.

Each article in a file starts with a marker line giving its path, then its own `#` title. In
`/kb/llms-full.txt`, for example:

```text
<!-- page: ../gladstone360/access-control-entry-points-and-entry-point-profiles.md -->

# Access Control – Entry Points and Entry Point Profiles
```

Links between articles use the same paths, so a link to
`../gladstone360/access-control-entry-points-and-entry-point-profiles.md` means the article with that
marker in the same file. Tell your agent this, or split the file on the marker lines first.
Paths are relative to the file they appear in, exactly as links are. A link to a page that is
not in the file, such as a guide, points at that page's own markdown, so an agent can still
fetch it.

### One product area: `/<area>/llms.txt` and `/<area>/llms-full.txt`

Knowledge base articles are grouped into product areas, such as Gladstone360, Go Operator,
Hardware or Plus2. Each area has its own address, and its articles live under it:

```text
https://support.gladstonesoftware.cloud/gladstone360/llms.txt
https://support.gladstonesoftware.cloud/gladstone360/llms-full.txt
https://support.gladstonesoftware.cloud/gladstone360/<article>
https://support.gladstonesoftware.cloud/gladstone360/<article>.md
```

The area's `llms.txt` lists only that area's articles, and its `llms-full.txt` holds them all in
full. Point an agent at one of these, rather than at the site-wide index, when you want it to
stay within one product and not pick up material about another. The site-wide `llms.txt` lists
every area and links to each one's index and full file, under **Knowledge base → Sections**.

Some articles are not in a product area yet. They are still at `/kb/<article>` and are listed in
the site-wide index under **Other articles**. They are in `/kb/llms-full.txt`, with every other
article, but in no area's file. If an article moves into an area, its old
`/kb/<article>` address still opens it in a browser, but its markdown is only at the new address,
so take addresses from the index rather than keeping your own list.

### Pointing your agent at it

How you do this depends on the agent. It works with any agent that can fetch a URL:

- **In a prompt.** Give it the index address and the task, for example: *"Using the Gladstone API
  documentation at https://support.gladstonesoftware.cloud/llms.txt, write a client for the
  booking flow."*
- **In your project's agent instructions.** Most agents read a file of standing instructions
  from the repository. Add a line saying that the Gladstone API is documented at the `llms.txt`
  address above and should be read from there, not guessed.
- **In a script.** Fetch `llms.txt`, pick the links you need, and fetch those `.md` files into
  whatever your tooling uses as context.
- **As one file.** If the agent takes a single document as its knowledge source and only needs
  knowledge base articles, give it the `llms-full.txt` address for its product area, above. For
  the API, give it `llms.txt`. Every file is rebuilt on every release, so reference the address
  rather than downloading a copy that will go out of date.

Ask the agent to read these three pages before anything else, in this order. The rest of the
documentation assumes them:

1. [Getting started](../guides/getting-started.md)
2. [Authenticating with Gladstone APIs](../guides/authenticating-with-gladstone-apis.md)
3. [Glossary](../guides/glossary.md). Several Gladstone terms look like ordinary English words and
   mean something specific.

## Notes

- **No sign-in is needed.** The markdown files are public, like the rest of the documentation.
  Never put an API key, token or password in a prompt or an agent instructions file; the
  documentation does not need one.
- **The markdown matches the site.** Both are built from the same source in the same release, so
  the markdown is never behind or ahead of what you see in a browser.
- **Some details are not documented yet.** Where a detail could not be confirmed, the page leaves
  it out rather than guess: a field or error row can have an empty description, in the markdown
  and on the web page alike. An empty cell means exactly that: the behaviour is not documented.
  Tell your agent not to fill it in by guessing. If your integration depends on one,
  [raise a support case](../guides/raising-a-support-case.md).
- **An agent can still be wrong.** It reads what is published and may misread it. Check its
  output against the endpoint page before you rely on it, especially the **Errors** table and
  any field marked required.