---
title: "POST /api/v1/projects/{project_id}/issues"
method: POST
path: "/api/v1/projects/{project_id}/issues"
---

# POST /api/v1/projects/{project_id}/issues

`POST /api/v1/projects/{project_id}/issues`

## Path parameters

- `project_id` string, required — Numeric project ID or name:<project name>; name: alone requires an alias

## Headers

- `X-Kata-Project-Alias` string — Workspace alias identity; requires a name: selector
- `X-Kata-Project-Alias-Kind` string — Workspace alias kind; required with X-Kata-Project-Alias
- `Idempotency-Key` string

## Request body

- CreateIssueRequestBody
  - `actor` string
  - `body` string
  - `force_new` boolean
  - `labels` string[]
  - `links` CreateInitialLinkBody[]
    - `incoming` boolean
    - `to_project_uid` string
    - `to_ref` string, required
    - `type` 'parent' | 'blocks' | 'related', required
  - `metadata` object
  - `owner` string
  - `priority` integer
  - `title` string, required

## Response `200`

OK

- MutationResponseBody
  - `changed` boolean, required
  - `event` Event, required
    - `actor` string, required
    - `content_hash` string, required
    - `created_at` string, date-time, required
    - `hlc_counter` integer, required
    - `hlc_physical_ms` integer, required
    - `id` integer, required
    - `issue_id` integer
    - `issue_short_id` string
    - `issue_uid` string
    - `origin_instance_uid` string, required
    - `payload` string, required
    - `project_id` integer, required
    - `project_name` string, required
    - `project_uid` string, required
    - `related_issue_id` integer
    - `related_issue_short_id` string
    - `related_issue_uid` string
    - `type` string, required
    - `uid` string, required
  - `issue` Issue, required
    - `assignment_expires_on` string, date-time
    - `author` string, required
    - `body` string, required
    - `closed_at` string, date-time
    - `closed_reason` string
    - `created_at` string, date-time, required
    - `deleted_at` string, date-time
    - `id` integer, required
    - `metadata` object, required
    - `occurrence_key` string
    - `owner` string
    - `priority` integer
    - `project_id` integer, required
    - `project_uid` string
    - `recurrence_id` integer
    - `revision` integer, required
    - `short_id` string, required
    - `status` string, required
    - `title` string, required
    - `uid` string, required
    - `updated_at` string, date-time, required
  - `original_event` Event
    - `actor` string, required
    - `content_hash` string, required
    - `created_at` string, date-time, required
    - `hlc_counter` integer, required
    - `hlc_physical_ms` integer, required
    - `id` integer, required
    - `issue_id` integer
    - `issue_short_id` string
    - `issue_uid` string
    - `origin_instance_uid` string, required
    - `payload` string, required
    - `project_id` integer, required
    - `project_name` string, required
    - `project_uid` string, required
    - `related_issue_id` integer
    - `related_issue_short_id` string
    - `related_issue_uid` string
    - `type` string, required
    - `uid` string, required
  - `reused` boolean

## Other responses

- `default` — Error

## Changes

- **2026-09-19** `62eb7bbfff42` — 1 info
  - added the optional property `issue/assignment_expires_on` to the response with the `200` status
- **2026-09-08** `f0017a33d9be` — 3 info
  - added the new optional `header` request parameter `X-Kata-Project-Alias`
  - added the new optional `header` request parameter `X-Kata-Project-Alias-Kind`
  - for the `path` request parameter `project_id`, the type was generalized from `integer` to `string`, and format from `int64` to no format
- **2026-09-05** `12b3e0f9f6ad` — 2 breaking
  - the request property `labels` became not nullable
  - the request property `links` became not nullable
- **2026-08-15** `d111dd43f594` — 1 info
  - added the new optional request property `links/items/to_project_uid`
- **2026-08-05** `1a5a27920493` — 1 info
  - the request property `actor` became optional

[Full history](https://skmtc.dev/kenn-io/apis/kata/changes/api/v1/projects/:project_id/issues/post.md)

---

[API](https://skmtc.dev/kenn-io/apis/kata.md) · [All operations](https://skmtc.dev/kenn-io/apis/kata/llms.txt) · [OpenAPI document](https://skmtc.dev/kenn-io/apis/kata/revisions/8524b3f37543?raw)