# API Reference + Integration Guide (PR12)

Per DESIGN: authenticated `POST /api/v1/reports` for auto-crash ingestion from games/apps/SDKs.

Base: under your product vhost e.g. `https://starminer.bugz.report/api/v1/...` (Host-based multi-tenant; or via marketing apex if routed).

All new user-facing API error strings are localized (human "error" + stable "error_code" for machines/SDKs). See l10n arch.

SDK examples (Python and Node.js JavaScript in `sdk/`) accept `locale` or infer it from the runtime environment, then pass it via `Accept-Language`.

## Authentication

Use a per-product API key. Initial keys are generated during product approval, and the product API becomes available after activation. Dashboard-created replacement keys are shown once.

Header: `X-Api-Key: bz_live_<generated-key>`

Internal storage: HMAC-SHA256 using `BUGZ_API_KEY_SECRET`; only prefix, last4, hash, and lifecycle metadata are persisted.

## POST /api/v1/reports

Ingest crash or bug report (same as public form path, but automated).

**Request**

- Headers: `X-Api-Key`, `Accept-Language: <bcp47>` (optional; defaults to en or negotiated; affects response "error" localization)
- Body: JSON or multipart form-data. Use JSON for pure crash text/metadata; use multipart when sending log files or screenshots.
  ```json
  {
    "product": "starminer",
    "version": "1.2.3",
    "platform": "android-14" | "win11" | "linux",
    "log": "full crash log text here (or base64 if binary small)",
    "metadata": { "extra": "optional" },
    "title": "optional short title",
    "screenshot_b64": "optional small base64 png"  // size limited
  }
  ```

  Multipart fields use the same scalar names (`product`, `title`, `description`,
  `version`, `severity`, `metadata`, `platform`). Send `metadata` and `platform`
  as JSON strings. File fields may be named `logfile`/`log` for logs and
  `screenshot`/`image`/`shot` for screenshots. Attachments are stored under the
  product/report attachment root and exposed back through safe metadata only.

**Success 200**

```json
{ "report_id": "uuid", "status": "accepted" }
```

Report appears in dashboard immediately (for owner).

**Errors (localized human + stable code)**

- 401: `{"error_code": "INVALID_KEY", "error": "Invalid API key"}`  ( "error" localized e.g. de: "Ungültiger API-Schlüssel" )
- 400: `{"error_code": "MISSING_PRODUCT", "error": "product is required"}` when `product`/`slug` is omitted
- 429: rate limit (per key + IP)
- 413: too large
- etc. Always include `error_code` for SDK parsing (ignore human if machine client).

See also `/api/v1/aggregates/summary?product=...` for real persisted counts, breakdowns, time series, and top signatures scoped to the API key's product.

## Integration with SDKs

Use the provided server-side examples in `sdk/python/` and `sdk/js/`:

- `example_crash.py --key ... --slug ... --log crash.log --locale pt-BR`
- `node example_crash.js --key ... --slug ... --log crash.log --locale pt-BR`
- They include the required `product` field, handle locale negotiation, and POST the crash report.

The JavaScript example is for Node.js/server automation. Browser-origin API-key
submissions are intentionally unsupported in v1 because `/api/v1/*` does not
emit permissive CORS headers and API keys must not be exposed to untrusted
reporter browsers. A browser SDK would require a future per-product
`allowed_origins` allow-list and a different key-exposure model.

Example direct (curl):

```sh
curl -X POST https://starminer.bugz.report/api/v1/reports \
  -H "X-Api-Key: bz_live_..." \
  -H "Accept-Language: ja" \
  -H "Content-Type: application/json" \
  -d '{"product":"starminer","log":"NullPointer at Foo.java:42\n...","version":"0.9","platform":"android"}'
```

Response localized if error.

## Generated Output Note (per DESIGN v1 + PR9)

The platform produces "generated output":
- Aggregates: time series volume, OS/version/browser breakdowns.
- Top signatures: simple fingerprint (hash title+first frame/normalized log) for clustering crashes.
- Visible in dashboard aggregates tab / report list groupings.
- "Powerful insights" without extra work from SDK (just send raw logs).

Future: symbolication, better ML clustering post-v1.

## Full Localization Notes (cross-cutting, PR12 delight)

- SDK locale param / runtime auto-detection sets Accept-Language → human strings in errors/responses use gettext for the 8 langs.
- Reporter confirmations (if contact) use submit-time negotiated locale.
- Dev dashboard uses `preferred_locale`.
- All API docs/examples note the locale support.
- High-quality translations (human preferred) for error strings, to delight international devs using SDKs.

See:
- docs/i18n.md (full workflow, extraction, placeholder safety)
- DESIGN.md (Localization Architecture, SDKs section, API section)
- app/api.py (impl of locale dep + _() in errors)
- sdk/ examples

## OpenAPI

Developer-gated schema is available at `/api/v1/openapi.json` after login. The
default FastAPI `/docs`, `/redoc`, and `/openapi.json` routes are disabled so
API discovery is not exposed publicly. Interactive Swagger UI is intentionally
not enabled until the UI assets are packaged with the service and compatible
with the production CSP.

## Rate Limiting / Abuse

Per-key + IP. SDKs should implement backoff.

## Privacy

Minimal PII in payloads; logs scrubbed client-side if possible.

## Webhooks

Product webhooks emit `report.created` as a JSON envelope with `event_id`,
`event_type`, `created_at`, and `data`. Verify `X-Bugz-Signature` as
`t=<unix_seconds>,v1=<hmac_sha256(secret, f"{t}.{raw_body}")>` with a
five-minute timestamp tolerance, and dedupe deliveries by `event_id`.
Non-2xx responses and transport failures are stored in `webhook_deliveries`
and retried by the `bugz-webhook-retry.timer` worker with capped backoff.

Webhook URLs must be HTTPS on the default port. The app rejects localhost,
private/link-local/reserved IP literals, metadata IPs, embedded credentials, and
non-standard ports before storing or delivering a webhook.

## Next / SDK Polish

- Official packages on PyPI/npm later.
- Packaged SDK helpers for multipart attachments.
- Webhook verification helpers.
- Typed clients.
- Browser SDK support only after an explicit per-product CORS allow-list and
  safe public-token design exist.

For now: copy examples, they work against the live API after product activation and a dashboard API key.

## Testing the API (local)

Use the test client or:

```python
# see tests/integration/...
```

All API paths covered by i18n tests (localized errors).

*This completes the SDKs + docs portion of PR12.*