instacart-api

Instacart API Operations

Purpose

This repository is an Instacart-native API, not a generic commerce API. It wraps a logged-in Instacart.ca browser controller and exposes typed, safe endpoints for state, text, screenshots, analysis, and cart planning.

Controller setup

Default controller:

PORT=6082 \
START_URL='https://www.instacart.ca/store/?categoryFilter=homeTabForYou' \
USER_DATA_DIR='/home/hermes/shared-browser/profile-instacart' \
HEADLESS=true \
NODE_PATH=/home/hermes/shared-browser/node_modules:/home/hermes/.hermes/hermes-agent/node_modules \
node /home/hermes/shared-browser/server.js

API server:

cd /home/hermes/commerce-api
INSTACART_CONTROLLER_URL=http://127.0.0.1:6082 npm run dev

Native endpoints

Use /instacart/*:

• GET /health
• GET /instacart/state
• GET /instacart/text
• GET /instacart/screenshot.jpg
• GET /instacart/elements
• GET /instacart/analysis
• GET /instacart/vision
• GET /instacart/login, /login/status
• POST /instacart/login/start, /login/otp
• POST /instacart/goto
• POST /instacart/click, /type, /press, /scroll, /reload, /nav, /click-near-text
• POST /instacart/cart-plan

Legacy /apps/instacart/* aliases exist only for old dashboards. Do not add other app adapters here.

Safety invariants

• No checkout/payment/place-order route.
• cart-plan must default to checkoutBlocked: true.
• Non-Instacart surfaces should analyze as unknown instead of falling through to another parser.
• Keep user credentials inside the browser profile, never in API logs or repo files.
• Preferred login path is phone-number OTP: start with /instacart/login/status, then /instacart/login/start, /instacart/login/otp, and verify status again.

Verification

Run:

npm run check

Before reporting a cart task complete, also hit a live controller if available:

curl -s http://127.0.0.1:7077/health
curl -s http://127.0.0.1:7077/instacart/analysis