android_cast/docs/OPEN_API.md

Crash console — open ingest API (design)

Triage real device crashes vs synthetic / bulk test traffic when exposing upload or query APIs beyond the Android app. Builds on RBAC (examples/crash_reporter/backend/README.md).

Problems

• Load tests and CI may POST many similar JSON blobs → drown signal in the reports list.
• Third-party integrations need stable auth and filters without console login cookies.
• Similarity grouping already uses payload fingerprints; need provenance to exclude known harness traffic.

Payload extension (ingest)

Add optional top-level fields on upload (backward compatible):

Field	Type	Meaning
ingest.source	string	device (default), open_api, ci, manual
ingest.client_id	string	Stable id per API key or CI job
ingest.run_id	string	Correlates a burst of reports from one test run

Android app omits these (defaults to device). Harness sets open_api + run_id.

Store in DB:

• Column reports.ingest_source (indexed) or JSON path in payload_json with generated column later.
• Prefer column for list filters and MariaDB permissions story.

Upload API (POST …/api/upload.php)

Phases:

1. Phase A (now): Accept extra JSON fields; persist inside payload_json; console search includes ingest.source in blob.
2. Phase B: API key header X-Crash-Api-Key → maps to company_id (RBAC); rate limit per key.
3. Phase C: Reject or quarantine when ingest.source=open_api and fingerprint matches org blocklist.

Console / query API (read)

Thin JSON endpoints (session or API key):

Endpoint	Purpose
GET /api/reports?ingest_source=device	Default triage view
GET /api/reports?ingest_source_ne=open_api	Hide harness
GET /api/reports?group=fingerprint&min_count=N	Bulk duplicate detector
GET /api/reports/{id}	Detail (existing shape)

UI: filter chips on reports toolbar — Devices only / Include API traffic / tag synthetic.

Classifying synthetic traffic (heuristics)

Mark report or tag synthetic when any:

• ingest.source in (open_api, ci) and user has not promoted it.
• Same ingest.run_id + fingerprint count > threshold in 10 minutes.
• Identical report_id prefix pattern from known test fixture.

Manual: console Clear synthetic tag / Promote to real on detail page.

Security

• API keys scoped to company_id; no cross-tenant list.
• Separate write-only keys for CI upload vs read keys for dashboards.
• Log upload failures to existing crash event log; no stack traces in response body.

Android

No change required for v1. Optional later: dev setting to set ingest.source=manual for dogfood builds.

Implementation order

1. Document fields; parse and store in payload (Phase A).
2. List filter ingest_source in ReportRepository + UI chip.
3. API keys table + X-Crash-Api-Key on upload.
4. Grouped bulk endpoint for duplicate review.

See also CRASH_REPORTER.md and examples/crash_reporter/ROADMAP.md.