API Documentation

Integrate ClearOrigin trade compliance intelligence into your application.

Quick Start

Sign up at clearorigin.ca and choose a plan
Go to Dashboard → API Keys → Create Key
Use your key in the Authorization: Bearer co_live_... header

curl "https://clearorigin.ca/api/v1/rulings?q=steel+pipe" \
  -H "Authorization: Bearer co_live_YOUR_KEY"

Authentication

All API v1 endpoints require a Bearer token. Include your API key in the Authorization header:

Authorization: Bearer co_live_a1b2c3d4e5f6...

API keys start with co_live_ (production) or co_test_ (testing). The raw key is shown once at creation — store it securely.

Rate Limits & Quotas

Plan	Price	Monthly Calls	Rate Limit
Free	$0	50/mo	10 RPM
Pro	$49/mo	500/mo	60 RPM
Business	$149/mo	5,000/mo	120 RPM
Platform	$499/mo	50,000/mo	200 RPM

Exceeding the monthly quota returns 429 QUOTA_EXCEEDED. Exceeding RPM returns 429 RATE_LIMITED with a Retry-After header.

Endpoints

POST/api/v1/assessscope: assess

Run an FTA origin assessment for a product and its materials. Returns qualification determination, condition results, and gap analysis.

Request Body (JSON)

descriptionstringrequiredProduct description

hsCodestringrequiredHS code (e.g. "7304.19")

originCountrystringrequiredCountry of origin (ISO alpha-2)

destinationCountrystringrequiredDestination country (ISO alpha-2)

materialsMaterial[]requiredArray of materials with description, hsCode, originCountry

ftastringFTA to assess (default: auto-detect)

customsValuenumberCustoms value for RVC calculation

Example Request

curl -X POST https://clearorigin.ca/api/v1/assess \
  -H "Authorization: Bearer co_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Softwood lumber",
    "hsCode": "4407.11",
    "originCountry": "CA",
    "destinationCountry": "US",
    "materials": [
      { "description": "Spruce logs", "hsCode": "4403.11", "originCountry": "CA" }
    ]
  }'

Example Response

{
  "determination": "qualifies",
  "fta": "CUSMA",
  "rule": { "hs_start": "4407", "source_text": "..." },
  "conditions": [{ "type": "shift", "result": "pass", ... }],
  "confidence": "high",
  "gap_analysis": null
}

Error Codes

All errors follow the format: { "error": "message", "code": "ERROR_CODE" }

Code	HTTP	Description
`AUTH_MISSING`	401	No Authorization header or malformed Bearer token
`AUTH_INVALID`	401	API key not found, expired, or revoked
`SCOPE_MISSING`	403	API key lacks the required scope for this endpoint
`QUOTA_EXCEEDED`	429	Monthly API call quota exceeded
`RATE_LIMITED`	429	Per-minute rate limit exceeded (see Retry-After header)
`INTERNAL_ERROR`	500	Unexpected server error
`SERVICE_UNAVAILABLE`	503	Embedding service temporarily unavailable

Code Examples

Python

import requests

API_KEY = "co_live_YOUR_KEY"
BASE = "https://clearorigin.ca/api/v1"

# Classify a product
resp = requests.post(f"{BASE}/classify",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"query": "softwood lumber", "limit": 5})
print(resp.json())

# Calculate landed cost
resp = requests.post(f"{BASE}/landed-cost",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "hsCode": "4407.11",
        "originCountry": "CA",
        "destinationCountry": "US",
        "customsValue": 50000
    })
print(resp.json())

JavaScript / Node.js

const API_KEY = 'co_live_YOUR_KEY';
const BASE = 'https://clearorigin.ca/api/v1';

// Search rulings
const res = await fetch(`${BASE}/rulings?q=steel+pipe&limit=5`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});
const data = await res.json();
console.log(data.cbp_results);

// Run origin assessment
const assess = await fetch(`${BASE}/assess`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    description: 'Steel pipe fittings',
    hsCode: '7307.19',
    originCountry: 'CA',
    destinationCountry: 'US',
    materials: [
      { description: 'Steel coils', hsCode: '7208.10', originCountry: 'CA' }
    ],
  }),
});
console.log(await assess.json());

MCP Server (AI Agents)

ClearOrigin also provides an MCP server for AI agents. The server exposes 4 tools (assess, landed_cost,classify, search_rulings) via stdio transport. See the GitHub README for setup instructions.

Questions? Contact support@clearorigin.ca