API overview

Overview

The ShopSniffer API is a REST-over-HTTPS API served from a single base URL. Most read endpoints are public; write endpoints and user-scoped reads require one of three auth methods. All responses are JSON except file downloads.

Base URL: https://shopsniffer.com/api

The machine-readable OpenAPI 3.1 spec is published at /api/openapi.json. The agent-discovery manifest is at /.well-known/agents.json.

Authentication at a glance

See authentication for the full method matrix and which endpoints accept which.

Conventions

• JSON everywhere. All request bodies and responses are application/json, except GET /api/downloads which streams raw file content.
• UUIDs for job IDs. Every job ID is a v4 UUID. Slugs are lowercase domain strings with dots replaced by hyphens (allbirds.com → allbirds-com).
• Timestamps are ISO 8601 UTC. All created_at / updated_at / completed_at fields use 2025-01-15T10:30:00Z format.
• Pagination uses page and limit query params. Default page=1, limits vary per endpoint (see individual endpoint docs). Responses include a pagination object with page, limit, and total.
• Errors are JSON with an error string field. HTTP status codes follow REST conventions: 400 client error, 401 missing auth, 402 payment required (x402), 403 forbidden, 404 not found, 409 conflict, 429 rate-limited, 5xx server error.

Pagination pattern

Endpoints that return lists accept page and limit and return a pagination object:

bash
curl "https://shopsniffer.com/api/stores?page=2&limit=24&search=sustainable"

json
{
  "stores": [],
  "pagination": {
    "page": 2,
    "limit": 24,
    "total": 1847
  }
}

To iterate all pages: fetch page=1, keep incrementing until (page * limit) >= total.

Endpoint index

Next steps