# Cipher & Row API · Phase 1

> Carrier and broker verification, continuous compliance monitoring, and driver Trust Links via REST. Canada-first, US-ready, one API key. The full interactive docs page lives at https://cipherandrow.com/docs.

**Scope:** Phase 1 covers verification and monitoring only. Deal flow, agent-to-agent messaging, AI gateway, and document extraction endpoints ship in Phase 2 — design partners onboarding now (founders@cipherandrow.com).

## Authentication

All Phase 1 endpoints take a single header.

```
x-api-key: cr_live_a1b2c3d4...
```

Keys start with `cr_live_` and are shown only at creation. Mint and rotate at `Settings → API`. One key per environment. Never embed in a public client bundle.

## Base URL

```
https://amjwnrglafnzwfrctqoh.supabase.co/functions/v1
```

A custom `gateway.cipherandrow.com` host is also available for enterprise plans.

## Endpoints

### Carrier verification

**POST `/carrier-lookup`** — Look up a US carrier by MC or DOT.
```json
{ "mc_number": "MC-391204" }
```
Returns operating status, safety rating, insurance, fleet size, drivers, risk score (0-100), risk band. Cached 24h; append `?fresh=true` to bypass.

**POST `/carrier-lookup-ca`** — Look up a Canadian carrier by CVOR (ON), CTQ/NEQ (QC), NSC, or cross-border DOT. Pass the identifier plus a two-letter province code.
```json
{ "cvor_number": "123456789", "province": "ON" }
```

**POST `/verify-carrier`** — Full verification (FMCSA authority + insurance + fraud signals) in one call. Returns `overall_status: verified | pending | rejected` and an `expires_at` for 90-day re-verification windows.

### Broker verification

**POST `/broker-lookup`** — Look up a US broker by MC. Returns FMCSA authority, BMC-84 surety bond status and amount, complaint count, risk band.

**POST `/ca-broker-verify`** — Verify a Canadian broker against the CBSA licensed-broker registry and provincial registries (ON, QC).

### Continuous monitoring

**POST `/carrier-monitor`** — Subscribe a carrier. Idempotent on `(carrier, webhook_url)`. Returns subscription id and next check time.
```json
{
  "mc_number": "MC-391204",
  "webhook_url": "https://your.app/webhooks/cr",
  "events": ["authority_change", "insurance_lapse", "safety_rating_change"]
}
```

**POST `/insurance-monitor`** — Watch a carrier's BMC-91 / BMC-34 (US) or provincial insurance. Fires `insurance_lapse` on cancellation, reduction, or expiry within 14 days.

**POST `/compliance-scan`** — On-demand fresh snapshot across all upstream registries. No subscription required.

### Trust Links

**POST `/trust-link-create`** — Mint a one-time tokenized URL for a single load. Driver receives SMS or email.
```json
{
  "mc_number": "MC-391204",
  "delivery_method": "sms",
  "driver_phone": "+15551234567",
  "load_reference": "L-9921",
  "pickup_location": "Toronto, ON",
  "delivery_location": "Montréal, QC"
}
```

**POST `/trust-link-verify`** — Driver-side endpoint. Binds the link to a driver name + truck. After this, the driver page can post location and delivery updates.

## Webhooks

Phase 1 event catalog:

- `authority_change`
- `insurance_lapse`, `insurance_renewed`
- `safety_rating_change`
- `out_of_service_added`, `out_of_service_lifted`
- `broker_bond_change`, `broker_authority_change`
- `trust_link_opened`, `trust_link_completed`

Every delivery carries a signed `X-CR-Signature: t=<unix>,v1=<hex>` header. Verify with `HMAC-SHA256(secret, "{t}.{raw_body}")` and a timing-safe compare. Reject deliveries older than 5 minutes.

Non-2xx responses retry with exponential backoff for up to 24 hours (1m, 5m, 30m, 2h, 6h, 24h). Return a 2xx within 10 seconds to acknowledge.

## Rate limits

| Plan       | Burst / min | Daily quota |
|------------|-------------|-------------|
| Free       | 10          | 100         |
| Starter    | 120         | 5,000       |
| Pro        | 1,000       | 50,000      |
| Enterprise | Custom      | Unlimited   |

Every authenticated response includes `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, and on 429s a `Retry-After` header. Daily counter resets at 00:00 UTC.

## Error codes

| Code | Meaning |
|------|---------|
| 400  | Bad request |
| 401  | Missing or invalid API key |
| 403  | Key revoked, plan does not include endpoint, or RLS denied |
| 404  | Carrier / broker / subscription / Trust Link not found |
| 409  | Duplicate subscription or Trust Link for the same load |
| 413  | Payload over 32 KB |
| 422  | Validation error |
| 424  | Upstream registry unavailable (FMCSA / MTO / CBSA); retryable |
| 429  | Rate limit exceeded |
| 500  | Internal error (use `request_id` for support) |
| 503  | Service degraded; auto-retried with backoff |

## OpenAPI

Full spec: https://cipherandrow.com/api-spec.yaml

## Help

- Interactive docs: https://cipherandrow.com/docs
- Integrations email: integrations@cipherandrow.com
- Design-partner access for Phase 2: founders@cipherandrow.com