API Reference

Vikka API v1

One API call to EU Battery Regulation compliance. All endpoints require an API key.

Authentication

Include your API key in every request:

curl https://your-domain.com/api/v1/passports \
  -H "Authorization: Bearer tk_your_api_key"

API keys are scoped to your organization. All passports you create are associated with your org. A key carries scopes — read and/or write: reads need read, creates and updates need write. Requests are rate-limited to 60/minute per key; every response carries X-RateLimit-* headers, and a 429 returns Retry-After.

List passports

GET/api/v1/passports

Returns a paginated list of your passports.

manufacturerstringFilter by manufacturer name (case-insensitive contains)
categorystringFilter by battery_category: EV, Industrial, or LMT
limitintegerMax results per page (default 50, max 200)
offsetintegerPagination offset (default 0)
// Response
{
  "object": "list",
  "data": [{ "id": "...", "name": "NMC 75kWh Pack", ... }],
  "total": 142,
  "limit": 50,
  "offset": 0,
  "has_more": true
}

Retrieve a passport

GET/api/v1/passports/:id

Returns a single passport by UUID. Responses carry your passport's own fields; internal system columns (org_id, readiness_score, and other server-managed state) are never returned.

// Response
{
  "object": "passport",
  "id": "7e8e0d80-...",
  "name": "NMC 75kWh Pack",
  "manufacturer": "Vossberg Power",
  "battery_category": "EV",
  "chemistry": "NMC 811",
  "carbon": 61.2,
  ...
}

Get compliance

GET/api/v1/passports/:id/compliance

EU Battery Regulation readiness for one passport, scored by the same engine the dashboard uses. Returns a completeness score, a per-chapter breakdown, per-rule status, and the next enforcement deadline.

// Response
{
  "object": "compliance",
  "passport_id": "7e8e0d80-...",
  "battery_category": "ev",
  "completeness": { "score": 72, "total_required": 69, "complete": 50, "missing": 19 },
  "next_deadline": { "date": "2027-02-18", "days_remaining": 232, "status": "upcoming" },
  "chapters": { "Carbon Footprint": { "total": 9, "complete": 7, "missing": 2 }, ... },
  "fields": [{ "rule_code": "AX13_1_A_MFR_NAME", "title": "Manufacturer name", "status": "complete", ... }]
}

Create a passport

POST/api/v1/passports

Create a new battery passport. Only name is required — all other fields are optional and map to EU Battery Regulation Annex XIII. The response returns the created passport (system fields omitted).

curl -X POST https://your-domain.com/api/v1/passports \
  -H "Authorization: Bearer tk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "NMC 75kWh Pack",
    "manufacturer": "Vossberg Power",
    "battery_category": "EV",
    "chemistry": "NMC 811",
    "capacity": 75,
    "carbon": 61.2,
    "carbon_method": "PEF",
    "gtin": "07312345678901",
    "warranty": 8
  }'

Update a passport

PUT/api/v1/passports/:id

Update fields on an existing passport. Only send the fields you want to change. Compliance is recalculated automatically.

curl -X PUT https://your-domain.com/api/v1/passports/:id \
  -H "Authorization: Bearer tk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "soh": 97.5, "carbon": 58.3 }'

Field reference (Annex XIII)

These are the fields tracked per EU Battery Regulation 2023/1542, Annex XIII.

General Information
name · battery_model · battery_category · chemistry · serial_number · batch_id · gtin · weight_kg · manufacturer · manufacturer_address · manufacturer_contact · country · manufacturing_date · manufacturing_place · hazardous_substances
Compliance
eu_declaration_of_conformity · conformity_body · test_report_ref
Carbon Footprint
carbon · carbon_method · carbon_performance_class · carbon_study_url
Recycled Content
rc_cobalt · rc_lithium · rc_nickel · rc_lead · renewable_content_pct
Performance & Durability
capacity · rated_capacity_ah · nominal_voltage · min_voltage · max_voltage · warranty · expected_lifetime_years · expected_lifetime_cycles · capacity_fade_pct · temp_range_min · temp_range_max · round_trip_efficiency · initial_internal_resistance · soh
Due Diligence
due_diligence_policy · third_party_audit_status · raw_material_sourcing
End-of-Life
collection_scheme · recycling_instructions · dismantling_info

Errors

All errors return a JSON object with error and message fields.

401missing_api_keyNo Authorization header provided
401invalid_api_keyAPI key not recognized
401revoked_api_keyAPI key has been revoked
403insufficient_scopeKey lacks the scope (read for GET, write for POST/PUT)
404not_foundPassport ID does not exist or belongs to another org
422validation_errorMissing required field (name)
429rate_limitedToo many requests — see Retry-After / X-RateLimit-* headers
Vikka API v1 · EU Battery Regulation 2023/1542