API Overview

Live endpoints

Version 1 has two live endpoints on https://www.padelful.com:

• GET /api/v1/rackets: list and search rackets
• GET /api/v1/rackets/{slug}: get one racket

The Compare API, the Recommendations API and the hosted MCP server are not live. Their pages show the planned partner contract. A request to them returns 404.

Access

Padelful gives a partner key to each partner. To request a key, send an email to partners@padelful.com. Tell us who you are and how you will use the data.

Send the partner key in one of these two headers:

• Authorization: Bearer <partner-key>
• X-Api-Key: <partner-key>

When a request has both headers, the API uses the key in the Authorization header.

This request gets one racket. Replace <partner-key> with your partner key:

curl "https://www.padelful.com/api/v1/rackets/babolat-technical-viper-2025?locale=en" \
  -H "Authorization: Bearer <partner-key>"

The same request with the X-Api-Key header:

curl "https://www.padelful.com/api/v1/rackets/babolat-technical-viper-2025?locale=en" \
  -H "X-Api-Key: <partner-key>"

Keep your partner key on your server. Do not put it in browser code, a public repository or a log.

Missing or incorrect key

When the partner key is missing, incorrect or revoked, the API returns 401 with a WWW-Authenticate: Bearer header. The response contains no catalog data:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "A partner key is required. See https://www.padelful.com/en/data-terms and https://docs.padelful.com, or contact partners@padelful.com.",
    "requestId": "req_123"
  }
}

Tiers

Each partner key has a tier. The Data Terms of Use give the rules of each tier.

• Public fields: slug, title, model, brand, brandSlug, season, rating, ratings (the sub-ratings), summary, image, url, reviewUrl, language, updatedAt, prices, labSummary and attribution.
• Paid fields: pvp, materials, feel, shape, balance, game, genre, weight, players, eans, lab and, on the detail endpoint only, priceHistory.

A free-tier list request with a limit above 50 gets 50 rackets. A free-tier list request reads only the first 200 results: a page that ends after result 200 ends at result 200, and a request with an offset of 200 or more gets 403 with the code FREE_TIER_LIST_LIMIT. The paid tier reads the full list. The detail endpoint gives each racket to both tiers. pagination.limit gives the limit that the API used.

Attribution

Each racket has an attribution object:

{ "text": "Rating and review by Padelful", "url": "https://www.padelful.com/en/rackets/example-racket" }

Each page, screen or widget that shows Padelful data must show attribution.text and a visible, followable link to attribution.url. The Data Terms of Use give the full rule.

Base URL

• Production: https://www.padelful.com

Versioning

• Current version: v1
• Prefix all endpoints with /api/v1

Response envelope

Successful responses:

{
  "data": {},
  "meta": {
    "requestId": "req_123",
    "version": "v1",
    "locale": "en",
    "generatedAt": "2026-02-11T12:00:00.000Z"
  }
}

Error responses:

{
  "error": {
    "code": "INVALID_QUERY",
    "message": "Invalid query parameters",
    "details": {},
    "requestId": "req_123"
  }
}

Locale

• Supported locales: en, es
• Default locale: en

CORS

• The API sends CORS headers. A browser can send the preflight OPTIONS request with no partner key. We recommend that you call the API from your server, so that your partner key stays private.

Rate limits

• Each partner key can send 120 requests in one minute. This limit is for the list endpoint and the detail endpoint together.
• Requests with no valid partner key have a separate limit for each IP address.
• When a client reaches the limit, the API returns 429 with the code RATE_LIMITED and a Retry-After header. The header gives the number of seconds to wait before the next request.
• When a partner passes the day limit of its tier, the API returns 429 with the code DAILY_LIMIT and a Retry-After header that ends at midnight UTC.
• When a free-tier key asks for a list result after the first 200, the API returns 403 with the code FREE_TIER_LIST_LIMIT. The paid tier (Partner plan) reads the full list.
• When the API cannot check the key, it returns 503 with the code UNAVAILABLE. Try again later.

LLM consumption tips

• Prefer deterministic filters (brand, shape, minRating) over free-text only.
• Use includeJsonLd=true for richer product context.
• Cache list results and only re-fetch details on demand.