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

Managing Requirement Connections

Requirements can be connected to Controls, Risks, and Findings.

PATCH /requirements/:id/connections

Update the connections for a requirement.

Connection Parameters

Parameter	Type	Description
control_ids	array	IDs of controls to connect
risk_ids	array	IDs of risks to connect
finding_ids	array	IDs of findings to connect

Partial Updates

Only connection types included in the request are updated. Omitted connection types remain unchanged.

Replacing Connections

When updating a connection type, you must include all IDs you want connected, not just the new ones.

• To add a connection: include all existing IDs plus the new ID
• To remove a connection: include all IDs except the one to remove
• To remove all connections of a type: include an empty array []

Invalid IDs are ignored.

Example: Update requirement connections

curl --location PATCH \
--url "https://YOUR_KORDON_DOMAIN/api/v1/requirements/a1b2c3d4-e5f6-7890-abcd-ef1234567890/connections" \
--header "Authorization: Bearer YOUR-TOKEN" \
--header "Content-Type: application/json" \
--data '{
    "connections": {
        "control_ids": [
            "18211d00-904f-4ca9-a212-1e616a687d83",
            "5e440b94-87c9-4bd9-9b04-65095439760e"
        ],
        "risk_ids": [
            "3efe0045-3562-4aa5-96bd-b17f13c4de79"
        ],
        "finding_ids": [
            "064ad39e-0f7f-479f-a239-5b4e30713a16"
        ]
    }
}'

Example Response

Status: 200

The response returns the full requirement object with all updated connections.