Item API

API to manage configuration items and records in Ketryx

Ketryx exposes an API to manage configuration items programmatically. See also the documentation on authentication and API keys and webhooks.

These API endpoints generally use pagination, based on the query parameters startAt and maxResults. The maximum number of entries to return at once is 1000. The effective values of startAt and maxResults is also returned as part of the API response.

Items

Read all items in a project

get

Path parameters

projectIdstringRequired

Ketryx ID of the project to query items for

Query parameters

startAtintegerOptional

Index to start at. Defaults to 0.

Default: 0

maxResultsinteger · min: 1 · max: 1000Optional

Maximum number of results to return

Default: 1000

Responses

200

Successful response

application/json

default

Error response

application/json

get

HTTPcURLJavaScriptPython

GET /api/v1/projects/{projectId}/items HTTP/1.1
Host: app.ketryx.com
Accept: */*

{
  "items": [
    {
      "id": "text",
      "externalIds": [
        {
          "system": "Ketryx",
          "id": "text",
          "key": "text",
          "projectId": "text",
          "url": "text"
        }
      ],
      "createdAt": "2025-06-20T11:55:58.055Z",
      "isExcluded": true,
      "folderPath": [
        "text"
      ],
      "currentRecord": {
        "id": "text"
      },
      "controlledRecord": {
        "id": "text"
      }
    }
  ],
  "startAt": 1,
  "maxResults": 1
}

Item records

The fields query parameter allows you to selectively include additional data in the response. You can specify one or more fields as a comma-separated list (e.g., fields=approvalState,otherField). Available fields include:

• approvalState: Returns detailed approval information including approval steps, approving users, and approval blockers

Read all item records for an item

get

Path parameters

projectIdstringRequired

Ketryx ID of the project

itemIdstringRequired

Ketryx ID of the item

Query parameters

fieldsstringOptional

startAtintegerOptional

Index to start at. Defaults to 0.

Default: 0

maxResultsinteger · min: 1 · max: 1000Optional

Maximum number of results to return

Default: 1000

Responses

200

Successful response

application/json

default

Error response

application/json

get

HTTPcURLJavaScriptPython

GET /api/v1/projects/{projectId}/items/{itemId}/records HTTP/1.1
Host: app.ketryx.com
Accept: */*

{
  "records": [
    {
      "id": "text",
      "itemId": "text",
      "type": "text",
      "title": "text",
      "isControlled": true,
      "revision": 1,
      "createdAt": "2025-06-20T11:55:58.055Z",
      "introducedInVersion": {
        "id": "text",
        "name": "text"
      },
      "obsoleteInVersion": {
        "id": "text",
        "name": "text"
      },
      "fields": [
        {
          "label": "text",
          "type": "string",
          "value": null
        }
      ],
      "relations": [
        {
          "type": "text",
          "toItem": {
            "id": "text",
            "projectId": "text"
          }
        }
      ],
      "fileUrl": "text",
      "approvalState": {
        "steps": [
          {
            "name": "text",
            "type": "group",
            "group": {
              "id": "text",
              "name": "text"
            },
            "users": [
              {
                "id": "text",
                "email": "text"
              }
            ],
            "approvingUsers": [
              {
                "id": "text",
                "email": "text"
              }
            ],
            "isFullyApproved": true,
            "minApprovals": 1
          }
        ],
        "designInputsBlockingApproval": [
          {
            "id": "text",
            "projectId": "text"
          }
        ],
        "instructionText": "text",
        "invalidFields": [
          "text"
        ],
        "milestoneBlockingApproval": {
          "id": "text",
          "name": "text"
        }
      }
    }
  ],
  "startAt": 1,
  "maxResults": 1
}

Query project records

The fields query parameter allows you to selectively include additional data in the response. You can specify one or more fields as a comma-separated list (e.g., fields=approvalState,otherField). Available fields include:

• approvalState: Returns detailed approval information including approval steps, approving users, and approval blockers

Use this API to query records based on a KQL query.

Query item records in a project

get

Path parameters

projectIdstringRequired

Ketryx ID of the project

Query parameters

versionIdstringOptional

comparedVersionIdstringOptional

fieldsstringOptional

querystringRequired

KQL query string

startAtintegerOptional

Index to start at. Defaults to 0.

Default: 0

maxResultsinteger · min: 1 · max: 1000Optional

Maximum number of results to return

Default: 1000

Responses

200

Successful response

application/json

default

Error response

application/json

get

HTTPcURLJavaScriptPython

GET /api/v1/projects/{projectId}/records HTTP/1.1
Host: app.ketryx.com
Accept: */*

{
  "records": [
    {
      "id": "text",
      "itemId": "text",
      "type": "text",
      "title": "text",
      "isControlled": true,
      "revision": 1,
      "createdAt": "2025-06-20T11:55:58.055Z",
      "introducedInVersion": {
        "id": "text",
        "name": "text"
      },
      "obsoleteInVersion": {
        "id": "text",
        "name": "text"
      },
      "fields": [
        {
          "label": "text",
          "type": "string",
          "value": null
        }
      ],
      "relations": [
        {
          "type": "text",
          "toItem": {
            "id": "text",
            "projectId": "text"
          }
        }
      ],
      "fileUrl": "text",
      "approvalState": {
        "steps": [
          {
            "name": "text",
            "type": "group",
            "group": {
              "id": "text",
              "name": "text"
            },
            "users": [
              {
                "id": "text",
                "email": "text"
              }
            ],
            "approvingUsers": [
              {
                "id": "text",
                "email": "text"
              }
            ],
            "isFullyApproved": true,
            "minApprovals": 1
          }
        ],
        "designInputsBlockingApproval": [
          {
            "id": "text",
            "projectId": "text"
          }
        ],
        "instructionText": "text",
        "invalidFields": [
          "text"
        ],
        "milestoneBlockingApproval": {
          "id": "text",
          "name": "text"
        }
      }
    }
  ],
  "startAt": 1,
  "maxResults": 1,
  "total": 1
}