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

/projects/{projectId}/items

Path parameters

projectIdstringrequired

Ketryx ID of the project to query items for

Query parameters

startAtinteger

Index to start at. Defaults to 0.

maxResultsinteger

Maximum number of results to return

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://app.ketryx.com/api/v1/projects/{projectId}/items'

200

default

200

{
  "startAt": 1,
  "maxResults": 1,
  "items": [
    {
      "id": "text",
      "createdAt": "2025-02-15T16:30:27.715Z",
      "isExcluded": true,
      "folderPath": [
        "text"
      ],
      "currentRecord": {
        "id": "text"
      },
      "controlledRecord": {
        "id": "text"
      },
      "externalIds": [
        {
          "id": "text",
          "key": "text",
          "projectId": "text",
          "system": "Jira"
        }
      ]
    }
  ]
}

Successful response

Item records

Read all item records for an item

get

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

Path parameters

projectIdstringrequired

Ketryx ID of the project

itemIdstringrequired

Ketryx ID of the item

Query parameters

startAtinteger

Index to start at. Defaults to 0.

maxResultsinteger

Maximum number of results to return

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://app.ketryx.com/api/v1/projects/{projectId}/items/{itemId}/records'

200

default

200

{
  "startAt": 1,
  "maxResults": 1,
  "records": [
    {
      "id": "text",
      "itemId": "text",
      "type": "text",
      "title": "text",
      "isControlled": true,
      "revision": 1,
      "createdAt": "2025-02-15T16:30:27.715Z",
      "fileUrl": "text",
      "introducedInVersion": {
        "id": "text",
        "name": "text"
      },
      "obsoleteInVersion": {
        "id": "text",
        "name": "text"
      },
      "fields": [
        {
          "label": "text",
          "value": null,
          "type": "string"
        }
      ],
      "relations": [
        {
          "type": "text",
          "toItem": {
            "id": "text",
            "projectId": "text"
          }
        }
      ]
    }
  ]
}

Successful response

Query project records

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

Query item records in a project

get

/projects/{projectId}/records

Path parameters

projectIdstringrequired

Ketryx ID of the project

Query parameters

versionIdstring

comparedVersionIdstring

querystringrequired

KQL query string

startAtinteger

Index to start at. Defaults to 0.

maxResultsinteger

Maximum number of results to return

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://app.ketryx.com/api/v1/projects/{projectId}/records?query=text'

200

default

200

{
  "startAt": 1,
  "maxResults": 1,
  "total": 1,
  "records": [
    {
      "id": "text",
      "itemId": "text",
      "type": "text",
      "title": "text",
      "isControlled": true,
      "revision": 1,
      "createdAt": "2025-02-15T16:30:27.715Z",
      "fileUrl": "text",
      "introducedInVersion": {
        "id": "text",
        "name": "text"
      },
      "obsoleteInVersion": {
        "id": "text",
        "name": "text"
      },
      "fields": [
        {
          "label": "text",
          "value": null,
          "type": "string"
        }
      ],
      "relations": [
        {
          "type": "text",
          "toItem": {
            "id": "text",
            "projectId": "text"
          }
        }
      ]
    }
  ]
}

Successful response