Machine-readable seller onboarding

Import API for AI agents

An agent acting for a builder, maker, dealer or supplier can preview and submit that seller’s inventory with one HTTP call. Every submission goes to the same human review as the seller form.

1. Preview

POST https://microhom.us/api/import with JSON. Nothing is stored. The response lists every product found, the department MicroHom suggests, why any item was skipped, and the trust checks a reviewer will see.

curl -s https://microhom.us/api/import \
  -H 'content-type: application/json' \
  -d '{"url": "https://yourstore.com/collections/cabins"}'

Or send rows you already have, with the seller’s website (every item URL must be on that site):

{"website": "https://yourstore.com",
 "items": [{"title": "12x16 Cabin Kit", "url": "https://yourstore.com/p/12x16",
            "price": 18950, "currency": "USD", "image": "https://yourstore.com/img/12x16.jpg",
            "stock": "In stock", "location": "Bend, OR", "type": "Cabin kit", "sqft": 192}]}

A CSV string also works: {"website": "https://yourstore.com", "csv": "title,url,price\n..."}. Use the CSV template columns.

Response

{"ok": true, "mode": "preview", "platform": "shopify",
 "source": {"host": "yourstore.com", "name": "Your Cabin Co."},
 "counts": {"found": 40, "listable": 31, "skipped": 9},
 "trust": {"level": "ok", "flags": []},
 "items": [{"id": "...", "title": "...", "url": "https://...", "price": 18950,
            "currency": "USD", "img": "https://...", "status": "In stock",
            "location": null, "dept": "cabins", "unit": false, "skip": null}]}

2. Submit for review

Send the same body with submit: true, the business name, a contact email and authorized: true. Only submit for a business that asked you to, and only with its permission.

curl -s https://microhom.us/api/import \
  -H 'content-type: application/json' \
  -d '{"url": "https://yourstore.com/collections/cabins",
       "submit": true,
       "business": "Your Cabin Co.",
       "email": "[email protected]",
       "authorized": true,
       "agent": "Name of your agent or tool"}'

The 201 response has an id and a one-time statusKey. Check progress with GET /api/import/status?id=…&key=…, or give the seller the statusPage link to open in a browser. Approved sellers get a page at https://microhom.us/#/s/<slug>.

Detected sources

Paste	MicroHom reads
Shopify store or `/collections/<handle>`	`/products.json` (title, price, compare-at price, stock, images)
WooCommerce store or `/product-category/<slug>/`	Store API `/wp-json/wc/store/v1/products`
WordPress site with listing post types	`/wp-json/wp/v2/<type>`; price and location only when the page labels them
Any product or category page	schema.org `Product` / `Offer` / `ItemList` JSON-LD, plus up to 12 linked product pages
Product sitemap (`.xml`)	Up to 10 product pages from it, read as JSON-LD
`.csv` or `.json` feed URL	Rows with title, url, price, image, stock, location (Google Merchant keys work)

Errors and limits

Code	Meaning
`https_only`, `bad_host`, `bad_port`, `private_ip`	Only public `https://` domains on port 443
`robots`	The site’s robots.txt doesn’t allow reading that address
`not_found`	No machine-readable products found; send `items` or `csv` instead
`missing_fields`	Submit needs `business`, a valid `email` and `authorized: true`
`rate_limited` (429)	About 20 previews an hour, and 2 API submissions a day, per network

Pages over 3 MB, more than 4 redirects or about 20 seconds of fetching end the import. Up to 200 items are kept per seller. All text is stored as plain text.