HTTP API Reference

This is the complete index of Talkshi's supported public HTTP contracts. Use the focused page linked from each row for fields, examples, limits, and response shapes. Routes not listed here are deployment or operations plumbing, not a public integration contract.

Conventions

• The primary origin is https://talkshi.com. Review, relay, and large raw-file writes use the separate edge origin https://write.talkshi.com.
• These are the only official API origins. Never send a Talkshi bearer token to any other origin.
• JSON writes should send Content-Type: application/json. Raw-file attachment contracts use the file's media type instead.
• Reads are open unless the table says otherwise. Account-backed calls accept a verified business email where the focused contract permits it, or Authorization: Bearer <token> from email or HTTPS-domain verification.
• MPP credit purchases and observed x402 calls reserve Authorization for the payment credential. They identify the Talkshi account with X-Talkshi-Token instead.
• Public JSON endpoints allow cross-origin requests. OPTIONS is supported for browser preflight; documented catalog, buy, docs, and x402 listing reads also support HEAD. Browser raw-file uploads are limited to the Talkshi site; server and command-line clients are unaffected.

Discovery, buying, and catalog reads

The unified human buying marketplace is the /#buy section of the homepage. The protocol-specific directories remain at /marketplace and /mpp; their machine snapshots are /data/x402-marketplace.json and /data/mpp-marketplace.json.

POST /api/buy/attachment accepts exactly one raw PDF, JPEG, PNG, or WebP file up to 3,000,000 bytes per request. Send its matching Content-Type; an application/octet-stream upload also requires X-File-Type. The browser can select, paste, or drop up to four files totaling 12,000,000 bytes and processes them sequentially. A successful response contains a privacy-minimized summary of at most 360 characters plus attachment.kind and attachment.fileType. When the kind is commercial_insurance, it also contains a privacy-minimized three-line insuranceBrief of at most 1,200 characters; that field is null for every other kind. Talkshi does not persist the raw file, and OpenAI processing uses store: false. The source limit is 15/hour and 40/rolling 24 hours; project-wide extraction capacity is 60/hour and 200/rolling 24 hours. Errors are 413, 415, 422, 429 with Retry-After, or 503.

POST https://write.talkshi.com/insurance-document accepts exactly one raw PDF, JPEG, PNG, or WebP file up to 25,000,000 bytes. Send the matching file Content-Type; an application/octet-stream upload also requires X-File-Type with the actual supported media type. A successful response contains a privacy-minimized, at-most 1,200-character Need:/Must:/Prefer: commercial-insurance shopping brief and short detected document.fileType. The source limit is 5/hour and 15/rolling 24 hours; shared capacity is 20/hour and 50/rolling 24 hours. The compatibility path shares both budgets. Talkshi does not persist raw files. OpenAI processing uses store: false; Talkshi attempts immediate deletion before returning the result, and the temporary file expires after one hour as a backstop. The brief is input for broker shortlisting; the endpoint does not provide an insurer quote, binding indication, vendor outreach, or purchase. Errors are 413, 415, 422, 429 with Retry-After, or 503. The same-origin /api/insurance-document compatibility path accepts files up to 3,000,000 bytes.

Reviews and participation

An email-verified reviewer can forward a vendor-sent product email to [email protected]. This is an inbound evidence workflow, not a caller API; the public review receives only its evidence label and commitment hashes. Write reviews documents the checks and privacy boundary.

Identity

Talkshi AI, relay, payments, and reporting

The same stateless Talkshi AI responder is available by plain-text email at [email protected]; the Talkshi AI contract documents sender authentication, limits, and the differences from HTTP.

Content, data, and machine discovery

All of these reads are open. Research findings are sourced catalog or editorial facts, not first-hand product reviews or proof that Talkshi used the subject.

Not public contracts

Inbound email webhooks, the Vercel log drain, the daily founder-recap scheduler, database migrations, telemetry collectors, and admin monitoring routes are operational interfaces. Do not call or depend on them. Admin-only review maintenance actions are described in Write reviews for auditability, but they are not self-serve customer features.

The repository's insurance re-shop runner is also outside Talkshi's public API. An operator can host its POST /v1/drafts route on a private origin, protected by the backend-specific INSURANCE_RESHOP_TOKEN rather than a Talkshi account token, to prepare a draft-only renewal comparison from one PDF, JPEG, PNG, or WebP document up to 25,000,000 bytes. The backend pins OpenCode 1.18.14 and the exact model openai/gpt-5.6-sol, deletes its per-request temporary directory after success or failure, sends OpenAI Responses with store: false, and leaves missing underwriting facts unknown. It cannot contact or submit to a broker, accept terms, appoint a BOR/AOR, bind or change coverage, pay, or cancel. Keep it private or add gateway request and spend limits; its per-process one-job lock is not a distributed quota or persistent idempotency layer. There is no equivalent talkshi.com or write.talkshi.com route. Operator setup and the private multipart contract are documented in the repository's insurance-reshop/README.md.