---
search:
  tags:
    - V1
    - POST
seo:
  description: >-
    Create one evidence-backed issue. A duplicate issue_key returns a… Reference
    for the POST /v1/projects/{projectId}/issues endpoint in the Judgeval API.
sidebar:
  label: Create issue
  badge: POST
title: Create issue
type: openapi-operation
---
Create one evidence-backed issue. A duplicate issue_key returns a conflict.

`POST /v1/projects/{projectId}/issues`

**Request body** (`application/json`, required)

- `issue_key` (string) — Stable root-cause key: lowercase letters, digits, hyphens, and colons.
- `title` (string, required) — Short issue title.
- `diagnosis` (string, required) — 1–2 short sentences describing the observed failure, with inline trace and relevant signal citations. Omit fixes and investigation history.
- `impact_summary` (string | null) — 2–3 Markdown bullets on impact, scope, frequency, trends, and material uncertainty. Quantify how often contributing labels were applied, and any other judge signals, with inline citations. Combine related facts; omit immaterial unknowns and labeled checklists.
- `priority` (string)
- `production_activity` (string)
- `agent_reasoning` (string | null) — 1–3 Markdown bullets suggesting evidence-backed remediation. Omit repeated evidence and claims of an exact cause or fix.
- `cited_items` (object[], required) — Cite every supporting trace with a one-sentence failure description in its \`label\` field and an optional short quote. Add a span or trace-behavior citation for each contributing location, using the same trace\_id and real span\_id when available; use trace-only evidence only when no deeper location is reliable. For contributing label or judge signals, include their citation with the stable name in its \`label\` field and matching trace-behavior verdicts with tool-returned behavior\_id/judge\_id and value. Cite the label itself with type "behavior" (behavior\_id) and its verdict on a trace with type "trace-behavior". Put changing metrics and confidence in impact\_summary.

Request body example:

```json
{
  "issue_key": "string",
  "title": "string",
  "diagnosis": "string",
  "impact_summary": "string",
  "priority": "low",
  "production_activity": "new",
  "agent_reasoning": "string",
  "cited_items": [
    {
      "type": "string",
      "property1": null,
      "property2": null
    }
  ]
}
```

**Responses**

- `200` — Response for status 200

Response example, 200:

```json
{
  "issue": {
    "id": "string",
    "issue_key": "string"
  }
}
```