> 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

## 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, 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.

## 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.

## 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 %}