---
title: "Report a failure"
method: POST
path: "/api/pitfalldb/report"
tags: ["PitfallDB"]
---

# Report a failure

`POST /api/pitfalldb/report`

## Request

- Base URL: `https://plith.ai`
- URL: `https://plith.ai/api/pitfalldb/report`
- Auth: none required

Submit an agent failure report. All free-text fields are PII-scrubbed before storage. Attempts to link to an existing pitfall via semantic similarity (threshold 0.85). Trust tier: verified orgs (age >= 30 days, >= 500 calls) have reports immediately visible; others require 3+ confirmations. FREE.

## Request body

- object
  - `task_type` string, required
  - `task_description` string, required: Description of the task that failed. PII-scrubbed before storage.
  - `failure` object, required: Details about the failure. All string fields are PII-scrubbed.
    - `error_type` string
    - `error_message` string
    - `root_cause` string
    - `fix_applied` string
    - `fix_worked` boolean
    - `language` string
    - `framework` string
    - `provider` string

## Response `201`

Report stored

- object
  - `report_id` string, uuid, nullable
  - `linked_pitfall_id` string, uuid, nullable: Pitfall this report was linked to, if a semantic match was found.
  - `verified` boolean: true if the org meets the trust tier threshold (age >= 30 days, calls >= 500).
  - `message` string
  - `cross_product` string
  - `request_id` string
  - `credits_used` integer
  - `credits_remaining` integer
  - `fallback_behavior` string

## Other responses

- `400`: Missing task_type, task_description, or failure
- `401`: Invalid or missing API key
- `413`: Payload too large
- `500`: Internal server error

---

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