REST API Reference

Base URL: {origin}/api/public/v1

Authentication

Every request must include an Authorization header with your Bearer API key. Create keys on the API Keys page.

Authorization: Bearer rfid_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Each key inherits the role and credit balance of its owner.
Keys are shown once at creation — store them like a password.
Revoked keys stop working immediately.

Quickstart (cURL)

# 1. List your products
curl -H "Authorization: Bearer $RFID_KEY" \
  https://your-domain.com/api/public/v1/products

# 2. Create a product
curl -X POST -H "Authorization: Bearer $RFID_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"T-Shirt","base_price":19.99}' \
  https://your-domain.com/api/public/v1/products

# 3. Mint 500 RFID tags
curl -X POST -H "Authorization: Bearer $RFID_KEY" \
  -H "Content-Type: application/json" \
  -d '{"quantity":500}' \
  https://your-domain.com/api/public/v1/products/PRODUCT_ID/rfids

# 4. Resolve scanned tags to products
curl -X POST -H "Authorization: Bearer $RFID_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tags":["A1B2C3D4E5F6A1B2C3D4E5F6"]}' \
  https://your-domain.com/api/public/v1/scan/lookup

Endpoints

GET

/api/public/v1/me

Get current account

Returns the profile that owns the API key: role, credit balance and hierarchy.

Response

{
  "data": {
    "id": "uuid",
    "name": "Warehouse A",
    "username": "warehousea",
    "role": "USER",
    "available_credits": 100,
    "parent_id": "uuid|null",
    "created_at": "2026-07-01T12:00:00Z"
  }
}

GET

/api/public/v1/products

List products

Returns every product created by this account, newest first.

Response

{
  "data": [
    { "id": "uuid", "name": "T-Shirt", "sku": "TSH-0001", "base_price": 19.99, "created_at": "..." }
  ]
}

POST

/api/public/v1/products

Create a product

SKU is auto-generated from the first 3 letters of the name plus a 4-digit counter.

Request body

{
  "name": "T-Shirt",
  "base_price": 19.99   // optional, defaults to 0
}

Response

{
  "data": { "id": "uuid", "name": "T-Shirt", "sku": "TSH-0001", "base_price": 19.99, "created_at": "..." }
}

POST

/api/public/v1/products/{productId}/rfids

Generate RFID batch

Deducts 1 credit per tag. Returns EPC-96 compliant (24 hex chars) tag list. The batch is downloadable for 7 days.

Request body

{ "quantity": 500 }

Response

{
  "data": {
    "batch_id": "uuid",
    "created_at": "...",
    "product": { "id": "uuid", "name": "T-Shirt", "sku": "TSH-0001" },
    "quantity": 500,
    "rfids": ["A1B2C3D4E5F6A1B2C3D4E5F6", "..."],
    "credits_remaining": 500
  }
}

Returns HTTP 402 with `insufficient_credits` when the account's credit balance is below the requested quantity.

GET

/api/public/v1/usage

List usage batches

Metadata for every RFID batch minted by this account. `expired: true` when older than 7 days.

Response

{
  "data": [
    { "id": "uuid", "created_at": "...", "credits_deducted": 500, "product_id": "uuid", "expired": false }
  ]
}

GET

/api/public/v1/usage/{batchId}

Get one batch (with tags)

Returns the full RFID list. Enforces the 7-day download lock — older batches return HTTP 410.

Response

{
  "data": {
    "id": "uuid",
    "created_at": "...",
    "product_id": "uuid",
    "credits_deducted": 500,
    "rfid_list": ["A1B2C3D4E5F6A1B2C3D4E5F6", "..."]
  }
}

POST

/api/public/v1/scan/lookup

Resolve scanned tags

Bulk-resolves EPC hex codes against your minted batches. Returns matched products, unit prices and total valuation.

Request body

{
  "tags": ["A1B2C3D4E5F6A1B2C3D4E5F6", "BADC0FFEE0DDF00DBADC0FFE"]
}

Response

{
  "data": {
    "total": 2,
    "matched": 1,
    "unmatched": 1,
    "total_value": 19.99,
    "results": [
      { "epc": "A1B2C3D4E5F6A1B2C3D4E5F6", "matched": true,  "product": { "id": "uuid", "name": "T-Shirt", "sku": "TSH-0001", "base_price": 19.99 } },
      { "epc": "BADC0FFEE0DDF00DBADC0FFE", "matched": false, "product": null }
    ]
  }
}

Error format

All errors follow the same JSON shape:

{ "error": "insufficient_credits", "message": "Insufficient Credits. Please contact your reseller to recharge." }

HTTP	error	Meaning
400	invalid_input	Request body failed validation.
401	missing_authorization	No Bearer token was provided.
401	invalid_key	The API key is not recognized.
401	revoked_key	The API key has been revoked.
402	insufficient_credits	Not enough credits to complete the operation.
404	not_found	The requested resource does not exist or you do not own it.
410	download_locked	Batch is older than 7 days — downloads are permanently locked.
500	internal_error	Unexpected server error.

Rate limits & fair use

RFID minting is bounded per request to 10,000 tags. Scan lookups accept up to 5,000 tags per call. Batch downloads are permanently locked 7 days after the batch was created.