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

/projects/{projectId}/items

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": "2026-01-14T07:42:56.125Z",
      "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

/projects/{projectId}/items/{itemId}/records

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": "2026-01-14T07:42:56.125Z",
      "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

/projects/{projectId}/records

HTTPcURLJavaScriptPython

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

{
  "records": [
    {
      "id": "text",
      "itemId": "text",
      "type": "text",
      "title": "text",
      "isControlled": true,
      "revision": 1,
      "createdAt": "2026-01-14T07:42:56.125Z",
      "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
}

Create or update an item

This API endpoint is currently in preview and is accessible only behind a feature flag. Please contact Ketryx Support for assistance.

Depending on the use case, this API can be used in two ways:

• Update an existing item – Include the id field in the request body with the Ketryx item ID (e.g., KXITM12345). Note that if the item is sourced from Jira or other integrations, the source system is considered the source of truth, and the project update may override/reset changes applied via the API.

• Bring your own items – Include the sourceId field in the request body with a stable, unique identifier for the item. If the sourceId already exists, the item will be updated. If not, a new item will be created.

Create or patch an existing item in a project (subject to change)

post

Path parameters

projectIdstringRequired

Ketryx ID of the project, e.g., KXPRJ12345

Pattern: ^KXPRJ[A-Z0-9]{26}

Body

application/json

Responses

200

Successful response

application/json

default

Error response

application/json

post

/projects/{projectId}/items

HTTPcURLJavaScriptPython

POST /api/v1/projects/{projectId}/items HTTP/1.1
Host: app.ketryx.com
Content-Type: application/json
Accept: */*
Content-Length: 205

{
  "itemData": {
    "id": "text",
    "sourceId": "text",
    "type": "text",
    "title": "text",
    "statusName": "text",
    "fields": [
      {
        "label": "text",
        "type": "string",
        "value": "text"
      }
    ],
    "relations": [
      {
        "type": "text",
        "toItem": {
          "id": "text"
        }
      }
    ]
  }
}

{
  "item": {
    "success": true,
    "id": "text",
    "sourceId": "text",
    "currentRecord": {
      "id": "text"
    },
    "warnings": [
      {
        "type": "UNKNOWN_ITEM_TYPE",
        "message": "text",
        "typeName": "text"
      }
    ]
  }
}