Skip to content

API Reference

Jump to bottom
mrdulasolutions edited this page Jun 15, 2026 · 3 revisions

API Reference

ExChek ships two MCP servers with the plugin. Skills talk to them through MCP tools — not raw HTTP — so calls are sanitized, audit-logged, and routed by the data-source gate. The free core — eCFR data, CSL screening, skill retrieval, the regulatory radar — needs no authentication and no payment, and no PII transits the network. The only paid surface is ExChek Enterprise (the branded Official Classification Memorandum PDF and the dashboard write-back tools), which is reached with a prepaid exk_live_… key; see Enterprise.

Hosted API base URL (MCP): https://api.exchek.us/mcp

Full API reference: https://docs.exchek.us/docs/api-reference

The two MCP servers

Server Transport Where it runs What it provides
exchek (local) stdio, local-first Claude Code / desktop (needs a local Node runtime) eCFR lookups (www.ecfr.gov primary, api.exchek.us fallback), Trade.gov CSL screening, input sanitization, CUI gate, HMAC-chained audit log, .docx converter
exchek-api (hosted) HTTP at https://api.exchek.us/mcp Anywhere, including Claude Cowork eCFR lookups + skill retrieval (list_skills / get_skill / get_skill_bundle) + the free regulatory radar — all no-auth, no PII. Plus the prepaid-key Enterprise tools (PDF rendering + dashboard)

Local exchek tools include regulatory_source (the data-source gate), ecfr_get_part, ecfr_full_text, csl_search, csl_sources, sanitize_input, cui_gate, audit_log / audit_verify / audit_tail, and report_to_docx. Screening, sanitization, audit logging, the CUI gate, and report generation always run on this local server — regardless of the data-source setting.

Hosted exchek-api tools cover eCFR part/section structure and full-text search, skill retrieval, the free regulatory radar (get_rule_changes, no auth), and the Enterprise surface — PDF rendering (create_classification_pdf / get_classification_pdf_contract) and the dashboard read/write tools (get_party_status, get_prior_classification, record_product_classification, record_screening, record_compliance_event, list_compliance_transactions, get_regulatory_notes). Everything except the Enterprise tools is no-auth; the Enterprise tools need a prepaid exk_live_… key. In Claude Cowork the local stdio server cannot spawn, so the hosted server is the one that runs.

regulatory_source setting (the data-source gate)

Skills call regulatory_source before pulling any CFR text. The setting decides which server serves eCFR data:

Value Behavior
ask (default) A one-time, per-session gate lets the user choose (ExChek API recommended).
local Always use the local exchek MCP (www.ecfr.gov primary, api.exchek.us fallback, cached on-machine).
api Always use the hosted exchek-api MCP at https://api.exchek.us/mcp.

Only CFR part numbers and search terms ever transit the hosted API — never item descriptions, party names, or results. In Claude Cowork, choose api (the local stdio server can't spawn there).

Free tools (no auth)

Beyond the eCFR lookups above, the hosted exchek-api server exposes skill retrieval and a regulatory-radar feed with no key and no payment:

Tool What it does
list_skills / get_skill / get_skill_bundle Discover and load any of the 20 ExChek skills on demand.
get_rule_changes The regulatory radar: recent BIS/DDTC/OFAC rulemaking, optionally narrowed to a set of ECCNs or CFR parts. Free, no auth — the same feed the dashboard's Regulatory Radar is built on.

Enterprise tools (hosted, prepaid key)

The following tools are the ExChek Enterprise surface. They render the branded Official Classification Memorandum and read/write your compliance dashboard, and they require a prepaid exk_live_… key (see the three auth surfaces below). Without a valid key they return purchase information rather than failing. None of them ever carry CUI, classified, or § 126.18-restricted matter — the skills enforce that gate at entry. See Enterprise for the full product, pricing, and dashboard description.

Tool What it does
get_classification_pdf_contract Returns the payload contract for create_classification_pdf — every template field, which are required, the raw-HTML narrative fields, and the authoring rules. Fetch this first when building a payload. The variable schema is part of the paid product, so it requires your key; fetching it never consumes a credit.
create_classification_pdf Renders a completed classification analysis (typically the output of exchek-classify) into the branded, audit-ready PDF memorandum. Pass draft: true for a free watermarked preview — no credit consumed, not stored — review it, then render the final (omit draft) once approved, which consumes 1 prepaid credit. Delivery is link-only: every response returns a 1-hour download link (the PDF is never embedded). On claude.ai / Desktop give the user the link; on Code / Cursor fetch the link to save the file — do not re-render to obtain the file, as a second final render re-charges a credit.
get_party_status Look up a party's current monitoring/screening status from the dashboard's Screening Center.
get_prior_classification Check the Products registry for a confirmed determination (generic label + ECCN) before re-deriving one — classify once, reuse, with staleness flags after 30 days.
record_product_classification Save a confirmed determination to the Products registry (generic label + ECCN only).
record_screening Record a screening event for a party, optionally registering it for continuous monitoring.
record_compliance_event Mirror pipeline status (stage / status / ECCN refs only — never item details) to the Transactions page; this is the opt-in metadata sync the dashboard's needs-attention queue is built on.
list_compliance_transactions List the compliance pipeline's transactions and their stages for the account.
get_regulatory_notes Pull your team's institutional guidance pinned to CFR citations in the eCFR Workbench, for use inside an analysis.

Credits and errors. Only successful final renders consume a credit. Failed validation (HTTP 400) and service errors are never charged. When credits run out, create_classification_pdf (and the REST endpoint) return HTTP 402 with a purchase link — buy again to receive a new key, or email matt@exchek.us to top up an existing one.

The three Enterprise auth surfaces

One prepaid exk_live_… key works across all three; pick the surface that fits your client. Buy credits and obtain the key at https://app.exchek.us (the key is shown exactly once, on the confirmation page).

Surface Endpoint / setting Best for How the key is presented
OAuth connector (preferred) add connector https://api.exchek.us/mcp/pro claude.ai, Claude Desktop OAuth sign-in — no key handling by you
Key-header MCP https://api.exchek.us/mcp Claude Code, Cursor the key as the MCP connection's Authorization header, or the plugin's enterprise_api_key setting
REST POST https://api.exchek.us/pdf/classification any HTTP client (raw PDF bytes) Authorization: Bearer <key>; add ?draft=1 for a free watermarked preview

The REST endpoint is the raw-bytes equivalent of create_classification_pdf. Its companion contract route, GET https://api.exchek.us/pdf/classification/contract, also requires your key and never consumes a credit.

eCFR Part endpoints (hosted HTTP)

The hosted service also exposes plain HTTP/JSON eCFR endpoints under https://api.exchek.us. Skills reach this data through the MCP tools above; the routes below document the underlying data surface.

These endpoints return the full structure of a given CFR Part as JSON. Skills use them to apply regulatory logic with current rule text.

Endpoint Description Used by
GET /api/ecfr/774 15 CFR Part 774 — Commerce Control List (CCL) ECCN Classification, License Determination
GET /api/ecfr/738 15 CFR Part 738 — Commerce Country Chart License Determination, Country Risk
GET /api/ecfr/740 15 CFR Part 740 — License Exceptions License Determination
GET /api/ecfr/742 15 CFR Part 742 — CCL-based Controls (incl. encryption § 742.15) Encryption
GET /api/ecfr/744 15 CFR Part 744 — End-use Controls (Entity List, MEU) ECCN Classification, License Determination
GET /api/ecfr/746 15 CFR Part 746 — Embargoes and Special Controls Country Risk, License Determination
GET /api/ecfr/121 22 CFR Part 121 — U.S. Munitions List (USML) ECCN Classification, Jurisdiction

Full-text search endpoints

Search within a specific Part for a keyword or phrase.

Endpoint Description
GET /api/ecfr/:part/search?q=term Full-text search within a specific Part
GET /api/ecfr/search?q=term&title=15 Search across all Parts in Title 15

Examples:

GET https://api.exchek.us/api/ecfr/774/search?q=pressure+sensor
GET https://api.exchek.us/api/ecfr/746/search?q=Russia
GET https://api.exchek.us/api/ecfr/742/search?q=encryption
GET https://api.exchek.us/api/ecfr/search?q=specially+designed&title=15

Response format

All part endpoints return JSON with a nodes structure. Each node has:

{
  "identifier": "774",
  "label": "Part 774 — The Commerce Control List",
  "children": [
    {
      "identifier": "774.1",
      "label": "§ 774.1 — Introduction",
      "children": []
    }
  ]
}

Skills traverse the node tree to find applicable sections and cite specific parts in the output.

eCFR source endpoints

Under the local exchek MCP, the primary regulatory source is the official eCFR developer API at www.ecfr.gov (the hosted api.exchek.us is the automatic fallback; the source used is recorded on every response). Under the hosted exchek-api MCP, api.exchek.us serves the data directly.

Endpoint Description
GET https://www.ecfr.gov/api/versioner/v1/structure/current/title-15.json Title 15 (Commerce) — extract Part 774, 738, 740, 742, 744, 746
GET https://www.ecfr.gov/api/versioner/v1/structure/current/title-22.json Title 22 (Foreign Relations) — extract Part 121

The eCFR API requires no key and returns the same node structure.

Trade.gov CSL API (CSL Search skill only)

The CSL Search skill screens parties against the Trade.gov Consolidated Screening List — a separate system from the eCFR data. Screening runs through the local exchek MCP (csl_search / csl_sources), so it requires Claude Code or a desktop runtime and is not available in Cowork. This one needs a free API key from developer.trade.gov.

Endpoint Description
GET https://data.trade.gov/consolidated_screening_list/v1/search Search the CSL by name and other parameters
GET https://data.trade.gov/consolidated_screening_list/v1/sources List available source abbreviations

Authentication: API key as a query parameter or header (see developer.trade.gov for exact method).

Key parameters:

Parameter Type Description
name string Party name to search
fuzzy_name boolean Enable fuzzy matching (use with name)
sources string Comma-separated source abbreviations (DPL, EL, SDN, etc.)
countries string ISO alpha-2 codes, comma-separated
size integer Results per page (max 50)
offset integer Pagination offset

Full parameter list: developer.trade.gov

Rate limits and availability

Neither MCP server has documented rate limits for normal skill use. The local exchek MCP uses www.ecfr.gov as its primary source and falls back to api.exchek.us automatically if it is unreachable.

The Trade.gov CSL API is maintained by ITA. Check developer.trade.gov for current status and rate limit terms.

Keeping data current

Both servers serve live eCFR data. The local exchek MCP fetches current regulatory text at runtime and caches part structure on-machine (24h) so repeat lookups stay fast; the hosted exchek-api MCP is edge-cached. Every response records the source and pull timestamp, and any determination older than 30 days should be re-run.

Clone this wiki locally