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.

In this section

• Authentication: creating keys, the X-API-Key header, key format, revocation.

• Rate Limits: the per-key request budget and the X-RateLimit-* / Retry-After headers.

• Quickstart: first requests with curl, pagination, and the error format.

• Endpoint Reference: every endpoint with parameters and example responses.

• Versioning & Stability: versioning and deprecation policy.

• MCP Server: 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

Building a compliance or GRC connector? Start with the compliance evidence endpoints. They return per-user, per-item completion rows mapped to compliance frameworks, designed for evidence pulls.