APIs, webhooks & MCP

Quickstart

1) Pick a rail (webhook, MCP, or Passport). 2) Create the right key in the dashboard. 3) Call api.karvia.mx with JSON. 4) Verify live status in Integrations.

export KARVIA_API=https://api.karvia.mx
export KARVIA_KEY=kmcp_prod_YOUR_KEY

Integration status

Live = productized. Path = existing webhook/API contract (no native SDK). Stub = credentials savable; sync still pending.

Authentication

Three key families. Do not mix them — each endpoint expects a different prefix.

Authorization: Bearer kmcp_prod_YOUR_KEY
# DMS workshop:
X-API-Key: YOUR_WORKSHOP_KEY
# Passport B2B:
Authorization: Bearer pk_live_YOUR_KEY

Inbound webhooks (telemetry)

Push events from Samsara, Geotab, Airbag, or generic sources. Use an Agent API key (Bearer kmcp_prod_…) with telemetry permission and the webhook secret configured in Integrations.

Endpoints

Secret: X-Samsara-Signature header (HMAC). Response 200 { received, eventId }.

Secret: ?token= or X-Geotab-Token / X-Webhook-Secret.

Secret: X-Airbag-Signature / X-Webhook-Secret / ?token=.

Generic contract. Minimum fields: external_vehicle_id (or vehicle_id). Optional type: diagnostics | fault | trip | alert | behavior | gps.

curl -X POST https://api.karvia.mx/api/webhooks/generic \
  -H "Authorization: Bearer kmcp_prod_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_vehicle_id": "CAR-1234",
    "latitude": 19.4326,
    "longitude": -99.1332,
    "speed": 65,
    "odometer": 42000
  }'

DMS / GetCarSignal / CarSignal

CarSignal (trycarsignal.com / getcarsignal.com) and generic DMS (Zapier, Make, n8n, CDK via JSON) use workshop webhooks. No brand-native connector. Two endpoints, two contracts.

A) Public DMS webhook

Required auth with X-API-Key (workshop key). Processed event: service_completion. Response 200.

curl -X POST https://api.karvia.mx/api/webhooks/dms/WORKSHOP_ID \
  -H "X-API-Key: YOUR_WORKSHOP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "service_completion",
    "dms_reference": "RO-99881",
    "vehicle": {
      "vin": "3VW…",
      "plate": "ABC123A",
      "make": "Volkswagen",
      "model": "Virtus",
      "year": 2022,
      "mileage": 48200
    },
    "service": {
      "type": "maintenance",
      "description": "Servicio 40k + aceite",
      "total_cost": 2490.0
    },
    "invoice": { "currency": "MXN", "total": 2490.0 }
  }'

If VIN/plate does not match a Karvia vehicle: 200 with warning (logged for manual review). Success: work_order_id + service_record_id.

B) Premium workshop webhook

Requires a Workshop Premium account. Required auth: X-API-Key or Authorization Bearer. Body: required services array.

curl -X POST https://api.karvia.mx/api/workshops/webhooks/dms/WORKSHOP_ID \
  -H "Authorization: Bearer YOUR_WORKSHOP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dms_reference": "cs-wo-12345",
    "vehicle": { "vin": "3VW…", "plate": "ABC123A", "make": "VW", "model": "Virtus", "year": 2022 },
    "services": [
      { "type": "oil_change", "description": "Cambio de aceite", "total_cost": 890 }
    ]
  }'

Response 200: { success, created_orders, count }. Mint keys: Workshop → Webhooks (POST /api/workshops/mine/api-keys).

MCP (Agentic Hub)

Model Context Protocol over fleet data (health, alerts, trips, copilot). Create the key in Integrations → API / MCP. Same data as the web dashboard and operational WhatsApp.

Transports

Legacy SSE (Cursor / mcp-remote).

Streamable HTTP (Claude Cloud / modern clients).

Cursor mcp.json

{
  "mcpServers": {
    "karvia_hub": {
      "url": "https://api.karvia.mx/api/mcp/sse",
      "headers": {
        "Authorization": "Bearer kmcp_prod_YOUR_KEY"
      }
    }
  }
}

mcp-remote

npx -y mcp-remote https://api.karvia.mx/api/mcp/sse \
  --header "Authorization:Bearer kmcp_prod_YOUR_KEY"

Passport B2B (/api/v1)

Verifiable vehicle identity for partners. pk_live_* keys are issued by Karvia (talk to sales). Mint and attest are queued and processed; on-chain NFT issuance may still need Karvia ops if no passport exists yet.

Public — platform stats.

curl -X POST https://api.karvia.mx/api/v1/passport/mint \
  -H "Authorization: Bearer pk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vin": "3VW…",
    "make": "Volkswagen",
    "model": "Virtus",
    "year": 2022,
    "ownerWallet": "0x…"
  }'

201 { requestId, status: "pending" }. 409 if VIN already has a passport. Requires vin, make, model.

masterScore required (0–10000 basis points). Optional: legal, mechanical, driving, maintenance, eventType.

Public passport read.

Body: vin, eventType, payload.

Max 100 events per request.

docType + IPFS/URL reference.

Key in path. Requires event + vin.

Dashboard-only integrations

Telematics pull (Geotab/Samsara/VisionQube) and HRIS (Buk) are configured while signed in to Integrations — they are not public partner APIs.

Telematics (connect)

Geotab / Samsara / VisionQube: save credentials → Test → Sync → map each unit. Push-only partners should use Webhooks.

HRIS

Buk: available (score sync). Workday / Runa: coming soon.

OpenAPI

Machine-readable spec for the same contracts. Import it into Postman, Insomnia, or client generators.

https://karvia.mx/developers/openapi.yaml