Bring your own exports
The desk never fetches Amazon data. It reads three CSVs and exposes the result over a small JSON API. Everything below is the actual contract, not an aspiration.
The three CSVs
1 · Earnings — Associates report
One row per ASIN and period. Required: an ASIN column. Recognised: period, units, revenue, commission. Aliases include product asin, child asin, units sold, ordered revenue, total earnings.
Used for: adjacency per category, on_my_storefront, and the later precision measurement.
2 · Campaigns — Creator Connections history
One row per ASIN and campaign. Required: ASIN. Recognised: campaign, brand, commission_pct, total_budget, remaining_budget, start_date, end_date.
Used for: commission per sale, budget health, sample likelihood, outreach grouping by brand.
3 · Products — the enrichment sheet
One row per ASIN. Required: ASIN. Recognised: parent_asin, title, brand, price, monthly_units, rating, reviews, influencer_videos, category. Any research tool that can export those columns works; so does a spreadsheet filled by hand.
This is the only route to the sales and competition signals, which is why the desk shows coverage on every row.
Header matching
- Headers are normalised: lower-case, punctuation collapsed, BOM stripped.
- Delimiter is detected: comma, tab, semicolon or pipe.
- Money is parsed with currency symbols, thousands separators and accounting negatives.
- An ASIN is accepted bare or inside a
/dp/link. - Rows without a valid ASIN are skipped and counted; a file with no ASIN column is rejected with the columns it did see.
- Re-uploading the identical file is detected by SHA-256 and changes nothing.
- Product rows merge: a sparse second sheet never blanks a value that was already known.
API v1
| Method | Path | Returns |
|---|---|---|
| GET | /api/v1/health | Public liveness and score version |
| GET | /api/v1/stats | Counts, flag histogram, average coverage |
| GET | /api/v1/products?flag=&q=&limit= | Ranked rows with components and outreach state |
| GET | /api/v1/export.csv | Ranked CSV, same columns as the console export |
| POST | /api/v1/score | Recompute all rows; returns run statistics |
| POST | /api/v1/ingest | Multipart kind + file; same parser as the console |
All but health require an operator session and, for POST, the CSRF token in the form field csrf or the X-CSRF-Token header. The token is rendered into the console pages; it is bound to the signed session cookie.
Authentication
Pocket ID at auth.kituwa.com, authorization code with PKCE S256, a single-use transaction and a verified ID token. Only subjects whose Pocket ID client is scoped to the operators group are accepted. The session cookie is HMAC-signed, HttpOnly, Secure, SameSite=Lax, and lasts 8 hours. There is no password on this site and no consumer account.
Errors and limits
- JSON errors are
{"error": "..."}with a 4xx status; HTML routes render a page. - Upload limit is set by
RESEARCH_MAX_BODY_BYTES(12 MB by default) and enforced before the body is read. - Sign-in is rate limited per client address; imports are limited per operator per hour.
- Every import and score run is written to the run log with its summary.
MCP
No MCP server is published for this desk. The data is one operator's private earnings; a remote model session is the wrong client for it. The listed machine surface is the v1 API above, recorded with the Kituwa Toolbox interface row.