API reference

Connect your ERP or other systems to maintainkit inventory — read and write stock, and receive webhooks when it changes.

Base URL

https://maintainkit.app/api/v1

Authentication

Every request needs an API key, sent as a bearer token (or the X-API-Key header).

Create and manage keys in API & webhooks. Keys are scoped read or read & write, and only ever see their own organization's data.

curl https://maintainkit.app/api/v1/parts \
  -H "Authorization: Bearer mk_live_xxxxxxxx"

# or:  -H "X-API-Key: mk_live_xxxxxxxx"

Conventions

Requests and responses are JSON. Successful responses wrap the result in a "data" field.
Reference parts by numeric id or by sku, and locations by id or by name.
Money fields (unitCost) are integer cents — 18500 means $185.00.
Write operations need a read & write key; read-only keys get 403.

Errors return the matching HTTP status and a JSON envelope:

{ "error": { "code": "unprocessable", "message": "`sku` and `name` are required." } }

Endpoints

Parts

GET /parts List all parts with on-hand totals

POST /parts Create a part

GET /parts/:id Get a part with per-location stock

PATCH /parts/:id Update a part (name, min, cost, notes)

Locations

GET /locations List locations

POST /locations Create a location

Stock

GET /stock On-hand levels, filter by part or location

Movements

GET /movements List the movement ledger

POST /movements Record a stock movement

Recording stock movements

Send POST /movements with a kind. Stock totals are derived from this ledger.

receive Add stock into a location (optionally with unitCost).

consume Remove stock from a location.

adjust Apply a signed correction (qtyDelta, + or −).

count Set the absolute on-hand at a location (target).

transfer Move stock from one location to another.

Example — receive 20 L at a location:

curl -X POST https://maintainkit.app/api/v1/movements \
  -H "Authorization: Bearer mk_live_xxxxxxxx" \
  -H "content-type: application/json" \
  -d '{
    "kind": "receive",
    "sku": "OIL-15W40",
    "location": "Almacén Central",
    "qty": 20,
    "unitCost": 18500
  }'

# → { "data": { "partId": 3, "sku": "OIL-15W40", "onHand": 20, "unit": "L" } }

Transfer between locations:

{ "kind": "transfer", "sku": "OIL-15W40",
  "from": "Almacén Central", "to": "Camioneta de Alice", "qty": 5 }

Webhooks

stock.movement.created Any stock change (receive, consume, adjust, count, transfer).

stock.low On-hand dropped to or below a part's reorder point.

part.created A part was created.

part.updated A part's details changed.

Each delivery looks like this:

POST  (your endpoint)
X-MK-Event: stock.movement.created
X-MK-Signature: sha256=<hmac>

{
  "event": "stock.movement.created",
  "orgId": 1,
  "createdAt": 1780517417000,
  "data": { "partId": 3, "sku": "OIL-15W40", "locationId": 2,
            "qtyDelta": -2, "kind": "consume", "onHand": 18, "unit": "L" }
}

Verify the signature with your webhook secret:

import { createHmac } from 'node:crypto';

const expected = 'sha256=' + createHmac('sha256', WEBHOOK_SECRET)
  .update(rawBody)            // the exact bytes received
  .digest('hex');
const ok = request.headers['x-mk-signature'] === expected;

Healthy endpoints are called instantly. Failed deliveries retry with exponential backoff for several hours.