> For the complete documentation index, see [llms.txt](https://herd-security.gitbook.io/herd-security-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://herd-security.gitbook.io/herd-security-docs/api-documentation.md).

# API Documentation

Reference documentation for the Herd Security public API: authentication, rate limits, a quickstart integration guide, the full endpoint reference, and the MCP server for AI assistants.

## Overview

The Herd Security API gives you programmatic, read-only access to your organization's security-awareness data: training content, tracks, users, enrollments and completion status, audit logs, and pull-model compliance evidence feeds for GRC platforms (framework completions and policy attestations).

All endpoints:

* Live under the versioned base URL below.
* Use `GET` requests and return JSON (plus an optional CSV export on the completions feed).
* Require an API key sent in the `X-API-Key` header.
* Are scoped to your organization; a key only ever sees its own organization's data.

### Base URL

```
https://api.herdsecurity.io/api/v1
```

### Machine-readable spec

The API is described by an OpenAPI 3.0 document, served by the API itself:

```
https://api.herdsecurity.io/api-docs/openapi.json
```

You can import this spec into tools like Postman, Insomnia, or code generators.

### AI assistants: the MCP server

If what you want is an AI assistant (Claude, Cursor, Claude Code) working with your Herd data, you don't need an API key at all. Herd runs an **MCP server** that those tools connect to with your normal Herd sign-in, offering the same reporting tools HerdAI uses plus draft-training creation. See [MCP Server](/herd-security-docs/api-documentation/mcp-server.md).

## In this section

* [Authentication](/herd-security-docs/api-documentation/authentication.md): creating keys, the `X-API-Key` header, key format, revocation.
* [Rate Limits](/herd-security-docs/api-documentation/rate-limits.md): the per-key request budget and the `X-RateLimit-*` / `Retry-After` headers.
* [Quickstart](/herd-security-docs/api-documentation/quickstart.md): first requests with `curl`, pagination, and the error format.
* [Endpoint Reference](/herd-security-docs/api-documentation/endpoint-reference.md): every endpoint with parameters and example responses.
* [Versioning & Stability](/herd-security-docs/api-documentation/versioning-and-stability.md): versioning and deprecation policy.
* [MCP Server](/herd-security-docs/api-documentation/mcp-server.md): connecting an AI assistant to Herd over the Model Context Protocol.

## Core resources

| Resource            | Endpoints                                                                                                                    | What it's for                                                             |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| Users               | `GET /users`                                                                                                                 | Your organization's user directory with Active/Inactive status            |
| Trainings           | `GET /trainings`, `GET /tags/{tag_id}/trainings`                                                                             | The training library, with compliance-framework mappings                  |
| Tracks              | `GET /tracks`                                                                                                                | Ordered learning paths, with compliance-framework mappings                |
| Tags                | `GET /tags`                                                                                                                  | Free-form labels used to group trainings                                  |
| Enrollments         | `GET /enrollments`                                                                                                           | Per-user training enrollments and completion status                       |
| Compliance evidence | `GET /integration/frameworks`, `GET /integration/frameworks/{framework}/completions`, `GET /integration/policy-attestations` | Pull-model evidence feeds for GRC and audit tools, including a CSV export |
| Audit logs          | `GET /audit-logs`                                                                                                            | Your organization's audit trail, with who/what/where/when detail          |

{% hint style="info" %}
Building a compliance or GRC connector? Start with the [compliance evidence endpoints](/herd-security-docs/api-documentation/endpoint-reference.md#compliance-evidence). They return per-user, per-item completion rows mapped to compliance frameworks, designed for evidence pulls.
{% endhint %}