kordi for Developers

Searches kordi’s observed save-desk history for the user’s active paid subscriptions and returns only services with a possible offer. Candidates are ranked by known fixed-dollar savings then monthly cost, with eligible after-tax monthly totals alongside the unchanged base amount, but are always unconfirmed — the agent asks which one to check first, works one at a time, and never promises or totals the offers.

Paginated subscription list. Params: offset, limit, include_paused. Multi-currency aware: returns display_currency, totals_by_currency (exact per-currency totals), and an FX-converted total_monthly. For eligible US catalog prices it adds estimated_monthly_tax and estimated_monthly_total without changing stored/base amounts; unmatched charged totals remain untouched. Subscriptions with price: 0 and guest_access: true are bundled/guest access — intentional, not missing data. Sensitive card fields stripped. Truncates at 25k chars.

Price-hike detection, dormant service list, billing cluster analysis, and additive estimated-tax spend/savings totals. Returns health_score 0–100.

Live server build metadata — version, git_sha, built_at. Runs server-side, so it always reflects the deployed version. Use it to detect a stale connection: if the reported version is newer than your cached tool schemas, reconnect to refetch tools/list.

The agent worklist — time-sensitive actions: upcoming renewals (renewal_upcoming), trials about to convert (trial_ending), elapsed pauses (resume_due), and the user's locked rotation schedule advancing to a new month (rotation_due, with to_pause/to_resume service lists). Eligible items carry additive monthly and per-charge estimated tax/total fields. Sorted most-urgent first. Params: trial_horizon_days and renewal_horizon_days (each 1–30, default 7). The primary tool for scheduled / autonomous check-ins — pair with the kordi_scheduled_checkin prompt.

Add a subscription the user names directly ("I pay $15.99/mo for Netflix"). Dedupes by name; re-call updates amount/bill date. Handles any cadence via billing_cycle — monthly (default), annual (amount is the full yearly price, bill_date the renewal date), or custom for weekly / every-N-weeks (billing_interval_days + billing_anchor_date). Optional trial_end_date.

Bulk import a list in one call — the onboarding tool (e.g. after an email scan). One call writes the whole batch (stays within the per-session rate limit), dedupes by name, validates each item independently (bad rows return in failed, never block the rest), and logs a discover event per service. Set source to the connector name (gmail/superhuman/outlook). Email finds carry per-item evidence_type + evidence_date — kordi reconciles "started" vs "still active" server-side and returns uncertain items (dead trials, cancellations, stale charges) in needs_confirmation instead of writing them; re-submit user-confirmed ones with user_confirmed: true. Per-item billing_cycle (annual/custom) imports yearly receipts at the full yearly price, normalized in totals.

Patch an existing subscription — price, bill date, trial end date, billing cadence, or the user's explicit tax_handling override (auto/pre_tax/included). A typed price resets catalog provenance so auto does not add tax to a charged total. Only provided fields change. service_id from kordi_list_subscriptions.

Mark a subscription paused in kordi's tracking. A plain pause does not stop provider billing — the response says so loudly: billing_status: "STILL_CHARGING" plus a next_action pointing at kordi_get_cancellation_route, alongside billing_note + cancellation_url. Optional resume_date (ISO) arms kordi's reactivation reminder; billing_stopped: true (only after an executed cancellation route or native pause) records a confirmed provider-side stop and returns billing_status: "STOPPED_CONFIRMED".

Mark a paused (or previously cancelled) subscription active again in kordi's tracking — also the write-back for kordi_get_resubscribe_route after a provider-side restart. service_id from kordi_list_subscriptions (with include_paused).

Record a confirmed provider cancellation — sets state CLOSED and logs the churn outcome. Returns cadence-aware base savings plus eligible estimated tax/after-tax savings. Call only after the user confirms (or the agent completed) the cancel.

Permanently stop tracking a subscription. Cannot be undone — use pause for a temporary stop. service_id from kordi_list_subscriptions.

Returns the execution runbook for cancelling/pausing at the provider — an agent_playbook with deep link, ordered steps, known retention traps, an on-page success indicator, and the exact write-back tool call. Curated playbooks for 33 services — every major streamer plus common SaaS/AI/lifestyle subs (Adobe, Audible, ChatGPT, Claude, iCloud+, gyms), with their contract-fee and credit-forfeiture traps. For anything else kordi checks a self-growing library (~50 more services, hand-audited or web-researched) then, on a genuine miss, researches the provider's current cancel flow live (Gemini + Google Search grounding) and saves the result — responses carry last_verified, and force_refresh re-researches + updates the library after UI drift — falling back to a generic runbook. A browser-capable agent can pass agent_can_browse: true to skip that paid research step on a miss and research the live flow itself instead (see kordi_contribute_playbook below to save it back for free). intent defaults to "pause" (kordi prioritizes rotation over churn — reserve "cancel" for an unambiguous "leaving for good"): pause wires write-back to kordi_pause_subscription and prefers native_pause where the provider has a real pause feature; cancel wires it to kordi_mark_cancelled. The playbook also carries retention_intel: any observed D1 offer becomes a clearly unconfirmed potential_offer, so the agent asks whether to check for it or continue cancelling before opening the provider flow; known fixed-dollar offers can be phrased as “up to $X.” It also carries broader crowd intel plus a negotiation script (see kordi_log_retention_offer). Records cancellation intent. service_id from kordi_list_subscriptions.

Report back a runbook a browser-capable agent researched and successfully executed itself for a service kordi had no playbook for (agent_playbook.source was "generic"). Call only after confirming the outcome on-page. Saves permanently to kordi's shared library — a curated or existing library entry always wins, so this only ever fills a genuine gap; the next request for that service, from anyone, is then served free instead of researched again.

The mirror image of the cancellation route — the execution runbook for restarting a paused or cancelled service. Returns an agent_playbook with the restart deep link, ordered steps, restart-specific traps (lost promo pricing, reactivate-don't-recreate the account, app-store billing), an on-page success indicator, and a billing_check warning that restarting charges the current price immediately. Write-back is kordi_resume_subscription. Curated restart playbooks for the major streaming services and common SaaS subs, generic runbook otherwise. service_id from kordi_list_subscriptions (include_paused: true).

Discovery-source ingest (Qira / Screenpipe / email connectors — set source to the connector name). Dedupes by normalized name (re-call updates amount/bill date). Optional: trial_end_date (ISO YYYY-MM-DD) lights up the proactive-trial loop; billing_cycle (annual/custom) for yearly or every-N-days receipts; currency (ISO 4217, when the receipt shows it — "€12" → "EUR"); card_network (visa | mastercard | amex | discover) feeds the card-network proof layer — only pass when explicitly known, never guessed. Email finds carry evidence_type + evidence_date — non-fresh evidence returns status: "needs_confirmation" (nothing written) until re-called with user_confirmed: true. All enrich-only on re-ingest. Returns a signed 7-day pause link.

Record a save-desk offer the provider made mid-cancellation ("wait — 50% off"), accepted or declined. Aggregated across users (non-PII: service + terms + outcome only) and fed back into kordi_get_cancellation_route's retention_intel so the next user knows what to ask for. If the user accepts a new price, also call kordi_update_subscription.

Report UI drift, missing buttons, or broken flows hit while executing a playbook (service_id, step, error_type, error_message) — flags the playbook for engineering instead of failing silently.

Escalate a blocker the agent can't solve — blocker_type ∈ captcha, 2fa, login_wall, biller_mismatch, other. kordi holds a short grace period before emailing (a user actively watching the agent usually clears the prompt themselves in seconds — the write-back tools mark it resolved and no email fires). If it's still unresolved after that, kordi emails the user with blocker-specific instructions and a provider deep link, so the handoff reaches them even when the agent runs in the background.

The hero tool. Crosses subscriptions × watchlist × real show air dates to recommend keep / pause-until / cancel per service, with unchanged base savings and eligible estimated tax/after-tax savings. Flags watchlist shows on services the user doesn't pay for.

What kordi has saved the user: vault credits, harvestable pending, current paused-monthly, and a lifetime estimate from pause history. Components reported separately, never summed.

Checks each active subscription against current market tiers (weekly price crawl) and surfaces cheaper tiers — e.g. ad-supported plans — with base and eligible after-tax savings plus the trade-off.

Search TV/movies by name — kordi's DB first, then TVMaze fallback. Use to confirm an exact title before rating or adding.

Record a like/dislike to train the user's taste profile — the same signal powering recommendations. Optional genres, network. Idempotent: re-stating the same opinion is skipped; a flipped opinion records.

Bulk rating — seed a whole taste profile in one call. Ask "what are your all-time favorites?" and pass everything named as shows[] (1–50, each defaults to liked). One rate-limit unit, one atomic batch write, one profile rebuild — use this instead of looping kordi_rate_show whenever the user lists more than one title.

"What should I watch?" — the same ranked picks as kordi's Vibe/Discover feed (genre, vibe-vector, collaborative, trending, mood, gateway scoring). Params: limit (1–20, default 8), optional mood (escape / engage / unwind / feel). Thin or no taste profile falls back to trending with personalized: false — seed taste via kordi_rate_shows first.

Add one or more shows kordi should monitor (new seasons, air dates, streaming availability). Additive — re-adding is a no-op. Feeds the rotation plan.

List the shows kordi is monitoring for the user. No arguments.

Stop tracking one or more shows (case-insensitive). Call only on explicit user request.

Cross-user show-popularity leaderboard. Aggregate only, no PII.

Opt the user out of AI taste profiling (Privacy Policy §11) — call only on a clear, explicit request. Ratings are still recorded as stated opinions, but no profile is derived and recommendations fall back to trending. Permanent, applies web + agent; confirmation emailed.

Whole-DB aggregates: users, swipes, like-rate, discovery volume by source. Admin-gated — hidden from tools/list for non-admin accounts.