API Reference

Create and update your listings programmatically instead of uploading a CSV each time. The whole surface is four endpoints — read-only category data, and list/create/update for your own listings. There's no delete endpoint and no access to anyone else's listings.

• Authentication
• Errors & rate limits
• List categories
• List your items
• Create an item
• Update an item
• Full example

Authentication

Every request needs an API token in the Authorization header. Generate one from your account's API access page — it's shown exactly once, so store it somewhere safe. Generating a new token immediately revokes the old one; there's only ever one active token per account.

Authorization: Token sk_your_token_here

A missing or invalid token returns:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{"error": "Missing or malformed Authorization header."}

Errors & rate limits

Every response is JSON, including errors. Validation failures on POST/PATCH return 400 with a field-by-field breakdown:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{"errors": {"name": "This field is required."}}

Looking up, updating, or creating under someone else's listing isn't distinguished from that listing not existing at all — both return a plain 404, the same as everywhere else on Stoxsi.

Every endpoint is rate limited to 60 requests per 60 seconds, per token, shared across reads and writes. Going over it returns:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{"error": "Too many requests. Please slow down."}

List categories

Reference data for the category field below — every category, not just top-level ones.

curl https://www.stoxsi.com/api/v1/categories/ \
  -H "Authorization: Token sk_your_token_here"

{
  "categories": [
    {"id": 6, "name": "PLCs", "slug": "plcs", "parent": null},
    {"id": 9, "name": "I/O Modules", "slug": "io-modules", "parent": 6}
  ]
}

List your items

Only ever returns listings you own, newest first, 50 per page.

curl https://www.stoxsi.com/api/v1/items/ \
  -H "Authorization: Token sk_your_token_here"

curl "https://www.stoxsi.com/api/v1/items/?page=2" \
  -H "Authorization: Token sk_your_token_here"

{
  "items": [
    {
      "id": 28, "name": "CPU 1214C", "slug": "cpu-1214c", "category": "plcs",
      "description": "", "manufacturer": "Siemens", "part_number": "6ES7214-A",
      "condition": "used", "quantity": 3, "price": "210.00", "status": "active",
      "url": "/catalog/items/cpu-1214c/"
    }
  ],
  "page": 1,
  "num_pages": 1,
  "count": 1
}

Create an item

Runs through the exact same data-quality checks as the CSV bulk importer — a manufacturer spelling that already exists elsewhere on Stoxsi (e.g. SIEMENS vs. Siemens) is folded onto the existing one, and a (manufacturer, part number) pair you've already listed is rejected rather than duplicated.

curl -X POST https://www.stoxsi.com/api/v1/items/ \
  -H "Authorization: Token sk_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CPU 1214C",
    "category": "plcs",
    "manufacturer": "Siemens",
    "part_number": "6ES7214-A",
    "condition": "used",
    "quantity": 3,
    "price": "210.00"
  }'

Returns 201 Created with the new listing, in the same shape as the list endpoint above.

Update an item

Partial — send only the fields you want to change, same validation as create. There's no PUT/full-replace, and no way to change who owns a listing.

curl -X PATCH https://www.stoxsi.com/api/v1/items/28/ \
  -H "Authorization: Token sk_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"quantity": 50}'

Returns 200 OK with the full, updated listing.

Full example

Check what's already listed, create something new, then adjust its quantity — in Python, using requests:

import requests

API = "https://www.stoxsi.com/api/v1"
HEADERS = {"Authorization": "Token sk_your_token_here"}

# 1. Find the category slug to list under
categories = requests.get(f"{API}/categories/", headers=HEADERS).json()["categories"]
plcs = next(c["slug"] for c in categories if c["name"] == "PLCs")

# 2. Create a listing
created = requests.post(
    f"{API}/items/",
    headers=HEADERS,
    json={"name": "CPU 1214C", "category": plcs, "quantity": 3, "price": "210.00"},
).json()

# 3. Update it later
requests.patch(f"{API}/items/{created['id']}/", headers=HEADERS, json={"quantity": 50})