Scoperly Connect API

Base URL

https://api.scoperly.com/connect/v1

The machine-readable contract lives at /connect/v1/openapi.yaml — OpenAPI 3.1, no credential needed to fetch it. Generate a client from it rather than transcribing these pages by hand; a build check keeps it in step with the running API.

All API requests are made to this base URL. Country-specific deployments use their own subdomain (e.g. api.am.scoperly.com).

Versioning

The Connect API follows semantic versioning. v1 endpoints are stable and will be maintained with backward compatibility. Breaking changes will be released as v2 with a minimum 6-month migration period.

Authentication

The Connect API uses API keys for authentication. Each key is scoped to a specific supplier tenant. You can use the key directly as a Bearer token for simple requests, or exchange it for a short-lived JWT for session-based integrations.

# Direct API key usage
curl https://api.scoperly.com/connect/v1/supplier/catalog/products \
  -H "Authorization: Bearer sck_live_abc123def456..."

# Or exchange for JWT
curl -X POST https://api.scoperly.com/connect/v1/auth/token \
  -H "Authorization: Bearer sck_live_abc123def456..." \
  -H "Content-Type: application/json"

# Response:
# {
#   "access_token": "eyJ...xxxxx",
#   "token_type": "Bearer",
#   "expires_in": 1800,
#   "refresh_token": "crt_..."
# }

See the full Authentication guide for details on key management, scopes, and rotation.

Rate Limits

Rate limits are applied per API key. Check X-RateLimit-Remaining and X-RateLimit-Reset headers for current status. These headers are included in every response.

Error Format

All errors follow RFC 9457 Problem Detail format. The type field is a machine-readable error code you can switch on in your integration.

{
  "type": "STOCK_INSUFFICIENT",
  "title": "Not enough stock",
  "status": 422,
  "detail": "Product SKU-123 has only 5 units available (requested 10).",
  "instance": "/connect/v1/supplier/catalog/products/SKU-123/stock"
}

See the full Error Reference for all error types.