API Overview

The ReBattery Supplier API is a private JSON API for approved suppliers that need to synchronise battery inventory from an ERP, ingestion script, or trusted agent. It creates and manages listings inside the supplier account associated with the API key.

[!NOTE] This API is account-scoped. A key can never read or mutate another supplier's inventory, and it is not intended for browser-side code.

Quickstart

1. Create an API key

An account owner can create a key from Settings → API Keys. Choose only the scopes the integration needs, copy the key once, and store it in a secrets manager.

For the commands below, set local placeholders. Do not paste a real key into source control, support messages, or shared shell history.

export REBATTERY_API_KEY="replace-with-your-key"
export REBATTERY_IDEMPOTENCY_KEY="erp-42-create-2026-08-14"

2. Create a draft listing

Start with a draft while validating your mapping. The API does not invent missing battery facts.

curl --fail-with-body --silent --show-error \
  --request POST 'https://www.rebattery.io/api/v1/listings' \
  --header "Authorization: Bearer $REBATTERY_API_KEY" \
  --header "Idempotency-Key: $REBATTERY_IDEMPOTENCY_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "status": "draft",
    "reference": "ERP-42",
    "manufacturer": "Tesla",
    "model": "Model 3",
    "quantity": 2,
    "condition": "great",
    "channelMode": "sale"
  }'

A successful create returns 201 Created:

{
  "id": "6a27eb6e-e5f6-4457-a55d-0ad4c4fe1cd6",
  "reference": "ERP-42",
  "slug": "tesla-model-3-a1b2",
  "status": "draft",
  "revision": 1
}

Save the returned id. The slug and title are generated by ReBattery and cannot be supplied by the integration.

3. Read the listing and revision

Use --include to see the response headers. The ETag contains the quoted numeric revision needed for edits and lifecycle actions.

curl --include --silent --show-error \
  'https://www.rebattery.io/api/v1/listings/6a27eb6e-e5f6-4457-a55d-0ad4c4fe1cd6' \
  --header "Authorization: Bearer $REBATTERY_API_KEY"

HTTP/2 200
content-type: application/json
etag: "1"
cache-control: private, no-store

Continue with the Listing endpoints reference to edit fields, append images, publish, or withdraw the listing.

Base URL and format

The bare rebattery.io domain redirects to www.rebattery.io. Use the canonical www URL directly. Staging credentials and URLs are provided during integration onboarding; never send test inventory to production.

Download the machine-readable OpenAPI 3.1 contract for schema inspection, client generation, or contract tests. The written guides remain the source for workflow and safety guidance.

Authentication and scopes

Send the API key on every request:

Authorization: Bearer <your-api-key>

Missing, expired, revoked, and malformed keys receive the same generic 401 response. A valid key without the required scope receives 403.

[!WARNING] API keys are server credentials. Keep them in a secrets manager or server-side environment variable, grant the minimum scope, rotate them, and revoke unused keys. Never expose a key in browser JavaScript or a mobile application.

Mutation safety

Every mutation requires an Idempotency-Key containing 1–255 characters. Generate a new, stable key for each business intent, such as one ERP row plus its source revision.

Idempotency-Key: erp-42-edit-9

The same key, method, path, and body replay the original result for 24 hours. Reusing a key for a different intent returns 409 Conflict. If the first request is still running, the API returns 425 Too Early; wait briefly and retry the identical request.

Edits, image appends, publish, and withdraw also use optimistic concurrency:

1. Read the listing and retain its ETag.
2. Send that exact value in If-Match with a new idempotency key.
3. After success, retain the new ETag returned by the mutation.

If-Match: "12"

A missing If-Match returns 428 Precondition Required. A stale revision returns 412 Precondition Failed. Read the current listing, reconcile the changes, and submit a new mutation intent instead of overwriting newer data.

Rate and request limits

The API permits 100 requests per 60 seconds per API key. Every 429 response includes Retry-After. Collection requests also include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.

Respect Retry-After. Otherwise use exponential backoff with jitter for retryable failures. Avoid running large numbers of concurrent listing mutations against the same inventory.

Mutation bodies must use Content-Type: application/json. Malformed JSON returns 400, another media type returns 415, and a body over 40 MB returns 413.

Response conventions

• All authenticated responses are private, no-store.
• Collection reads return summaries and offset pagination.
• An ID read returns the complete editable resource plus ETag.
• Mutations return a compact durable acknowledgement; read the listing again when you need its complete current representation.
• Unknown, malformed, and other-account listing IDs all return the same 404 response.
• Validation failures use 422 with field-level guidance where available.

See Errors and retries for the complete status table and safe retry rules.

Versioning

The current contract is v1. Breaking changes require a new versioned path. Backward-compatible additions may appear in v1, so clients should ignore unknown response fields.

Before upgrading a production integration, run its contract tests against the staging URL and a synthetic supplier account.

Next steps

• Listing endpoints — methods, headers, fields, examples, and responses.
• Errors and retries — status codes, idempotent recovery, and troubleshooting.
• Import Listings from CSV or Excel — use the platform importer when an HTTP integration is unnecessary.