> 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/endpoint-reference.md).

# Endpoint Reference

Full reference for every Herd API endpoint: parameters, response schemas, and example responses for users, trainings, tracks, tags, enrollments, compliance evidence, and audit logs.

All endpoints are `GET` requests under `https://api.herdsecurity.io/api/v1`, require the `X-API-Key` header (see [Authentication](/herd-security-docs/api-documentation/authentication.md)), and support the standard pagination parameters `page` (default 1) and `per_page` (default 50, max 100) unless noted otherwise. Responses use the standard envelope described in the [Quickstart](/herd-security-docs/api-documentation/quickstart.md).

Endpoints at a glance:

| Endpoint                                                                      | Description                                                |
| ----------------------------------------------------------------------------- | ---------------------------------------------------------- |
| [`GET /users`](#users)                                                        | List your organization's users                             |
| [`GET /trainings`](#trainings)                                                | List the training library                                  |
| [`GET /tracks`](#tracks)                                                      | List tracks (ordered learning paths)                       |
| [`GET /tags`](#tags)                                                          | List training tags                                         |
| [`GET /tags/{tag_id}/trainings`](#tags)                                       | List trainings under a tag                                 |
| [`GET /enrollments`](#enrollments)                                            | List training enrollments and completion status            |
| [`GET /integration/frameworks`](#compliance-evidence)                         | List compliance frameworks available for evidence pulls    |
| [`GET /integration/frameworks/{framework}/completions`](#compliance-evidence) | Per-user completion evidence for a framework (JSON or CSV) |
| [`GET /integration/policy-attestations`](#compliance-evidence)                | Per-user policy acknowledgement status                     |
| [`GET /audit-logs`](#audit-logs)                                              | Pull your organization's audit trail                       |

## Compliance frameworks

Several endpoints filter by or return **compliance framework** identifiers. The valid values are:

`SOC2`, `ISO27001`, `NIST_CSF`, `GDPR`, `HIPAA`, `PCI_DSS`, `SOX`, `FISMA`, `CUSTOM`, `SOC1`, `FERPA`, `CMMC`, `CCPA_CPRA`, `ISO42001`, `FEDRAMP`, `FDA_21_CFR_PART_11`, `CUI_FCI`

***

## Users

### GET /users

Retrieve a paginated list of all users in your organization.

**Query parameters:** `page`, `per_page`.

{% code title="Response" %}

```json
{
  "status": "success",
  "data": [
    {
      "user_id": "usr_cluser789xyz",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane.smith@company.com",
      "status": "Active"
    }
  ],
  "pagination": {
    "total_records": 250,
    "current_page": 1,
    "total_pages": 5,
    "per_page": 50,
    "next_page_url": "https://api.herdsecurity.io/api/v1/users?page=2&per_page=50"
  }
}
```

{% endcode %}

**Status values:**

* `Active` — the user is connected to Slack or Microsoft Teams.
* `Inactive` — the user is not connected to any messaging platform.

***

## Trainings

### GET /trainings

Retrieve a paginated list of trainings in your organization's library, optionally filtered by compliance framework.

**Query parameters:**

| Parameter   | Type    | Required | Description                                                                                                  |
| ----------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------ |
| `page`      | integer | No       | Page number (default 1)                                                                                      |
| `per_page`  | integer | No       | Records per page (default 50, max 100)                                                                       |
| `framework` | string  | No       | Only return trainings mapped to this [compliance framework](#compliance-frameworks) (for example, `PCI_DSS`) |

{% code title="Response" %}

```json
{
  "status": "success",
  "data": [
    {
      "training_id": "trn_clxyz123abc",
      "title": "Phishing Awareness 101",
      "description": "Learn to identify and report phishing attempts",
      "tags": ["phishing", "PCI"],
      "frameworks": ["PCI_DSS"],
      "created_at": "2024-01-10T08:30:00Z"
    }
  ],
  "pagination": {
    "total_records": 42,
    "current_page": 1,
    "total_pages": 1,
    "per_page": 50
  }
}
```

{% endcode %}

***

## Tracks

### GET /tracks

Retrieve a paginated list of tracks (ordered learning paths) in your organization, optionally filtered by compliance framework.

**Query parameters:**

| Parameter   | Type    | Required | Description                                                                                            |
| ----------- | ------- | -------- | ------------------------------------------------------------------------------------------------------ |
| `page`      | integer | No       | Page number (default 1)                                                                                |
| `per_page`  | integer | No       | Records per page (default 50, max 100)                                                                 |
| `framework` | string  | No       | Only return tracks mapped to this [compliance framework](#compliance-frameworks) (for example, `SOC2`) |

{% code title="Response" %}

```json
{
  "status": "success",
  "data": [
    {
      "track_id": "trk_cltrack123abc",
      "title": "PCI DSS Onboarding",
      "description": "Sequential trainings for payment-handling staff",
      "tags": ["onboarding"],
      "frameworks": ["PCI_DSS", "SOC2"],
      "created_at": "2024-01-10T08:30:00Z"
    }
  ],
  "pagination": {
    "total_records": 6,
    "current_page": 1,
    "total_pages": 1,
    "per_page": 50
  }
}
```

{% endcode %}

***

## Tags

{% hint style="info" %}
API **tags** are free-form labels used to group and categorize trainings. They are not the same as the **Tracks** feature in the web app (ordered, scheduled learning paths). A tag's `tag_id` is derived from the tag's name; the `tag_id` on an enrollment maps to the training's first tag, not to a Track.
{% endhint %}

### GET /tags

Retrieve a paginated list of all training tags in your organization, sorted by name.

**Query parameters:** `page`, `per_page`.

{% code title="Response" %}

```json
{
  "status": "success",
  "data": [
    {
      "tag_id": "tag_U2VjdXJpdHk",
      "name": "Security Awareness",
      "status": "In Progress",
      "start_date": null,
      "end_date": null,
      "created_at": "2024-01-10T08:30:00Z"
    }
  ],
  "pagination": {
    "total_records": 25,
    "current_page": 1,
    "total_pages": 1,
    "per_page": 50
  }
}
```

{% endcode %}

{% hint style="warning" %}
On this endpoint, `status` is currently always `"In Progress"` and `start_date`/`end_date` are always `null` — tags don't yet track scheduling. Use [`GET /enrollments`](#enrollments) for real per-user status and dates.
{% endhint %}

### GET /tags/{tag\_id}/trainings

Retrieve all trainings associated with a specific tag. Returns **404** if the tag doesn't exist.

**Path parameters:**

| Parameter | Type   | Required | Description                                         |
| --------- | ------ | -------- | --------------------------------------------------- |
| `tag_id`  | string | Yes      | The tag identifier (for example, `tag_U2VjdXJpdHk`) |

**Query parameters:** `page`, `per_page`.

{% code title="Response" %}

```json
{
  "status": "success",
  "tag_id": "tag_U2VjdXJpdHk",
  "data": [
    {
      "training_id": "trn_clxyz123abc",
      "title": "Phishing Awareness 101",
      "description": "Learn to identify and report phishing attempts",
      "frameworks": ["PCI_DSS"]
    }
  ],
  "pagination": {
    "total_records": 10,
    "current_page": 1,
    "total_pages": 1,
    "per_page": 50
  }
}
```

{% endcode %}

***

## Enrollments

### GET /enrollments

Retrieve training enrollments with completion status and dates. This is the primary endpoint for tracking training progress across your organization.

**Query parameters:** `page`, `per_page`.

{% code title="Response" %}

```json
{
  "status": "success",
  "data": [
    {
      "enrollment_id": "enr_clenroll456def",
      "user_id": "usr_cluser789xyz",
      "tag_id": "tag_U2VjdXJpdHk",
      "training_id": "trn_clxyz123abc",
      "enrollment_date": "2024-01-15T09:00:00Z",
      "completion_date": "2024-01-16T14:20:00Z",
      "status": "Passed"
    }
  ],
  "pagination": {
    "total_records": 500,
    "current_page": 1,
    "total_pages": 10,
    "per_page": 50,
    "next_page_url": "https://api.herdsecurity.io/api/v1/enrollments?page=2&per_page=50"
  }
}
```

{% endcode %}

**Field notes:**

* `status` — one of `Not started`, `In Progress`, or `Passed`. Completed trainings are always reported as `Passed`; there is no separate fail state.
* `enrollment_date` — always present; when the user was enrolled.
* `completion_date` — `null` until the user completes the training.
* `tag_id` — the training's first tag, or `null` if the training has no tags.

***

## Compliance evidence

Pull-model evidence feeds for GRC integrations: per-user completion evidence mapped to compliance frameworks, plus policy acknowledgement status.

### GET /integration/frameworks

Retrieve the compliance frameworks available for evidence pulls, each with a link to its completions feed.

**Query parameters:** `page`, `per_page`.

{% code title="Response" %}

```json
{
  "status": "success",
  "data": [
    {
      "framework": "SOC2",
      "completions_url": "https://api.herdsecurity.io/api/v1/integration/frameworks/SOC2/completions"
    },
    {
      "framework": "ISO27001",
      "completions_url": "https://api.herdsecurity.io/api/v1/integration/frameworks/ISO27001/completions"
    }
  ],
  "pagination": {
    "total_records": 17,
    "current_page": 1,
    "total_pages": 1,
    "per_page": 50
  }
}
```

{% endcode %}

{% hint style="info" %}
This endpoint lists the full framework catalog Herd supports, not just the frameworks your content currently maps to. A framework's completions feed simply returns no rows if none of your content is mapped to it.
{% endhint %}

### GET /integration/frameworks/{framework}/completions

Retrieve per-user, per-item completion rows (trainings, tracks, and policy acknowledgements) for a compliance framework — the pull-model evidence feed for GRC integrations. Filters apply before pagination, so `total_records`/`total_pages` describe the filtered set, and `next_page_url` preserves active filters.

**Path parameters:**

| Parameter   | Type   | Required | Description                                                                                      |
| ----------- | ------ | -------- | ------------------------------------------------------------------------------------------------ |
| `framework` | string | Yes      | The [compliance framework](#compliance-frameworks) to pull evidence for (for example, `PCI_DSS`) |

**Query parameters:**

| Parameter          | Type    | Required | Description                                                                                           |
| ------------------ | ------- | -------- | ----------------------------------------------------------------------------------------------------- |
| `page`             | integer | No       | Page number (default 1); ignored when `format=csv`                                                    |
| `per_page`         | integer | No       | Records per page (default 50, max 100); ignored when `format=csv`                                     |
| `status`           | string  | No       | Only return rows with this completion status: `completed`, `in_progress`, `not_started`, or `overdue` |
| `completed_after`  | string  | No       | Only return rows completed at or after this ISO 8601 datetime (inclusive)                             |
| `completed_before` | string  | No       | Only return rows completed at or before this ISO 8601 datetime (inclusive)                            |
| `format`           | string  | No       | Set to `csv` to download every filtered row (no pagination) as a `text/csv` attachment                |

{% hint style="info" %}
Rows without a completion date are excluded whenever either date bound is set. The CSV export contains the columns `user_email`, `user_name`, `item_name`, `item_kind`, `framework`, `status`, `completed_at`, `due_date`, `certificate_number` (a reserved column, always empty), `evidence_url`.
{% endhint %}

{% code title="Response" %}

```json
{
  "status": "success",
  "framework": "PCI_DSS",
  "data": [
    {
      "user_id": "usr_cluser789xyz",
      "user_email": "jane.smith@company.com",
      "user_name": "Jane Smith",
      "item_id": "trn_clxyz123abc",
      "item_name": "PCI DSS Fundamentals",
      "item_kind": "training",
      "item_type": "training",
      "framework": "PCI_DSS",
      "status": "completed",
      "completed_at": "2024-01-16T14:20:00Z",
      "due_date": "2024-02-01T00:00:00Z",
      "certificate_number": null,
      "evidence_url": null
    }
  ],
  "pagination": {
    "total_records": 120,
    "current_page": 1,
    "total_pages": 3,
    "per_page": 50,
    "next_page_url": "https://api.herdsecurity.io/api/v1/integration/frameworks/PCI_DSS/completions?page=2&per_page=50"
  }
}
```

{% endcode %}

**Field notes:**

* `item_kind` — `training` for training/track completions, `policy` for policy acknowledgements.
* `item_type` — `training` or `track` for training rows; the policy type (or `policy`) for policy rows.
* `status` — `completed`, `in_progress`, `not_started`, or `overdue`.
* `certificate_number` — reserved for compatibility; always `null` (the certificates feature has been retired).
* `evidence_url` — a link to supporting evidence (for example, the acknowledged policy document), when available.

Unknown framework values and invalid filter values are rejected with **400**.

### GET /integration/policy-attestations

Retrieve per-user policy acknowledgement status across the organization's active (non-archived) policies.

**Query parameters:** `page`, `per_page`.

{% code title="Response" %}

```json
{
  "status": "success",
  "data": [
    {
      "attestation_id": "att_clattest123abc",
      "user_id": "usr_cluser789xyz",
      "user_email": "jane.smith@company.com",
      "user_name": "Jane Smith",
      "policy_id": "pol_clpolicy456def",
      "policy_name": "Acceptable Use Policy",
      "policy_version": "2.1",
      "acknowledged": true,
      "acknowledged_at": "2024-01-16T14:20:00Z",
      "delivery_channel": "SLACK"
    }
  ],
  "pagination": {
    "total_records": 85,
    "current_page": 1,
    "total_pages": 2,
    "per_page": 50,
    "next_page_url": "https://api.herdsecurity.io/api/v1/integration/policy-attestations?page=2&per_page=50"
  }
}
```

{% endcode %}

**Field notes:**

* `acknowledged_at` — `null` until the user acknowledges the policy.
* `delivery_channel` — `SLACK` or `EMAIL`; `null` for attestations created before delivery tracking.
* `policy_version` — `null` if the policy doesn't track versions.

***

## Audit logs

### GET /audit-logs

Pull your organization's audit trail — the same records shown in the console under [Reports → Activity → Activity log](/herd-security-docs/reports/reports/activity-and-monitoring.md#activity-log). Rows are ordered by `(timestamp, id)` ascending, so pages are stable for incremental pulls. Note that every read of this endpoint itself writes an audit event.

**Query parameters:**

| Parameter         | Type    | Required | Description                                                                                |
| ----------------- | ------- | -------- | ------------------------------------------------------------------------------------------ |
| `page`            | integer | No       | Page number (default 1)                                                                    |
| `per_page`        | integer | No       | Records per page (default 50, max 100)                                                     |
| `event_type`      | string  | No       | Only return events of this type (for example, `USER_LOGIN`, `ADMIN_ACTION`, `DATA_EXPORT`) |
| `occurred_after`  | string  | No       | Only return events at or after this ISO 8601 datetime (inclusive)                          |
| `occurred_before` | string  | No       | Only return events at or before this ISO 8601 datetime (inclusive)                         |

{% code title="Response" %}

```json
{
  "status": "success",
  "data": [
    {
      "id": "aud_claudit123abc",
      "when": "2026-07-30T14:20:00.000Z",
      "who": {
        "userId": "usr_cluser789xyz",
        "actor": "jane.smith@company.com",
        "ipAddress": "203.0.113.7",
        "userAgent": "Mozilla/5.0 ...",
        "sessionId": "ses_clsession456def"
      },
      "what": {
        "eventType": "ADMIN_ACTION",
        "action": "permissions.changed"
      },
      "where": {
        "resource": "group",
        "resourceType": "Group",
        "resourceId": "grp_clgroup123abc"
      },
      "why": {
        "success": true,
        "errorMessage": null
      },
      "riskLevel": "MEDIUM",
      "correlationId": "cor_clcorr789xyz",
      "description": "Group permissions changed"
    }
  ],
  "pagination": {
    "total_records": 4210,
    "current_page": 1,
    "total_pages": 85,
    "per_page": 50,
    "next_page_url": "https://api.herdsecurity.io/api/v1/audit-logs?page=2&per_page=50"
  }
}
```

{% endcode %}

**Field notes:**

* Each record answers the "5 Ws": `when` (UTC timestamp), `who` (the acting user or credential, with IP, user agent, and session), `what` (the event type and fine-grained action code), `where` (the affected resource), and `why` (the outcome — success or the error message).
* `who.userId` is `null` for machine access (for example, API-key reads); `who.actor` still identifies the acting credential.
* `riskLevel` — `LOW`, `MEDIUM`, `HIGH`, or `CRITICAL`.

Invalid `event_type` and malformed datetime values are rejected with **400**.