Agnotiq MarginTide Price Checker Agent - API reference v1

Quickstart

Mint a pck_… token at Settings → API keys, then set TOKEN=pck_… and run any of the examples below. Replace the production URL with http://localhost:3000 for local development.

# List recent runs (scope: runs:read)
curl -s https://price-checker.vercel.app/api/v1/runs \
  -H "Authorization: Bearer $TOKEN"

# Trigger a run (scope: runs:trigger)
curl -s -X POST https://price-checker.vercel.app/api/v1/runs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"subset_tags": ["core-skus"]}'

# List recommendations (scope: recommendations:read)
curl -s "https://price-checker.vercel.app/api/v1/recommendations?status=new" \
  -H "Authorization: Bearer $TOKEN"

# Accept a recommendation (scope: recommendations:write)
curl -s -X POST https://price-checker.vercel.app/api/v1/recommendations/$REC_ID/accept \
  -H "Authorization: Bearer $TOKEN"

# Approve a pending_approval recommendation - triggers Shopify write-back
# (scope: recommendations:approve - Max / Enterprise plan required)
curl -s -X POST https://price-checker.vercel.app/api/v1/recommendations/$REC_ID/approve \
  -H "Authorization: Bearer $TOKEN"

# Reject a pending_approval recommendation with a reason
# (scope: recommendations:approve)
curl -s -X POST https://price-checker.vercel.app/api/v1/recommendations/$REC_ID/reject \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason": "price too aggressive for Q3 margin target"}'

# Snooze an alert (scope: alerts:write)
curl -s -X POST https://price-checker.vercel.app/api/v1/alerts/$ALERT_ID/snooze \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"snooze_until": "2026-07-01T00:00:00Z", "reason": "supplier renegotiation"}'

# List catalog items (scope: catalog:read)
curl -s https://price-checker.vercel.app/api/v1/catalog/items \
  -H "Authorization: Bearer $TOKEN"

# Export report data (scope: reports:read)
curl -s https://price-checker.vercel.app/api/v1/reports/export \
  -H "Authorization: Bearer $TOKEN"

Workspace-status trust fields

GET /api/v1/workspace/status (scope: workspace:read) also returns two read-only transparency projections alongside lifecycle and usage — both are required response keys that are null when the underlying state is absent, never omitted.

support_access is non-null only while a platform support session is actively open against the caller’s own workspace — the owner-transparency view onto the consent-gated support-access flow. It carries only active, admin_email, started_at, and expires_at— never a session id, consent code, encrypted token, or any other workspace’s data.

account_deletion is non-null only while the calling user has an active (pending or blocked) account-deletion request, scoped strictly to that caller. It carries scheduled and effective_at — the purge-not-before date — so a client can surface a deletion-pending banner without a second request.

Error cheat-sheet

Re-sending an accept / dismiss / snooze / resolve / approve that already took effect returns 200 { "ok": true, "idempotent": true } - safe to retry on network failures. The approve endpoint uses CAS (compare-and-swap) for exactly-once Shopify store writes.