Developer API

In 30 seconds

1. Sign in to your Kesper dashboard → Settings → Developer API Keys.
2. Click New key, give it a label, copy the plaintext (it's only shown once).
3. POST your sales or inventory data to the endpoints below. Agents pick it up on the next run.

Authentication

Every ingest call needs a Bearer header with your API key. Keys look likekesper_<48 hex chars>and are tied to a single store.

Authorization: Bearer kesper_<48hex>
Content-Type: application/json

Plaintext keys are stored SHA-256-hashed at rest. If you lose a key, create a new one — there's no recovery path.

Endpoints

Transaction payload schema

Body is a JSON array of transaction objects. Required fields: transaction_id, timestamp (ISO 8601), items (array), total.

[
  {
    "transaction_id": "tx_2026_05_12_001",
    "timestamp": "2026-05-12T15:42:00Z",
    "items": [
      {
        "sku": "latte_12oz",
        "name": "12oz Latte",
        "qty": 1,
        "unit_price": 5.50,
        "cost": 1.20,
        "total": 5.50
      }
    ],
    "total": 5.50,
    "payment_method": "card"
  }
]

Inventory payload schema

Body is a JSON array of inventory items. Required fields: sku, name, qty_on_hand.

[
  {
    "sku": "latte_12oz",
    "name": "12oz Latte",
    "qty_on_hand": 87,
    "qty_on_order": 0,
    "cost": 1.20,
    "sell_price": 5.50,
    "category": "Beverages",
    "expiry_date": "2026-06-15",
    "last_sold": "2026-05-12T15:42:00Z"
  }
]

curl examples

Replace $KEY with your plaintext API key.

# Push 1 transaction
curl -X POST https://kesper-production.up.railway.app/api/ingest/transactions \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '[{"transaction_id":"tx1","timestamp":"2026-05-12T15:00:00Z","items":[{"sku":"latte","name":"12oz Latte","qty":1,"unit_price":5.5,"cost":1.2,"total":5.5}],"total":5.5,"payment_method":"card"}]'

# Push an inventory snapshot
curl -X POST https://kesper-production.up.railway.app/api/ingest/inventory \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '[{"sku":"latte","name":"12oz Latte","qty_on_hand":87,"qty_on_order":0,"cost":1.2,"sell_price":5.5,"category":"Beverages"}]'

Responses

Success responses use HTTP 200 and a small JSON body confirming the count ingested:

{ "ok": true, "ingested": 42, "storeId": "your_store_id" }

Common errors:

• 401 Bearer API key required — missing Authorization header.
• 401 Invalid or revoked API key — key not found or revoked.
• 400 Body must be a JSON array — wrong body shape.
• 400 Item N is missing required fields — schema violation; fix the listed item index.
• 400 Max 1000 transactions / 5000 items — split into multiple calls.
• 429 Ingest rate limited — max 120 requests per minute per key. Back off and retry.

Rate limits

• 120 requests/minute per API key on the ingest endpoints.
• 1000 transactions / 5000 inventory items per request body.
• Standard RateLimit-* response headers are returned so you can pace your client.

What happens after you push

Ingested data flows into the same persistence layer as our native connectors. The agents pick it up on their next scheduled run:

• FRIDAY rolls transactions into the daily store state.
• SCROOGE runs margin analysis on the items you pushed.
• SHERLOCK compares the new inventory snapshot to recent sales to flag ghost-stock and shrinkage.
• MONICA includes the relevant signals in tomorrow's 90-second brief.

Support

Questions about the API, schemas, or integration patterns? Email business@kesper.io.