# Policy versions

`GET https://api.kapiworks.com/v1/policies`

Every version of the company's policies published by `as_at`, oldest first, each with its canonical HTML file, its statement and every field its `version_digest` covers, so anyone can check the file and the digest without Kapi. A page holds fewer versions when their files are long. Requires `acknowledgements:read`.

Scope: `acknowledgements:read`.

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `as_at` | string (date-time) or string (date) | No | RFC 3339 instant with an offset, or a date read as the end of the company's day. Versions published by then. Defaults to now. |
| `cursor` | string | No | Opaque next_cursor from the previous page. Send it unchanged to the same endpoint. It pins the snapshot and filters, and grants no access. |
| `limit` | integer | No | Rows per page, 1 to 200. Larger values are treated as 200. A page can hold fewer rows to stay within 3 MiB, so follow next_cursor until it is null. |

## Responses

| Status | Description |
| --- | --- |
| 200 | One page from a pinned company snapshot. |
| 400 | RFC 9457 problem details. Codes: invalid_request, invalid_cursor, key_in_url. Act on `code` or `type`; never parse `detail`. |
| 401 | RFC 9457 problem details. Codes: invalid_token. Act on `code` or `type`; never parse `detail`. |
| 403 | RFC 9457 problem details. Codes: insufficient_scope, ip_not_allowed. Act on `code` or `type`; never parse `detail`. |
| 404 | RFC 9457 problem details. Codes: not_found. Act on `code` or `type`; never parse `detail`. |
| 405 | RFC 9457 problem details. Codes: method_not_allowed. Act on `code` or `type`; never parse `detail`. |
| 422 | RFC 9457 problem details. Codes: before_history, record_too_large. Act on `code` or `type`; never parse `detail`. |
| 429 | RFC 9457 problem details. Codes: rate_limited, concurrent_limit. Act on `code` or `type`; never parse `detail`. |
| 502 | RFC 9457 problem details. Codes: read_failed. Act on `code` or `type`; never parse `detail`. |
| 503 | RFC 9457 problem details. Codes: unavailable, upstream_unavailable, writer_unavailable. Act on `code` or `type`; never parse `detail`. |
| 504 | RFC 9457 problem details. Codes: read_timeout. Act on `code` or `type`; never parse `detail`. |

## Fields of each row

| Field | Type | Meaning |
| --- | --- | --- |
| `deployment_id` | string (uuid) | Kapi deployment UUID. |
| `organization_id` | string (uuid) | Company UUID. |
| `learning_space_id` | string (uuid) | Learning-space UUID. |
| `course_id` | string (uuid) | Policy UUID. Part of the digest. |
| `course_release_id` | string (uuid) | Published version UUID. |
| `policy_title` | string | The title, from the file’s main heading. |
| `version` | integer | Version number. Part of the digest. |
| `act` | string | What people do: acknowledge or sign. Part of the digest. |
| `doors` | array of string | Who may receive it: employee, partner and customer, sorted. Part of the digest. |
| `statement` | string | The words people confirm. |
| `statement_sha256` | string | SHA-256 of the statement, normalised: Unicode NFC, each run of white space as one space, trimmed. Part of the digest. |
| `effective_on` | string (date) | When it takes effect, YYYY-MM-DD. Part of the digest. |
| `renew_months` | integer | Months after a signature before the person is asked again; 0 when they are not asked again. Part of the digest. |
| `change_kind` | string | first, ask_again (everyone signs again) or editorial (a small fix; earlier receipts still count). Part of the digest. |
| `published_at` | string (date-time) | When it was published. |
| `document_sha256` | string | SHA-256 of html, the canonical file. Part of the digest. |
| `version_digest` | string | The version digest: SHA-256 of these lines joined by line feeds: kapi.works.policy/2, course_id, version, document_sha256, statement_sha256, act, effective_on (empty when there is none), change_kind, renew_months, the doors sorted and joined with commas. |
| `html` | string | The canonical policy file in Kapi policy HTML, exactly as people read it and signed it. |

## Example response

```json
{
  "data": [
    {
      "deployment_id": "00000000-0000-4000-8000-000000000001",
      "organization_id": "4f6b2a52-1c1e-4f7a-9d3e-2b7c8a9e0d11",
      "learning_space_id": "8b2d6c3e-5f41-4a8e-9c27-1d0e3f4a5b62",
      "course_id": "3e1d5c7b-9a2f-4e6d-8c1b-5a7f9e3d1c22",
      "course_release_id": "6f4e2d1c-8b7a-4c9e-9d3f-2e1a0b9c8d33",
      "policy_title": "Partner code of conduct",
      "version": 2,
      "act": "sign",
      "doors": [
        "partner"
      ],
      "statement": "By signing, I agree to the Partner code of conduct, version 2.",
      "statement_sha256": "7e9b1d3f5a7c9e2b4d6f8a0c1e3b5d7f9a2c4e6b8d0f1a3c5e7b9d2f4a6c8e0b",
      "effective_on": "2026-11-01",
      "renew_months": 12,
      "change_kind": "ask_again",
      "published_at": "2026-10-01T08:30:00Z",
      "document_sha256": "0c2e4b6d8f1a3c5e7b9d2f4a6c8e0b1d3f5a7c9e2b4d6f8a0c1e3b5d7f9a2c4e",
      "version_digest": "4b1d9e7f2a6c8e0b3d5f7a9c1e3b5d7f9a2c4e6b8d0f1a3c5e7b9d2f4a6c8e0b",
      "html": "<!doctype html>\n<html lang=\"en-GB\">\n<head>\n<meta charset=\"utf-8\">\n<title>Partner code of conduct</title>\n</head>\n<body>\n<h1>Partner code of conduct</h1>\n<p>We expect our partners to act honestly and fairly.</p>\n<kapi-sign></kapi-sign>\n</body>\n</html>\n"
    }
  ],
  "total": 1,
  "snapshot": {
    "organization_id": "4f6b2a52-1c1e-4f7a-9d3e-2b7c8a9e0d11",
    "deployment_id": "00000000-0000-4000-8000-000000000001",
    "as_at": "2026-10-09T09:00:00Z",
    "from": null,
    "known_at": "2026-10-09T08:59:41Z",
    "sequence": 1284,
    "capture_sequence": 352,
    "chain_hash": "3f9a1c7e5b2d8f4a6c0e9b1d3f5a7c9e2b4d6f8a0c1e3b5d7f9a2c4e6b8d0f1a",
    "logic": {
      "version": 4,
      "date": "2026-10-06"
    },
    "history_complete_from": "2026-10-06T05:00:00Z",
    "available": true
  },
  "next_cursor": null
}
```

The full contract, with every schema, is at https://api.kapiworks.com/v1/openapi.json.