API docs

All requests use a Bearer API key in the Authorization header. Mint a key in Settings → API keys. The plaintext is shown once.

curl -H "Authorization: Bearer rcn_..." \
  https://3-130-85-220.sslip.io/api/v1/vehicles

ReconOS pushes events to your endpoint instead of you polling. Add a subscription in Settings → Webhooks. Each subscription gets a signing secret (shown once).

Event types

Delivery shape

POST to your URL with JSON body. Headers carry the event type and an HMAC-SHA-256 signature you verify against your secret.

POST https://your-server/webhook
Content-Type: application/json
X-ReconOS-Event: vehicle.stage_changed
X-ReconOS-Delivery: <delivery uuid>
X-ReconOS-Signature: sha256=<hex>
User-Agent: ReconOS-Webhook/1

{
  "event_type": "vehicle.stage_changed",
  "delivery_id": "<delivery uuid>",
  "timestamp": "2026-05-13T22:00:00.000Z",
  "payload": {
    "vehicle_id": "<uuid>",
    "vin": "1HGBH41JXMN109186",
    "from_stage": "photos",
    "to_stage": "frontline",
    "to": "frontline",
    "changed_at": "2026-05-13T22:00:00.000Z",
    "actor_user_id": "<uuid>"
  }
}

Verifying the signature

Compute hmac_sha256(secret, raw_body) and compare (constant-time) to the hex after sha256=. If they match, the payload came from us and wasn't tampered with.

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody, signatureHeader, secret) {
  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
  const got = (signatureHeader ?? "").replace(/^sha256=/, "");
  if (got.length !== expected.length) return false;
  return timingSafeEqual(Buffer.from(got), Buffer.from(expected));
}

Retries

Push ReconOS stage changes back to your DMS so inventory records stay in sync without anyone re-keying. Layered on the webhook outbox: same HMAC signing, same retry policy, same audit log. The payload is rewritten into the vendor's expected shape and the right vendor-specific header is set.

Configure in Settings → DMS write-back. Pick CDK Drive, Reynolds ERA, or Dealertrack; paste the partner endpoint URL; customize the stage → status-code mapping. Owner-only.

Supported presets

Event coverage

CDK Drive payload shape

POST https://your-cdk-partner-endpoint/status
Content-Type: application/json
X-ReconOS-Event: vehicle.stage_changed
X-ReconOS-Delivery: <delivery uuid>
X-ReconOS-Signature: sha256=<hex>
X-CDK-Status-Push: v1
User-Agent: ReconOS-Webhook/1

{
  "vin": "1HGBH41JXMN109186",
  "reconStatus": "RECON_PHOTO",
  "previousStatus": "RECON_MECH",
  "timestamp": "2026-05-13T22:00:00Z",
  "source": "ReconOS"
}

Reynolds ERA payload shape

POST https://your-reynolds-partner-endpoint/status
Content-Type: application/json
X-ReconOS-Event: vehicle.stage_changed
X-Reynolds-Event: vehicle.status

{
  "vin": "1HGBH41JXMN109186",
  "status": "R_PHOTOS",
  "ts": "2026-05-13T22:00:00Z"
}

Dealertrack payload shape

POST https://your-dealertrack-partner-endpoint/status
Content-Type: application/json
X-ReconOS-Event: vehicle.stage_changed
X-Dealertrack-Source: reconos

{
  "vin": "1HGBH41JXMN109186",
  "inventoryStatus": "RECON_PHOTOS",
  "changedAt": "2026-05-13T22:00:00Z"
}

Stage → status-code mapping

Each preset ships with default mappings between ReconOS stages and DMS status codes. Most CDK installs use slightly different codes per dealer; override per-stage in the settings UI. The value sent in reconStatus / status /inventoryStatus is whatever you configure (the defaults below are starting points, not contracts).

ReconOS can receive stage-change events from whatever recon tool your dealership runs today (Rapid Recon, CDK, Reynolds). Use that tool as your daily kanban; let ReconOS layer analytics + audit + the bolt-on API surface on top. We do not write back. This is one-way ingest.

1. Set up the signing secret

In ReconOS, go to Settings → Rapid Recon integration and click Generate signing secret. You'll see the plaintext exactly once. Copy it into Rapid Recon's outbound-webhook config along with the URL below.

2. Endpoint shape

POST https://3-130-85-220.sslip.io/api/integrations/rapid-recon/webhook/<your-dealership-id>
X-Signature: sha256=<hex-hmac-of-raw-body>
Content-Type: application/json

{
  "event_id": "evt_abc123",
  "event_type": "vehicle.synced",
  "occurred_at": "2026-05-14T15:23:00Z",
  "vehicle": {
    "external_id": "T5832",
    "vin": "1HGBH41JXMN109186",
    "year": 2021,
    "make": "Honda",
    "model": "Accord LX",
    "miles": 42100,
    "current_step": "Photography",
    "purchased_at_amount": 18200,
    "internet_price": 22500,
    "assigned_tech": "Mike Rodriguez"
  }
}

3. Idempotency

Upserted by (dealership_id, external_source, external_id). Calling twice with the same external_id updates the same row, so your retry logic doesn't duplicate cars. The first event creates the vehicle and logs a stage_change recon_event; subsequent events update fields and log a stage_change only when the stage actually transitions.

Response codes

Drop a <script> tag into any HTML page (your existing recon tool's custom panel, intranet, Slack canvas, Confluence page) and a ReconOS panel renders inline. Auth is a read-scope API key in the URL (same trust model as a Stripe Publishable Key).

Reference benchmark

<script src="https://3-130-85-220.sslip.io/embed/benchmark.js"
        data-key="rcn_..."
        data-width="420"
        data-height="320"></script>

Bottleneck this week

<script src="https://3-130-85-220.sslip.io/embed/bottleneck.js"
        data-key="rcn_..."
        data-width="420"
        data-height="320"></script>

Each API key gets 120 requests per minute. The limit is per-key (not per-IP), so a noisy script on one machine doesn't affect the same dealership's other integrations.

When you hit the limit, you get a 429 with a Retry-After header (seconds until the window resets). Well-behaved clients back off until that time.

Retry-After: 27
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0

All errors share a JSON shape. The HTTP status code tells you what kind:

{ "error": "human-readable message",
  "details": { "optional": "context" } }