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

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:

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 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:

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 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:

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:

<!-- 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:

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
2. Authenticating with Gladstone APIs
3. Glossary. 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.
• 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.

This page as markdown · All pages · llms.txt