decide.fyi

Decision API + MCP notaries for deterministic system and agent decisions

One-Click Install

Buttons install the Refund Notary server. To add all 4 servers, use the JSON config below.

MCP Servers

All servers: 100 vendors, US region, individual plans, stateless, no auth, 100 req/min.

Quick Start

Connect via MCP (Claude Desktop / Windsurf / other clients)

{
  "mcpServers": {
    "refund-decide": { "url": "https://refund.decide.fyi/api/mcp" },
    "cancel-decide": { "url": "https://cancel.decide.fyi/api/mcp" },
    "return-decide": { "url": "https://return.decide.fyi/api/mcp" },
    "trial-decide":  { "url": "https://trial.decide.fyi/api/mcp" }
  }
}

REST API

# Refund eligibility
curl -X POST https://refund.decide.fyi/api/v1/refund/eligibility \
  -H "Content-Type: application/json" \
  -d '{"vendor":"adobe","days_since_purchase":12,"region":"US","plan":"individual"}'

# Cancellation penalty
curl -X POST https://cancel.decide.fyi/api/v1/cancel/penalty \
  -H "Content-Type: application/json" \
  -d '{"vendor":"adobe","region":"US","plan":"individual"}'

# Return eligibility
curl -X POST https://return.decide.fyi/api/v1/return/eligibility \
  -H "Content-Type: application/json" \
  -d '{"vendor":"adobe","days_since_purchase":12,"region":"US","plan":"individual"}'

# Trial terms
curl -X POST https://trial.decide.fyi/api/v1/trial/terms \
  -H "Content-Type: application/json" \
  -d '{"vendor":"adobe","region":"US","plan":"individual"}'

Local Dev Checks

Start local dev server:

npx vercel dev

In a separate terminal:

# Handler-level smoke checks (no running server required)
npm run smoke

# MCP endpoint checks (requires vercel dev running on localhost:3000)
npm run mcp:check

# End-to-end workflow fixture (example -> result)
npm run workflow:test

# Production customer-key verification after provisioning a key
DECIDE_SMOKE_API_KEY='<customer-key>' npm run smoke:customer-key

Zendesk Workflow Orchestrators

Use workflow endpoints when you want one request to return:

• decision classification (yes | no | tie) from /api/decide

• policy result from the relevant notary endpoint

• recommended Zendesk action + tags + private note with request_id

Endpoints

• POST https://refund.decide.fyi/api/v1/workflows/zendesk/refund

• POST https://cancel.decide.fyi/api/v1/workflows/zendesk/cancel

• POST https://return.decide.fyi/api/v1/workflows/zendesk/return

• POST https://trial.decide.fyi/api/v1/workflows/zendesk/trial

Request

{
  "ticket_id": "ZD-9001",
  "workflow_type": "refund",
  "question": "Should this Adobe annual plan refund request proceed under policy?",
  "vendor": "adobe",
  "region": "US",
  "plan": "individual",
  "days_since_purchase": 5
}

For refund and return, include days_since_purchase.

Deterministic test mode

Set decision_override to bypass model classification during fixtures and CI:

{
  "decision_override": "yes"
}

Response (example)

{
  "ok": true,
  "flow": "zendesk_refund_v1",
  "ticket_id": "ZD-9001",
  "decision": { "c": "yes", "request_id": "req_123" },
  "policy": { "verdict": "ALLOWED", "code": "WITHIN_WINDOW" },
  "action": {
    "type": "approve_refund",
    "zendesk_tags": ["decide", "decide_yes", "refund_allowed"]
  }
}

Refund Notary

Endpoint: POST https://refund.decide.fyi/api/v1/refund/eligibility MCP Tool: refund_eligibility

Checks if a subscription purchase is within the vendor's refund window.

Input: vendor, days_since_purchase, region, plan

{"refundable":true,"verdict":"ALLOWED","code":"WITHIN_WINDOW","message":"Refund is allowed. Purchase is 12 day(s) old, within 14 day window.","vendor":"adobe","window_days":14}

Codes: WITHIN_WINDOW, OUTSIDE_WINDOW, NO_REFUNDS, UNSUPPORTED_VENDOR

Cancel Notary

Endpoint: POST https://cancel.decide.fyi/api/v1/cancel/penalty MCP Tool: cancellation_penalty

Checks cancellation penalties — early termination fees, contract locks, or free cancellation.

Input: vendor, region, plan

{"verdict":"PENALTY","code":"EARLY_TERMINATION_FEE","message":"adobe charges an early termination fee: 50% of remaining months on annual plan.","vendor":"adobe","policy":"etf"}

Codes: NO_PENALTY, EARLY_TERMINATION_FEE, CONTRACT_LOCKED, UNSUPPORTED_VENDOR

Return Notary

Endpoint: POST https://return.decide.fyi/api/v1/return/eligibility MCP Tool: return_eligibility

Checks if a subscription purchase can be returned/reversed, with return type and method.

Input: vendor, days_since_purchase, region, plan

{"returnable":true,"verdict":"RETURNABLE","code":"FULL_RETURN","message":"Return is available. Purchase is 5 day(s) old, within 14-day window.","vendor":"adobe","return_type":"full_refund","method":"self_service"}

Codes: FULL_RETURN, PRORATED_RETURN, CREDIT_RETURN, OUTSIDE_WINDOW, NO_RETURNS, UNSUPPORTED_VENDOR

Trial Notary

Endpoint: POST https://trial.decide.fyi/api/v1/trial/terms MCP Tool: trial_terms

Checks free trial availability, length, card requirement, and auto-conversion status.

Input: vendor, region, plan

{"verdict":"TRIAL_AVAILABLE","code":"AUTO_CONVERTS","message":"adobe offers a 7-day free trial. Credit card required. Auto-converts to paid plan.","vendor":"adobe","trial_days":7,"card_required":true,"auto_converts":true}

Codes: AUTO_CONVERTS, NO_AUTO_CONVERT, TRIAL_NOT_AVAILABLE, UNSUPPORTED_VENDOR

Supported Vendors (100)

Scope: US region, individual plans only.

Data Freshness

Policies are sourced from official vendor documentation and terms of service.

• Daily automated checks — GitHub Action runs at 08:00 UTC, hashing vendor policy pages across all 4 services (refund, cancel, return, trial). If a page changes, an issue is opened for review.

• Policy source URLs tracked — Each service has its own sources file in rules/ linking to official policy pages.

• Compliance export — GET /api/compliance-export returns a CSV snapshot of tracked sources, hashes, and pending candidate changes (?format=json for machine-readable output).

• Versioned rules — Each rules file includes a rules_version field for staleness detection.

Architecture

• Stateless — No database, no sessions, no side effects

• Deterministic — Same input always produces same output

• Versioned Rules — Rules files include version for tracking changes

• Daily Monitoring — GitHub Action checks all vendor policy pages daily

• Serverless — Runs on Vercel serverless functions

• Zero Dependencies — Core compute logic has no external dependencies

• Hostname Routing — Vercel middleware routes subdomains to correct MCP endpoints

Limitations

• US Only — Currently only supports US region

• Individual Plans Only — Business/enterprise plans not yet supported

• Calendar Days — Windows are based on calendar days, not business days

• Static Rules — Does not account for promotional offers or special circumstances

Changelog

Unreleased

Added:

• GET /api/compliance-export endpoint for policy monitoring evidence export (CSV default, JSON via ?format=json).

• Smoke test coverage for compliance export JSON and CSV paths.

v1.2.1 (2026-02-08)

Changed:

• Subdomain homepage now shows the relevant notary card (refund/cancel/return/trial).

• Version metadata is consistent across server.json, MCP initialize, and /.well-known/*.

v1.2.0 (2026-02-02)

Added:

• Cancel Notary MCP (cancel.decide.fyi) — cancellation penalty checker

• Return Notary MCP (return.decide.fyi) — return eligibility checker

• Trial Notary MCP (trial.decide.fyi) — free trial terms checker

• Hostname-based middleware routing for all subdomains

• Policy source files and daily checking for cancel, return, and trial policies

• Systems/Agents mode framing on landing page

• MCP catalog with cards for all 4 servers

Fixed:

• Daily policy checker: added contents:write permission and fixed shell logic

• Removed dead Cloudflare email-decode scripts causing 404s

v1.1.0 (2026-02-01)

Added:

• Expanded from 64 to 100 supported vendors

• Daily policy-check GitHub Action (cron at 08:00 UTC)

• Policy source URLs tracked in rules/policy-sources.json

• MCP vendor enum in inputSchema for agent discoverability

Fixed:

• ERR_IMPORT_ATTRIBUTE_MISSING crash on Vercel (Node 22 import attributes)

v1.0.0 (2026-01-15)

Added:

• Initial release with REST API and MCP server

• Support for 9 vendors

Free API (Default: No Auth)

All 4 policy servers are free to use. No authentication. No API keys.

/api/decide is public by default, and can be protected by setting DECIDE_API_KEY in server env vars.

If you run decide behind the decidesite proxy with dynamic customer keys, also set:

• DECIDE_PROXY_SHARED_TOKEN: shared secret required in x-decide-proxy-token header for trusted proxy calls.

• DECIDE_API_KEY: backend internal key that the trusted proxy forwards upstream (recommended to keep backend private).

Rate limit: 100 requests/minute per IP.

For first-customer handoff and keyed production verification, see docs/FIRST_CUSTOMER_RUNBOOK.md.

Policy Fetch Hook (for policy checker browser-hook lane)

Use POST /api/policy-fetch-hook as a fetch adapter for the daily checker when direct fetches are blocked.

Request body:

{
  "url": "https://example.com/policy",
  "vendor": "example_vendor",
  "policy_type": "refund",
  "timeout_ms": 18000
}

Auth:

• Authorization: Bearer <POLICY_CHECK_BROWSER_HOOK_TOKEN> or x-hook-token: <token>

Server env:

• POLICY_CHECK_BROWSER_HOOK_TOKEN (required for endpoint auth)

• POLICY_FETCH_BROWSERLESS_TOKEN (optional; enables browserless render first)

• POLICY_FETCH_BROWSERLESS_CONTENT_URL (optional override; default https://chrome.browserless.io/content)

• POLICY_FETCH_ALLOWED_HOSTS (optional comma-separated host allowlist)

Checker (GitHub Actions, repo decide):

• Secret POLICY_CHECK_BROWSER_HOOK_URL = deployed endpoint URL (example: https://decide-1.vercel.app/api/policy-fetch-hook)

• Secret POLICY_CHECK_BROWSER_HOOK_TOKEN = same token as runtime env

• Variable POLICY_CHECK_FETCH_LANES_DEFAULT = browser_hook,direct,zendesk_api,mirror

Questions? decidefyi@gmail.com or @decidefyi on X

Links

• Website: https://decide.fyi

• Refund: https://refund.decide.fyi

• Cancel: https://cancel.decide.fyi

• Return: https://return.decide.fyi

• Trial: https://trial.decide.fyi

• X/Twitter: @decidefyi

• MCP Spec: https://modelcontextprotocol.io

Built with love by the decide.fyi team