---
title: "Create or patch an existing item in a project. A write that conflicts with another in-progress write on the same id or sourceId is rejected with 409 and should be retried (subject to change)."
method: POST
path: "/projects/{projectId}/items"
tags: ["Items"]
---

# Create or patch an existing item in a project. A write that conflicts with another in-progress write on the same id or sourceId is rejected with 409 and should be retried (subject to change).

`POST /projects/{projectId}/items`

## Request

- Base URL: `https://app.ketryx.com/api/v1`
- URL: `https://app.ketryx.com/api/v1/projects/{projectId}/items`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/ketryx/apis/ketryx-api/docs/projects/:projectId/items/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
  - `itemData` object, required
    - `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
  - `item` object, required
    - `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`.
    - `warnings` union[]: Problems encountered while processing the item
      - union
        - object
          - `type` 'UNKNOWN_ITEM_TYPE', required
          - `message` string, required
          - `typeName` string, required
        - object
          - `type` 'UNKNOWN_ID', required
          - `message` string, required
          - `key` object, required
            - `value` string, required
        - object
          - `type` 'UNKNOWN_FIELD', required
          - `message` string, required
          - `fieldKey` string, required
        - object
          - `type` 'NON_WRITABLE_FIELD', required
          - `message` string, required
          - `fieldKey` string, required
        - object
          - `type` 'COMPUTED_FIELD_ERROR', required
          - `message` string, required
          - `fieldKey` string, required
        - object
          - `type` 'INCOMPATIBLE_FIELD_TYPE', required
          - `message` string, required
          - `fieldKey` string, required
          - `actualType` string, required
          - `expectedType` string, required
        - object
          - `type` 'UNKNOWN_RELATION_TYPE', required
          - `message` string, required
          - `relationType` string, required
        - object
          - `type` 'SINGLE_SELECT_RELATION_CARDINALITY', required
          - `message` string, required
          - `relationType` string, required
        - object
          - `type` 'UNKNOWN_RELATION_TARGET' | 'SELF_REFERENCE', required
          - `message` string, required
          - `relationType` string, required
          - `targetKey` union, required: Identifier of the referenced item
            - object
              - …
            - object
              - …
            - object
              - …
        - object
          - `type` 'STALE_DATA_DETECTED', required
          - `message` string, required
        - object
          - `type` 'DUPLICATE_ITEM_REFERENCE', required
          - `message` string, required
        - object
          - `type` 'INVALID_STATE_TRANSITION', required
          - `message` string, required
        - object
          - `type` 'UNEXPECTED_ERROR', required
          - `message` string, required
        - object
          - `type` 'EXTERNAL_WRITE_BACK_FAILED', required
          - `message` string, required
        - object
          - `type` 'EXTERNAL_RELATION_WRITE_BACK_FAILED', required
          - `message` string, required

## Other responses

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

---

[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)