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

GEThttps://app.ketryx.com/api/v1/projects/{projectId}/items

Path parameters

projectId*string

Ketryx ID of the project to query items for

Query parameters

Response

200default

Successful response

Body

application/json

items*array of object

List of items

startAt*number

maxResults*number

Request

JavaScriptCurlPython

const response = await fetch('https://app.ketryx.com/api/v1/projects/{projectId}/items', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200default

{
  "items": [
    {
      "id": "text",
      "externalIds": [
        {
          "system": "Jira",
          "id": "text",
          "key": "text",
          "projectId": "text"
        }
      ],
      "createdAt": "2024-12-21T15:58:50.182Z",
      "isExcluded": false,
      "folderPath": [
        "text"
      ],
      "currentRecord": {
        "id": "text"
      },
      "controlledRecord": {
        "id": "text"
      }
    }
  ],
  "startAt": 0,
  "maxResults": 0
}

Item records

Read all item records for an item

GEThttps://app.ketryx.com/api/v1/projects/{projectId}/items/{itemId}/records

Path parameters

projectId*string

Ketryx ID of the project

itemId*string

Ketryx ID of the item

Query parameters

Response

200default

Successful response

Body

application/json

records*array of object

List of records

startAt*number

maxResults*number

Request

JavaScriptCurlPython

const response = await fetch('https://app.ketryx.com/api/v1/projects/{projectId}/items/{itemId}/records', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200default

{
  "records": [
    {
      "id": "text",
      "itemId": "text",
      "type": "text",
      "title": "text",
      "isControlled": false,
      "revision": 0,
      "createdAt": "2024-12-21T15:58:50.182Z",
      "introducedInVersion": {
        "id": "text",
        "name": "text"
      },
      "obsoleteInVersion": {
        "id": "text",
        "name": "text"
      },
      "fields": [
        {
          "label": "text",
          "type": "string"
        }
      ],
      "relations": [
        {
          "type": "text",
          "toItem": {
            "id": "text",
            "projectId": "text"
          }
        }
      ],
      "fileUrl": "text"
    }
  ],
  "startAt": 0,
  "maxResults": 0
}

Query project records

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

Query item records in a project

GEThttps://app.ketryx.com/api/v1/projects/{projectId}/records

Path parameters

projectId*string

Ketryx ID of the project

Query parameters

Response

200default

Successful response

Body

application/json

records*array of object

Matching records

startAt*number

Index that the pagination started at

maxResults*number

Maximum number of items that were returned

total*number

Total number of items matching the query

Request

JavaScriptCurlPython

const response = await fetch('https://app.ketryx.com/api/v1/projects/{projectId}/records?query=text', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200default

{
  "records": [
    {
      "id": "text",
      "itemId": "text",
      "type": "text",
      "title": "text",
      "isControlled": false,
      "revision": 0,
      "createdAt": "2024-12-21T15:58:50.182Z",
      "introducedInVersion": {
        "id": "text",
        "name": "text"
      },
      "obsoleteInVersion": {
        "id": "text",
        "name": "text"
      },
      "fields": [
        {
          "label": "text",
          "type": "string"
        }
      ],
      "relations": [
        {
          "type": "text",
          "toItem": {
            "id": "text",
            "projectId": "text"
          }
        }
      ],
      "fileUrl": "text"
    }
  ],
  "startAt": 0,
  "maxResults": 0,
  "total": 0
}