API Reference

v1 — April 2026

Authentication

API keys are generated in Settings → Workspace → API Key. Pass the key as a Bearer token in the Authorization header:

Authorization: Bearer sk_cobank_a1b2c3d4e5f6...

Keys are hashed server-side with SHA-256. cobank never stores the raw key. If you lose the key, revoke it in Settings and generate a new one.

POST /api/ingest

Push structured invoice data from ERPs, accounting software, or custom integrations. Each request can contain up to 100 invoices.

Request

POST https://cobank.ai/api/ingest
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "invoices": [
    {
      "vendor_name": "Kuehne + Nagel AG",
      "invoice_date": "2026-03-10",
      "total_amount": 29835.60,
      "currency": "CHF",
      "region": "CH",
      "line_items": [
        {
          "description": "FCL Container Rotterdam-Shanghai",
          "spend_amount": 9200,
          "quantity": 1,
          "unit_of_measure": "TEU"
        },
        {
          "description": "Inland transport Zurich-Rotterdam",
          "spend_amount": 3400,
          "quantity": 28,
          "unit_of_measure": "t",
          "distance_km": 820
        }
      ]
    }
  ]
}

Invoice fields

Field	Type		Description
vendor_name	`string`	required	Supplier / vendor name
invoice_date	`string`	required	ISO date (YYYY-MM-DD)
total_amount	`number`	optional	Invoice total. If omitted, computed from line items.
currency	`string`	optional	ISO 4217 code. Default: CHF
region	`string`	optional	ISO country code. Default: CH
line_items	`array`	required	At least one line item per invoice

Line item fields

Field	Type		Description
description	`string`	required	Line item description. The classifier uses this to assign an emission factor.
spend_amount	`number`	required	Amount in invoice currency
quantity	`number`	optional	Physical quantity (kWh, kg, km, TEU, etc.)
unit_of_measure	`string`	optional	Unit label for quantity
weight_tonnes	`number`	optional	Weight in metric tonnes (for freight)
distance_km	`number`	optional	Distance in km (for freight/travel)

Providing physical quantities (kWh, t, km) produces higher-confidence results than spend-only. Physical method = 0.85–0.95 confidence; spend-based = 0.55–0.75.

Response (success)

{
  "processed": 1,
  "invoices": [
    {
      "invoice_id": "bb387bb1-a2a3-4933-af02-3475a7753a68",
      "vendor_name": "Kuehne + Nagel AG",
      "line_items_created": 2,
      "total_kgco2e": 1287.40
    }
  ],
  "errors": []
}

Response (partial failure)

{
  "processed": 1,
  "invoices": [{ ... }],
  "errors": [
    {
      "index": 1,
      "vendor_name": "Bad Invoice",
      "error": "Missing invoice_date"
    }
  ]
}

Rate limits

Limit	Value
Invoices per request	100
Requests per hour	1'000

Error codes

HTTP	Meaning
400	Validation error (missing fields, empty array)
401	Missing or invalid API key
429	Rate limit exceeded
500	Server error (retry)

Example (curl)

curl -X POST https://cobank.ai/api/ingest \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "invoices": [{
      "vendor_name": "Office AG",
      "invoice_date": "2026-04-01",
      "total_amount": 1200,
      "currency": "CHF",
      "line_items": [{
        "description": "Office supplies",
        "spend_amount": 1200
      }]
    }]
  }'

POST /api/workpaper

Auditor workpaper operations. Requires JWT authentication from an auditor account.

Actions

Action	Description
`generate-sample`	Create a risk-weighted sample (ISA 530) for an engagement
`save-assertion`	Save/update a workpaper assertion on a line item
`re-perform`	Re-run emission calculation for comparison
`complete`	Mark engagement as completed (all items tested)
`export-evidence`	Download evidence package as ZIP

Example: export evidence

POST https://cobank.ai/api/workpaper
Authorization: Bearer <jwt>
Content-Type: application/json

{ "action": "export-evidence", "engagement_id": "UUID" }

Response: application/zip containing:

File	Content
`metadata.json`	Engagement details, period totals, testing summary
`workpapers.json`	Per-item assertion status, risk scores, factor details
`audit-trail.json`	SHA-256 hash chain entries for the period
`source-documents/*.pdf`	Original invoices (if available, max 10)

The engagement must be completed before export. Call complete first.

Webhooks

Coming in v2. Webhook notifications for invoice processing completion, period close, and amendment events.