Data & API · v1

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

MethodPathReturns
GET/api/v1/healthPublic liveness and score version
GET/api/v1/statsCounts, flag histogram, average coverage
GET/api/v1/products?flag=&q=&limit=Ranked rows with components and outreach state
GET/api/v1/export.csvRanked CSV, same columns as the console export
POST/api/v1/scoreRecompute all rows; returns run statistics
POST/api/v1/ingestMultipart 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.