Requirements API

Requirements are specific compliance obligations within a framework (regulation). Each requirement belongs to one or more frameworks and can be linked to controls that satisfy it.

POST /requirements/

Create a new requirement.

Field	Type	Required	Description
title	string	Yes	The title of the requirement.
regulation_ids	array	Yes	Array of framework IDs this requirement belongs to.
description	string	No	Rich-text description (HTML supported).
chapter_name	string	No	Name of the chapter/section.
chapter_number	string	No	Chapter/section number.
paragraph_number	string	No	Paragraph number within the chapter.
meaning	string	No	Explanation of what the requirement means.
label_ids	array	No	Array of label UUIDs to attach.
is_applicable	boolean	No	Whether this requirement is applicable. Defaults to true.

curl --location 'https://YOUR_KORDON_DOMAIN/api/v1/requirements/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-TOKEN' \
--data '{
    "requirement": {
        "title": "Information Security Policy",
        "regulation_ids": ["b698a0ed-ad82-4468-900e-3b6eb3f5eb9b"],
        "description": "<p>The organization shall define and communicate an information security policy.</p>",
        "chapter_name": "Organizational Controls",
        "chapter_number": "5",
        "paragraph_number": "5.1",
        "meaning": "A documented policy must exist and be communicated to all employees.",
        "is_applicable": true
    }
}'

Example response:

Status 200

{
    "data": {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "title": "Information Security Policy",
        "description": "<p>The organization shall define and communicate an information security policy.</p>",
        "chapter_name": "Organizational Controls",
        "chapter_number": "5",
        "paragraph_number": "5.1",
        "meaning": "A documented policy must exist and be communicated to all employees.",
        "is_applicable": true,
        "labels": [],
        "regulations": [
            {
                "id": "b698a0ed-ad82-4468-900e-3b6eb3f5eb9b",
                "title": "ISO 27001:2022"
            }
        ],
        "controls": [],
        "created_at": "2024-08-28T14:27:26+00:00",
        "updated_at": "2024-08-28T14:27:26+00:00"
    }
}

---

GET /requirements/:id

Get a single requirement by ID.

curl --location --request GET 'https://YOUR_KORDON_DOMAIN/api/v1/requirements/a1b2c3d4-e5f6-7890-abcd-ef1234567890' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-TOKEN'

Example response:

Status 200

{
    "data": {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "title": "Information Security Policy",
        "description": "<p>The organization shall define and communicate an information security policy.</p>",
        "chapter_name": "Organizational Controls",
        "chapter_number": "5",
        "paragraph_number": "5.1",
        "meaning": "A documented policy must exist and be communicated to all employees.",
        "is_applicable": true,
        "labels": [],
        "regulations": [
            {
                "id": "b698a0ed-ad82-4468-900e-3b6eb3f5eb9b",
                "title": "ISO 27001:2022"
            }
        ],
        "controls": [],
        "created_at": "2024-08-28T14:27:26+00:00",
        "updated_at": "2024-08-28T14:27:26+00:00"
    }
}

---

GET /requirements/

List all requirements.

Query Parameters

Parameter	Type	Description
frameworks[]	array	Filter by framework IDs.
applicability[]	array	Filter by applicability: true, false.
chapter[]	array	Filter by chapter names.
controls[]	array	Filter by control status: with_failing_controls, with_no_controls.
labels[]	array	Filter by label IDs. Use none for requirements without labels.

Array parameters

To filter by multiple values, repeat the parameter with [] brackets for each value. For example, to filter requirements from multiple frameworks:

?frameworks[]=b698a0ed-ad82-4468-900e-3b6eb3f5eb9b&frameworks[]=023fb404-56f6-49cd-9379-dbf584d2eef8

This bracket notation applies to all array parameters.

curl --location --request GET 'https://YOUR_KORDON_DOMAIN/api/v1/requirements/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-TOKEN'

Example with filters:

curl --location --request GET 'https://YOUR_KORDON_DOMAIN/api/v1/requirements/?frameworks[]=b698a0ed-ad82-4468-900e-3b6eb3f5eb9b&applicability[]=true&controls[]=with_no_controls' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-TOKEN'

Example response:

Status 200

{
    "data": [
        {
            "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "title": "Information Security Policy",
            "chapter_name": "Organizational Controls",
            "chapter_number": "5",
            "paragraph_number": "5.1",
            "is_applicable": true,
            "regulations": [
                {
                    "id": "b698a0ed-ad82-4468-900e-3b6eb3f5eb9b",
                    "title": "ISO 27001:2022"
                }
            ]
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 25,
        "total_count": 1,
        "total_pages": 1
    }
}

---

PATCH /requirements/:id

Update an existing requirement.

Field	Type	Required	Description
title	string	No	The title of the requirement.
regulation_ids	array	No	Array of framework IDs this requirement belongs to.
description	string	No	Rich-text description (HTML supported).
chapter_name	string	No	Name of the chapter/section.
chapter_number	string	No	Chapter/section number.
paragraph_number	string	No	Paragraph number within the chapter.
meaning	string	No	Explanation of what the requirement means.
label_ids	array	No	Array of label UUIDs to attach.
is_applicable	boolean	No	Whether this requirement is applicable.

curl --location --request PATCH 'https://YOUR_KORDON_DOMAIN/api/v1/requirements/a1b2c3d4-e5f6-7890-abcd-ef1234567890' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-TOKEN' \
--data '{
    "requirement": {
        "title": "Information Security Policy (Updated)",
        "is_applicable": false
    }
}'

Example response:

Status 200

{
    "data": {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "title": "Information Security Policy (Updated)",
        "is_applicable": false,
        "updated_at": "2024-08-29T09:15:00+00:00"
    }
}

---

DELETE /requirements/:id

Delete a requirement.

curl --location --request DELETE 'https://YOUR_KORDON_DOMAIN/api/v1/requirements/a1b2c3d4-e5f6-7890-abcd-ef1234567890' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-TOKEN'

Example response:

Status 200

{
    "data": {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "deleted": true
    }
}