API Overview

The ReBattery Supplier API lets approved suppliers sync battery inventory directly into ReBattery, so listings can be routed towards resale, reuse, or recycling through verified partners and managed compliance workflows. This is not a simple marketplace listing tool — it is an integration layer that feeds inventory into a managed supply chain with routing logic based on battery condition, chemistry, and regulatory requirements.

The API is intended for supplier ERP integrations, ingestion scripts, and automated partner feeds. It is designed to be predictable, with JSON request bodies and standard HTTP response codes.

Base URL

All API requests should be directed to the following base URL:

https://www.rebattery.io/api/v1

The bare domain rebattery.io redirects to www.rebattery.io.

Sandbox and test environment URLs are provided by your ReBattery contact during onboarding.

Authentication

The ReBattery Supplier API uses Bearer token authentication. All requests must include an Authorization header with a valid API key:

Authorization: Bearer <your-api-key>

API keys are created and managed from Settings → API Keys in your ReBattery account. Only the account owner can generate keys. Each key is shown exactly once at creation, can have an expiry, and can be revoked immediately; copy it into a secure secrets manager because it cannot be retrieved again.

Supplier account owners can also connect a trusted AI agent from New Listing. ReBattery generates a copyable prompt with a ten-minute, one-time setup code. The code exchanges once for a 30-day key named AI agent connection with only listings:write access. The key is delivered only to the agent's HTTPS exchange response and must be stored in that agent's local secret manager. Generating a replacement prompt revokes the prior AI-agent connection; the owner can also revoke it at any time from Settings → API Keys.

If a token is invalid, missing, or expired, the API returns a generic 401 response with no additional detail. This prevents token enumeration.

All requests must be made over HTTPS. Unencrypted HTTP requests are rejected.

[!WARNING] Store your API keys in a secure secrets manager or environment variable. Never commit them to version control or expose them in client-side code.

Scopes

Each API key must include the scope required by the endpoint it calls:

Rate Limits

The API enforces a limit of 100 requests per 60-second window per API key.

If you exceed the limit, the API returns a 429 Too Many Requests response with the following headers:

[!TIP] Implement exponential backoff with jitter in your integration to handle rate-limit responses gracefully. A typical approach retries after 1, 2, 4, 8, and 16 seconds.

Idempotency

To safely retry a POST /listings request without duplicating side effects, include an Idempotency-Key header with a unique string between 1 and 255 characters:

Idempotency-Key: <unique-key>

If the same key and request body are resent within a 24-hour window, the API returns the original response without reprocessing. If the same key is reused with a different request body, the request is rejected with 409 Conflict. If a request with that key is still being processed, the API returns 425 Too Early.

[!NOTE] We recommend using UUIDs as idempotency keys. Most programming languages include a standard library function to generate v4 UUIDs securely.

Request Limits

• Maximum request body size: 40 MB
• Request body: JSON object

Requests that exceed the body limit receive 413 Payload Too Large. Malformed JSON receives 400 Invalid JSON body.

Creating a listing

POST /listings accepts only documented fields. Set status to draft to persist structurally valid partial data, or published to publish only after the canonical listing readiness policy passes. A failed published request is never reported as published.

condition is either one canonical batch grade (new, excellent, great, functional, or end_of_life) or an array of existing unit-condition records. A unit array must contain exactly one record per quantity; ReBattery projects aggregate compatibility fields through the canonical listing condition model.

{
  "status": "draft",
  "reference": "ERP-42",
  "quantity": 2,
  "condition": [
    { "id": "unit-1", "condition": "great" },
    { "id": "unit-2", "condition": null }
  ]
}

manualReview and publish are legacy fields and receive field-specific 422 validation errors. Suppliers cannot submit titles or slugs; ReBattery generates both. Image failures are returned explicitly, and retries should use the same idempotency key.

Request fields

• Commercial and identity: status, channelMode, buyItNowPrice, minimumOfferPrice, currency, minimumOrderQuantity, reference, description, manufacturer, model, chemistry, category, cellChemistryDetail, format, and quantity.
• Condition and compliance: condition, conditionDeclaration, damageDetails, damageHistory, testDataOption, hasSafetyDataSheet, hasComplianceSDS, hasComplianceUN383, hasForklift, collectionSchedule, and recyclingPackagingDetails.
• Technical details: packKwh, packWeightKg, yearManufacture, originalApplication, usageDetails, soh, dimL, dimW, dimH, architectureVoltage, voltageNominal, socVolts, partNumber, vin, cycleCount, cellFormat, cellConfiguration, batteryPlatform, numCells, internalResistance, temperature, testDate, testMethod, and stateOfCharge.
• Collection and media: locationCountry, locationRegion, locationCity, exactly one of collectionAddress, useAccountAddress, or address, plus up to ten images supplied by HTTPS URL or base64 data.

category is one of ev, e_mobility, industrial, energy_storage, marine, or other. collectionSchedule has mon through fri; each day is { "enabled": boolean, "start": "HH:MM", "end": "HH:MM" }. damageHistory accepts fire_affected, water_damaged, impact, and thermal_event. testDataOption is upload_now, available_on_request, or skip.

Versioning

The current API is v1, accessible at /api/v1. Breaking changes will be introduced under a new versioned path (e.g., /api/v2). Non-breaking changes, such as additional optional fields in existing responses, may be added to v1 without prior notice. Your integration should ignore unknown fields rather than fail on them.