> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shopsniffer.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API overview

Base URL, authentication, response conventions, and the endpoint index for the ShopSniffer REST API.

## 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`](https://shopsniffer.com/api/openapi.json). The agent-discovery manifest is at [`/.well-known/agents.json`](https://shopsniffer.com/.well-known/agents.json).

## Authentication at a glance

| Method | Header | Use case |
| --- | --- | --- |
| **None** | — | Read-only: job status, reports, free export, public directory |
| **API key** | `X-API-Key: ss_…` | Scripts, CI, long-running AI agents |
| **Better Auth session** | Cookie (automatic) | Browser UIs on `shopsniffer.com` |
| **x402 payment** | `X-PAYMENT: …` | Account-free per-request payment |

See [authentication](/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 title="Response"
{
  "stores": [],
  "pagination": {
    "page": 2,
    "limit": 24,
    "total": 1847
  }
}
```

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

## Endpoint index

**[Jobs](/api/jobs)**

Create, fetch, poll, and retry store analysis jobs. Includes the WebSocket progress endpoint.
  **[Reports & downloads](/api/reports)**

Full report data, file downloads, PageSpeed audits, changelog.
  **[Monitoring](/api/monitoring)**

Track shops, snapshots, changes, compare diffs, analytics, inventory events.
  **[API keys](/api/keys)**

Create, list, and revoke API keys.
  **[Store directory](/api/directory)**

Browse the public directory of analyzed stores.
  **[AI chat](/api/chat)**

SSE streaming chat about any report, plus suggested prompts.
  **[Misc endpoints](/api/misc)**

OpenGraph, AnySpend, apps catalog, blog, OpenAPI spec, well-known.
  **[Rate limits](/rate-limits)**

Per-minute and per-day limits and 429 response shapes.

## Next steps

**[Authentication](/authentication)**

Pick an auth method and start making requests.
  **[AI agent integration](/agent-integration)**

Agent discovery files and recommended autonomous workflow.