Developer Guides

Authentication

All API requests require a Bearer token. Obtain one by logging in:

curl -X POST https://listerleo.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your-password"}'

Response:

{
  "data": {
    "token": "1|abc123...",
    "user": {
      "id": 1,
      "name": "Your Name",
      "email": "you@example.com",
      "organization": { "id": 1, "name": "Your Org", "slug": "your-org" },
      "roles": ["org-owner"]
    }
  }
}

Use the token in all subsequent requests:

Authorization: Bearer 1|abc123...

Quickstart

Scan an item in 3 API calls:

1. Look up the barcode

POST /api/scan/lookup
{ "barcode": "012345678901" }

2. Create the item

POST /api/scan
{
  "barcode": "012345678901",
  "lot_id": 1,
  "title": "Samsung 55\" 4K Smart TV",
  "condition": "LN",
  "starting_bid": 50.00
}

3. Confirm (catalog) the item

PUT /api/items/123/confirm
{
  "title": "Samsung 55\" 4K Smart TV",
  "condition": "LN",
  "starting_bid": 50.00,
  "description": "Like new, all accessories included."
}

Error Handling

The API uses standard HTTP status codes:

Validation errors return field-specific messages:

{
  "message": "The given data was invalid.",
  "errors": {
    "email": ["The email field is required."],
    "password": ["The password must be at least 8 characters."]
  }
}

Scanning Items

The scanning workflow supports three modes:

• Barcode scan — POST /scan/lookup followed by POST /scan
• Photo identification — POST /scan/photo-lookup (multipart) then poll GET /scan/photo-lookup/poll
• Manual entry — POST /scan with title/description directly

Items can be scanned into an existing lot (lot_id) or in lot-per-item mode (lot_per_item: true + vendor_id).

Cataloging

After scanning, items are in scanned status. Confirm them with final details to move to cataloged:

PUT /api/items/{id}/confirm
{
  "title": "...",
  "condition": "G",
  "description": "...",
  "starting_bid": 25.00
}

Put-Away

Three put-away modes:

• POST /put-away/item-to-location — Place item at a warehouse location
• POST /put-away/item-to-pallet — Place item on a pallet
• POST /put-away/pallet-to-location — Move pallet to a location

All accept flexible identifiers (serial number, barcode, or ID). Unknown location codes are auto-created.

Exporting

Generate CSV exports for auction platforms:

POST /api/exports
{
  "export_template_id": 1,
  "lot_id": 5
}

Then download: GET /api/exports/{id}/download

Supported platforms: HiBid, Proxibid, AuctionZip, and custom templates.

Order Picking

The picking workflow supports multiple concurrent pickers:

1. GET /pick-lists — List available pick lists
2. POST /pick-lists/{id}/claim — Claim items (row-locked, no duplicates)
3. POST /pick-lists/{id}/pick — Mark items as picked by serial/barcode
4. POST /pick-lists/{id}/release — Release unclaimed items when done

AI Enrichment

ListerLeo integrates with GlobalSKU for AI-powered product identification:

• Barcode lookup returns title, brand, description, and market pricing
• Photo identification works for items without barcodes
• Stock images are sourced from product databases
• Market value estimates from comparable sales data

Label Printing

Generate ZPL (Zebra) or ESC/POS (thermal) labels:

• POST /labels/serial — Item serial label with barcode
• POST /labels/shelf — Shelf/location label
• POST /labels/pallet — Pallet label
• POST /labels/login — Login badge barcode

Webhooks

Stripe webhooks are handled at POST /stripe/webhook for subscription management.

Export delivery supports webhook delivery to external URLs via scheduled exports.

Analytics

9 analytics endpoints under /analytics/:

dashboard, receiving, put-away, picking, vendor-performance, inventory-aging, revenue, throughput, user-productivity

All accept optional filters: date_from, date_to, warehouse_id, team_id, auction_id.

MCP Server

The ListerLeo MCP Server enables AI assistants to interact with the platform via the Model Context Protocol. Install via PyPI:

pip install listerleo-mcp

See the MCP documentation for full tool reference and setup guides.

OpenAPI Specification

The full OpenAPI 3.1 specification is available at:

• Interactive API Reference (Stoplight Elements)
• Download OpenAPI YAML