---
title: "Bulk create or patch items in a project (subject to change)"
method: POST
path: "/projects/{projectId}/items/bulk"
tags: ["Items", "Preview"]
---

# Bulk create or patch items in a project (subject to change)

`POST /projects/{projectId}/items/bulk`

## Request

- Base URL: `https://app.ketryx.com/api/v1`
- URL: `https://app.ketryx.com/api/v1/projects/{projectId}/items/bulk`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/ketryx/apis/ketryx-api/docs/projects/:projectId/items/bulk/post.ts> (a function with typed inputs; its response is checked against the schema)

## Path parameters

- `projectId` string, required: Ketryx ID of the project, e.g., `KXPRJ12345`

## Request body

- object
  - `items` object[], required: Items to create or patch, all in the same project. The request is all-or-nothing: if any item is invalid the whole request is rejected and nothing is written. Item order does not matter — intra-batch relations resolve regardless of order. Each item's id or sourceId must be unique within the request. Max 250 items per request.
    - `id` string, nullable: Ketryx ID of the item, e.g., `KXITM12345`
    - `sourceId` string, nullable: Unique source ID of the item. Use when ingesting data from external systems, e.g., `linear/myProject/AB-123`.
    - `type` string, required: Human-readable name of a system- or custom item type, e.g., `Requirement`.
    - `title` string, required: Title of the item
    - `statusName` string, required: Status of the item, by default, one of: Open, In Progress, Reopened, Resolved, Closed
    - `author` union: Author of the change
      - object
        - `id` string, required: Ketryx ID of the user, e.g., `KXUSR12345`
      - object
        - `email` string, email, required
    - `reporter` union: Reporter of the item
      - object
        - `id` string, required: Ketryx ID of the user, e.g., `KXUSR12345`
      - object
        - `email` string, email, required
    - `assignee` union: Current assignee of the item
      - object
        - `id` string, required: Ketryx ID of the user, e.g., `KXUSR12345`
      - object
        - `email` string, email, required
    - `introducedInVersion` object, nullable: Version this item was introduced in
      - `id` string, required: Ketryx ID of the version, e.g., `KXVSN12345`
    - `obsoleteInVersion` object, nullable: Version this item was obsoleted in
      - `id` string, required: Ketryx ID of the version, e.g., `KXVSN12345`
    - `selectedVersions` object[], nullable: Versions this item is associated with. Use as alternative to a version range; version ranges are preferred.
      - `id` string, required: Ketryx ID of the version, e.g., `KXVSN12345`
    - `fields` union[], nullable: Fields and values for this item
      - union
        - object
          - `label` string, required
          - `type` 'string' | 'select' | 'date', required
          - `value` string, required
        - object
          - `label` string, required
          - `type` 'jdf', required
          - `value` unknown, required
        - object
          - `label` string, required
          - `type` 'multiselect', required
          - `value` string[], required
    - `relations` object[], nullable: Relations to other items
      - `type` string, required: Human-readable name of a system- or custom relation type, e.g., `Related to`.
      - `toItem` union, required: Identifier of the referenced item
        - object
          - `id` string, required: The Ketryx item ID of the target item, e.g., `KXITM12345`.
        - object
          - `sourceId` string, required: The external ID of the target item, e.g., `linear/myProject/AB-123`.
        - object
          - `system` 'ADO' | 'BUILD' | 'GIT' | 'LINEAR' | 'JAMA' | 'JIRA' | 'CONFLUENCE' | 'KETRYX' | 'POLARION' | 'QMETRY' | 'TESTRAIL' | 'GHSA' | 'NVD' | 'JIRA_DATA_CENTER', required: The external system of the target item, e.g., `JIRA`.
          - `value` string, required: The external key of the target item within that system, e.g., `AB-1234`.

## Response `200`

Successful response

- object
  - `items` object[], required: Per-item result, in request order; correlate by `id`/`sourceId`. The request is all-or-nothing, so on success (HTTP 200) every item has `success: true`. Any failure is signaled by the HTTP status code — 400 for an invalid payload (each offending item reported in the `issues` array: position, message, and `params.warningType`/`sourceId`; `INVALID_STATE_TRANSITION` when a status change breaks the transition rules of the project), 409 for a write conflict, 500 for an unexpected error — and nothing is written.
    - `success` boolean, required: Whether the item was created or updated successfully
    - `id` string, nullable, required: Ketryx ID of the item, e.g., `KXITM12345`
    - `sourceId` string: External source ID, e.g., `linear/myProject/AB-123`.
    - `currentRecord` object, nullable, required: Newly created current record of the item
      - `id` string, required: Ketryx record ID. Can be null if creating the item failed, e.g., `KXREC12345`.

## Other responses

- `400`: Invalid input data
- `401`: Authorization not provided
- `403`: Insufficient access
- `500`: Internal server error
- `default`: Error response

---

[API](https://skmtc.dev/ketryx/apis/ketryx-api.md) - [All operations](https://skmtc.dev/ketryx/apis/ketryx-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ketryx/apis/ketryx-api/revisions/a2a484dc35ca?raw)