Controls API

Manage your organization’s security controls, policies, procedures, and their effectiveness monitoring.

GET /controls/

List all controls with optional filtering.

Query Parameters

Parameter	Type	Description
kind[]	array	Filter by control type: policy, procedure, technical, physical.
state[]	array	Filter by state: not_implemented, implemented, failing.
owner[]	array	Filter by owner user IDs.
labels[]	array	Filter by label IDs. Use none for controls without labels.

Array parameters

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

?state[]=implemented&state[]=failing&kind[]=policy

curl --location GET \
--url "https://YOUR_KORDON_DOMAIN/api/v1/controls/" \
--header "Authorization: Bearer YOUR-TOKEN"

Example with filters:

curl --location GET \
--url "https://YOUR_KORDON_DOMAIN/api/v1/controls/?state[]=failing&kind[]=policy&kind[]=procedure" \
--header "Authorization: Bearer YOUR-TOKEN"

Example Response

Status: 200

{
    "data": [
        {
            "id": "18211d00-904f-4ca9-a212-1e616a687d83",
            "assets": [],
            "begins_at": "2025-03-24T00:00:00+00:00",
            "created_at": "2025-03-24T09:02:24+00:00",
            "description": "<p><strong>1. Purpose</strong></p><p>The purpose of this Acceptable Use Policy is to establish guidelines for the appropriate use of the Company's information systems...</p>",
            "findings": [
                {
                    "id": "064ad39e-0f7f-479f-a239-5b4e30713a16",
                    "kind": "ncr",
                    "state": "open",
                    "title": "Start monitoring controls effect on risks in Kordon"
                }
            ],
            "kind": "policy",
            "labels": [],
            "owner": {
                "id": "58e7bf6e-618e-4c87-81fb-31b5ecee2d41",
                "active": true,
                "color": "#F5222D",
                "kind": "person",
                "name": "Rusty Ryan"
            },
            "permissions": {
                "update": true,
                "destroy": true,
                "connect": true,
                "changelog": true
            },
            "requirements": [
                {
                    "id": "9c70579f-fc76-4908-af69-7d9fdb3e8bf2",
                    "is_applicable": true,
                    "regulations": [
                        {
                            "id": "f1c874ec-4dcf-4603-a339-767094cdc5ce",
                            "is_custom": false,
                            "title": "ISO 27001:2022"
                        }
                    ],
                    "title": "Actions to address risks and opportunities"
                }
            ],
            "risks": [],
            "state": "not_implemented",
            "tasks": [],
            "title": "Acceptable Use Policy",
            "updated_at": "2025-10-29T15:14:06+00:00",
            "vendors": []
        }
    ],
    "meta": {
        "total_count": 60,
        "page": 1,
        "permissions": {
            "create": true
        },
        "per_page": "10"
    }
}

GET /controls/:id

Retrieve a specific control by ID.

curl --location GET \
--url "https://YOUR_KORDON_DOMAIN/api/v1/controls/18211d00-904f-4ca9-a212-1e616a687d83" \
--header "Authorization: Bearer YOUR-TOKEN"

Example Response

Status: 200

{
    "data": {
        "id": "5e440b94-87c9-4bd9-9b04-65095439760e",
        "assets": [],
        "begins_at": "2024-05-16T00:00:00+00:00",
        "created_at": "2024-05-15T09:15:34+00:00",
        "description": "<p><strong>1. Purpose</strong></p><p>The purpose of this Code of Conduct is to outline the ethical principles...</p>",
        "findings": [
            {
                "id": "064ad39e-0f7f-479f-a239-5b4e30713a16",
                "kind": "ncr",
                "state": "open",
                "title": "Start monitoring controls effect on risks in Kordon"
            }
        ],
        "kind": "policy",
        "labels": [],
        "owner": {
            "id": "58e7bf6e-618e-4c87-81fb-31b5ecee2d41",
            "active": true,
            "color": "#F5222D",
            "kind": "person",
            "name": "Rusty Ryan"
        },
        "permissions": {
            "update": true,
            "destroy": true,
            "connect": true,
            "changelog": true
        },
        "requirements": [
            {
                "id": "690a7009-38ea-4935-a139-f1b495e46d56",
                "is_applicable": true,
                "regulations": [
                    {
                        "id": "fce9d4d7-ffae-4aa1-84ac-941288d75ba4",
                        "is_custom": false,
                        "title": "SOC 2"
                    }
                ],
                "title": "Attract, Develop, Retain Personnel in Line with Security Objectives"
            }
        ],
        "risks": [
            {
                "id": "3efe0045-3562-4aa5-96bd-b17f13c4de79",
                "state": "acceptable",
                "title": "DDoS attack"
            }
        ],
        "state": "failing",
        "tasks": [
            {
                "id": "365077f9-028c-4162-8477-3b85fcfd86ac",
                "assignee": {
                    "id": "58e7bf6e-618e-4c87-81fb-31b5ecee2d41",
                    "active": true,
                    "color": "#F5222D",
                    "kind": "person",
                    "name": "Rusty Ryan"
                },
                "kind": "review",
                "state": "new",
                "title": "Annual review of Code of Conduct"
            }
        ],
        "title": "Code of Conduct",
        "updated_at": "2025-11-13T12:32:25+00:00",
        "vendors": []
    }
}

POST /controls/

Create a new control.

Required Parameters:

• title - Control title
• owner_id - User ID of the control owner
• kind - Control type (policy, procedure, or technical)
• begins_at - Date when the control begins (ISO 8601 format)

Optional Parameters:

• description - Detailed description of the control (HTML supported)
• state - Control state (defaults to not_implemented)

curl --location POST \
--url "https://YOUR_KORDON_DOMAIN/api/v1/controls/" \
--header "Authorization: Bearer YOUR-TOKEN" \
--header "Content-Type: application/json" \
--data '{
    "control": {
        "title": "Data Encryption Policy",
        "begins_at": "2025-11-12T00:00:00+00:00",
        "kind": "policy",
        "owner_id": "844596ff-8942-4704-b0cd-3e853921d71b"
    }
}'

PATCH /controls/:id

Update an existing control.

curl --location PATCH \
--url "https://YOUR_KORDON_DOMAIN/api/v1/controls/18211d00-904f-4ca9-a212-1e616a687d83" \
--header "Authorization: Bearer YOUR-TOKEN" \
--header "Content-Type: application/json" \
--data '{
    "state": "operating_effectively"
}'

Example Response

Status: 200

The response will include the full data of the updated control.

Connect a Task to a Control

To connect a task to a control, update the task’s taskable_id to reference the control ID. See the Tasks API for full details.

PATCH /tasks/:task_id

curl --location PATCH \
--url "https://YOUR_KORDON_DOMAIN/api/v1/tasks/task-id-here" \
--header "Authorization: Bearer YOUR-TOKEN" \
--header "Content-Type: application/json" \
--data '{
    "task": {
        "taskable_id": "18211d00-904f-4ca9-a212-1e616a687d83"
    }
}'

This will link the task to the control, making it appear in the control’s tasks list.

DELETE /controls/:id

Remove a control.

curl --location DELETE \
--url "https://YOUR_KORDON_DOMAIN/api/v1/controls/18211d00-904f-4ca9-a212-1e616a687d83" \
--header "Authorization: Bearer YOUR-TOKEN"

Example Response

Status: 200

{
    "data": {
        "id": "18211d00-904f-4ca9-a212-1e616a687d83"
    }
}

Control Types

Available control types (kind):

• policy - Organizational policy document
• procedure - Standard operating procedure
• technical - Technical security control

Control States

Available control states:

• not_implemented - Control has not been implemented yet
• implemented - Control has been implemented
• failing - Control is not operating effectively

Relationships

Controls can be related to:

• Assets - Information assets protected by the control
• Risks - Risks that the control helps mitigate
• Requirements - Compliance requirements the control addresses
• Findings - Audit findings or non-conformities related to the control
• Vendors - Third-party vendors involved in the control
• Tasks - Maintenance, review, or audit tasks for the control

Permissions

The permissions object indicates what actions the current user can perform:

• update - Can modify the control
• destroy - Can delete the control
• connect - Can link the control to other objects
• changelog - Can view the control’s change history