# API Catalog & Explorer

> Let developers and AI agents discover the APIs they are allowed to use, with OpenAPI documents and llms.txt.

URL: https://www.trakhound.com/docs/trakhound-framework/api-catalog

Developers who build applications on an Instance's APIs usually can't open the admin UI, and the System API exposes every API with internal details. The **API Catalog** shows each developer only what they can use, and the **API Explorer** App lets them browse and try those APIs from their browser.

Diagram: A developer or AI coding tool requests the API Catalog with their own API key. The Instance lists only the APIs and endpoints that caller is allowed to use. From the Catalog come OpenAPI documents for generating clients, the API Explorer App for trying requests and copying code samples, and llms.txt for AI agents.

## API Catalog

The Catalog is served on the Instance's HTTP port:

| Route | Returns |
| --- | --- |
| `/_developer/catalog` | The APIs served over HTTP, with only the endpoints the caller (signed-in session, API key, or Bearer token) is allowed to call, and which of them need authentication. |
| `/_developer/openapi/{apiId}` | That API's OpenAPI document, filtered the same way, with the server URL and the API key and Bearer security schemes. |

```
curl -H "X-API-Key: thk_..." http://localhost:8472/_developer/catalog
```

Access is controlled by the `system:api-catalog` resource (see [Security](https://www.trakhound.com/docs/trakhound-framework/security)). Administrators can also get the complete OpenAPI document of any API at `_api/openapi/{apiId}`, linked from the API's page in the admin UI.

For examples of calling APIs from Python, JavaScript, C#, Rust, C++, and cURL, and generating clients from these documents, see [Other Languages](https://www.trakhound.com/docs/trakhound-framework/clients).

## llms.txt

Every Instance serves `/llms.txt` (https://llmstxt.org), a Markdown index for AI agents: what the Instance is, how to connect (the [MCP Server](https://www.trakhound.com/docs/trakhound-framework/mcp-server) and API keys), and each API with its endpoints, descriptions, and OpenAPI document link. It is generated for each caller from the Catalog, so it only lists what the caller can use, and is protected the same way (`system:api-catalog`).

```
curl -H "X-API-Key: thk_..." http://localhost:8472/llms.txt
```

## System API OpenAPI

The System API is described by OpenAPI documents too, so clients can be generated for any language. They are served with the System API (on the Admin port when there is one) and protected by `system:instance`:

| Route | Returns |
| --- | --- |
| `/_instances/openapi` | The whole System API |
| `/_instances/openapi/areas` | The list of areas (ex. `volumes`, `services`, `functions`) |
| `/_instances/openapi/{area}` | One area |

Each operation's `x-trakhound-resource` is the System resource and permission it needs, and subscribe routes (WebSockets) are listed in `x-trakhound-streams`.

## API Explorer

The `TrakHound.ApiExplorer.App` Package is a browser for the Catalog. Install it and add an App configuration (default route `api-explorer`):

```
th packages install TrakHound.ApiExplorer.App
```

- Search the APIs and read each endpoint's parameters and descriptions
- Send **Try It** requests from the browser, using the developer's own credentials
- Copy code samples in cURL, JavaScript, C#, and Python
- Download the OpenAPI documents to generate clients

## Describing Your Endpoints

Descriptions on parameters appear in the Catalog, the OpenAPI documents, and [MCP Tool](https://www.trakhound.com/docs/trakhound-framework/mcp-server) inputs. See [APIs](https://www.trakhound.com/docs/trakhound-framework/apis#documentation).

```
[ApiGet("production")]
public async Task<TrakHoundApiResponse> GetProduction(
    [FromQuery(Description = "The first day to include")] DateTime start,
    [FromQuery(Description = "The last day to include")] DateTime end)
{
    ...
}
```
