Developers · API

The A2DB API

Send a supplier file from your own code — a PDF price list, an Excel sheet, a scan or a photo — and the MicroCity engine returns a clean product grid with a suggested column mapping, ready to feed a store or a database. It is the same API our WooCommerce plugin runs on. Five endpoints, key-based auth, JSON in and out.

Authentication

Every request carries your key in the X-A2DB-Key header. Generate (or regenerate) the key on your account page — any A2DB account has one, including the free tier. The key is your account: reads through the API count against the same daily quota as reads in the web app.

curl -H "X-A2DB-Key: a2db_XXXXXXXX" https://microcitylabs.com/api/plugin/ping
# -> {"ok": true, "email": "you@company.com", "plan": "free"}

The flow

Spreadsheets (xlsx, xls, csv, tsv) come back parsed in the upload response itself. PDFs and images(pdf, png, jpg, jpeg, webp) are read page by page: upload once, then start a read job per page and poll it. File limit: 25 MB.

POST/api/plugin/upload

Multipart form, one field named file. For a spreadsheet the answer is immediate:

curl -H "X-A2DB-Key: $KEY" -F "file=@pricelist.xlsx" \
  https://microcitylabs.com/api/plugin/upload
# -> {"upload_id": "...", "needs_read": false,
#     "grid": {"header": [...], "records": [[...], ...]},
#     "mapping": {"title": 1, "sku": 0, "price": 4, "description": 2, "qty": -1, "vendor": 3}}

For a PDF or image you get the page count instead: {"upload_id": "...", "needs_read": true, "pages": 12}

POST/api/plugin/read

Starts an engine read of one page. Body: {"upload_id": "...", "page": 1} (pages are 1-based). Each call counts one read against your daily quota — over the limit the answer is HTTP 429 with "quota": true.

# -> {"job_id": "f3a9...", "eta_s": 45}

GET/api/plugin/job/{job_id}

Poll until state is done — then the same grid and mapping shape as a spreadsheet upload. Anything the engine cannot read properly is flagged, not guessed.

POST/api/plugin/woo-products

Turns a grid into WooCommerce-ready product payloads (simple products, and variable products with variations when rows share a model). Body: {"header": [...], "records": [...], "mapping": {...}} — omit mappingto use the engine's guess.

# -> {"products": [ ...WooCommerce REST payloads... ], "count": 22}

The mapping object

Six fields — title, sku, price, description, qty, vendor — each holding a zero-based column index, or -1for “not in this file”. Several source columns can feed one field by joining indexes with + (for example "description": "2+5+6"— brand, specs and size merged into one description). The engine proposes the mapping from the file's own headers; you correct anything before using it.

Honest limits: files are processed on our servers and results returned to you — the API does not connect to your store or database itself (the WooCommerce plugin does the store side on your site). Reads are metered by your plan; see pricing.

Get a key and try it — free

Create a free account, copy your key from the account page, and run the curl above on your own price list. Questions: contact@microcitylabs.com.

Try it live — free See pricing