---
title: "File a new bug"
method: POST
path: "/v1/bugs"
tags: ["bugs"]
---

# File a new bug

`POST /v1/bugs`

Create a bug in the API key owner's organization. `source` is forced to `"mcp"` server-side; `user_id` / `organization_id` / `bug_id` are derived from the API key (callers cannot override).

## Headers

- `x-api-key` string

## Request body

- CreateBugBody — Body for POST /v1/bugs. ``source`` is intentionally NOT exposed — this router forces ``source = "mcp"`` server-side. ``user_id`` / ``organization_id`` / ``bug_id`` are likewise server-forced from the API key context.
  - `summary` string, required
  - `steps` string
  - `status` 'open' | 'in_progress' | 'fixed' | 'wont_fix'
  - `app_file_id` string, uuid, nullable — UUID of an uploaded app build in the caller's organization. 404 if not found or cross-org. Accepts any UUID version — Postgres' `uuid` column does too, and gen_random_uuid() happens to produce v4 but we don't want the API enforcing an implementation detail of the underlying RNG.
  - `test_case_id` string, nullable — Written into metadata.test_case_id for downstream attribution.
  - `test_run_id` string, nullable — Written into metadata.test_run_id for downstream attribution.
  - `failure_classification` 'app_bug' | 'setup_issue' — Classifies the issue as an app bug or setup issue.
  - `metadata` object, nullable

## Response `201`

Successful Response

- object

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/qualgent/apis/qualgent-api-service.md) · [All operations](https://skmtc.dev/qualgent/apis/qualgent-api-service/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/qualgent/qualgent-api-service/revisions/2372ed4904a6/schema)