> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bugspray.io/llms.txt
> Use this file to discover all available pages before exploring further.

# HTTP API and submission reference

> Discover the running contract and use bounded source references for extended APIs.

The API lives at `/api` on the app origin. Local loopback use is credential-free. Protected REST calls use the deployment's supported credential; browser mutations must satisfy the configured same-origin/Host checks. Hosted roles and service scopes also apply. Do not turn off those checks for an API client.

## Discover before submitting

```sh theme={null}
curl --fail-with-body http://127.0.0.1:3737/api/findings/schema
```

`POST /api/findings` uses `multipart/form-data` with JSON text in `metadata`. Use the [quickstart example](https://docs.bugspray.io/quickstart.md) for a complete safe request. Required fields include title, structured description, analysis, analysis confidence, absolute URL, severity from 1–10 and nonempty reproduction steps. The live schema defines exact bounds and optional fields.

Attach files with `screenshot`, `video`, `trace`, `consoleLog`, `networkLog` and `reproScript`. Local multipart counts allow up to 20 screenshots and one of each other field. Read live MIME/size limits. Hosted large files should use MCP or the helper CLI's staged-upload implementation.

```sh theme={null}
curl --fail-with-body http://127.0.0.1:3737/api/findings \
  --form 'metadata=<finding.json' \
  --form 'screenshot=@./artifacts/saved-view.png'
```

The paths must be real inspected evidence. Do not upload synthetic metadata as a verified product failure. Attaching a repro does not execute it. Bad metadata returns descriptive `400` details and `/api/findings/schema` as its help location.

## Choose a reference

| Area | Actual entry points | Maintained contract |
| - | - | - |
| Findings and ingestion | `/api/findings`, `/api/findings/schema`, `/api/ingestion-stats` | [API and repro reference](https://github.com/SynclyUS/bugspray/blob/main/docs/api.md) |
| Products and areas | `/api/products`, `/api/products/:productId/areas`, `/api/product-areas/:areaId` | [Shared catalog schemas](https://github.com/SynclyUS/bugspray/blob/main/apps/shared/catalog.ts) |
| Workflow search/history | `/api/product-workflows`, `/api/product-workflows/:workflowId` | [Search OpenAPI](https://github.com/SynclyUS/bugspray/blob/main/docs/catalog-search.openapi.json), [catalog retrieval](https://github.com/SynclyUS/bugspray/blob/main/apps/shared/catalog-retrieval.ts) |
| Reference videos | Workflow-scoped video/transfer routes | [Video history](https://github.com/SynclyUS/bugspray/blob/main/docs/catalog-video-history.md) |
| Candidate inventory | `/api/suite-inventories`, `/api/suite-inventories/:candidate` | [Registry](https://github.com/SynclyUS/bugspray/blob/main/docs/suite-registry.md) |
| Planning and saved plans | `/api/suite-planning/:candidate`, `/api/suite-plans` | [Plan bridge](https://github.com/SynclyUS/bugspray/blob/main/docs/suite-plan-ci-bridge.md) |
| PR suite report | `/api/pr-runs/:id/suite-validation` | [Report projection](https://github.com/SynclyUS/bugspray/blob/main/docs/pr-suite-reporting.md) |

These links stay in the repository alongside implementation; the site does not duplicate a speculative full OpenAPI document. Older increment prose may describe a pre-bridge state. Executable routes/shared validation and live discovery take precedence.

## Catalog mutation rules

Create operations require a client-generated `requestId`; edits also require the last-read `expectedVersion`. Retry an ambiguous save with the same identity and content. On conflict, reread and reconcile rather than overwriting another editor. Lists default to 20 items, allow up to 100 and return cursors bound to their filters.

Use stable workflow IDs for current lookup and exact workflow/definition pairs for saved expectations. A missing historical pair is unavailable; latest text must not be silently substituted.

## Helper CLI

`pnpm qa-submit` reads `QA_SUITE_URL` as a full findings endpoint and `QA_SUITE_TOKEN` for protected REST calls. Its description/analysis/steps arguments read files; tags and steps are JSON string arrays. It stages remote files before completing submission. Current flags do not select an auth profile; use API/MCP for protected findings. See the [maintained CLI example](https://github.com/SynclyUS/bugspray/blob/main/docs/api.md#helper-cli) for exact flags.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.