# Shoplens API

> REST API and MCP server with data on Shopify stores: store metrics, best-selling products, ads on Meta, Google and TikTok, and the people who work at each store's company.

Base URL: https://data.shoplens.dev/api/v1 (JSON over HTTPS). The REST API needs an API key (`Authorization: Bearer <key>`). The MCP server is at https://data.shoplens.dev/mcp and signs users in with OAuth through the Shoplens dashboard.

## Docs

- [OpenAPI 3.1 specification](https://data.shoplens.dev/api/v1/openapi.json): every endpoint, parameter, response and error. The source of truth for the endpoint reference.
- [Guide](https://data.shoplens.dev/llms-full.txt): concepts the specification cannot express (identifiers, pagination, on-demand shop lookup, how ads and people data is fetched and stored, monitors and webhooks, MCP tools). Read it together with the specification.

## Endpoints

- GET /api/v1/shops: search and rank shops
- GET /api/v1/shops/{domain}: shop details, best sellers, product types, similar shops
- GET /api/v1/shops/{domain}/ads: ads on Meta, Google and TikTok
- GET /api/v1/shops/{domain}/ads/{platform}: every ad on one platform, paginated
- GET /api/v1/shops/{domain}/people: people at the company
- POST /api/v1/shops/{domain}/people/{id}/reveal: reveal one person's contact
- GET, POST /api/v1/monitors and GET, PATCH, DELETE /api/v1/monitors/{id}: subscriptions to changes in shops, delivered as webhooks