API Documentation

Quick Start

Make your first API call in under 2 minutes

1

Sign up and get your API key from the Developer Dashboard

2

Make your first request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.kello.app/api/v1/watches?per_page=5"

3

Explore the response

{
  "data": [
    {
      "id": 1,
      "brand": "Rolex",
      "collection": "Submariner",
      "reference_number": "126610LN",
      "retail_price_usd": 10250,
      "current_market_price": 12800
    }
  ],
  "meta": { "current_page": 1, "per_page": 5, "total": 10432 }
}

Authentication

All API requests require a Bearer token in the Authorization header.

Base URL

https://api.kello.app/api/v1

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.kello.app/api/v1/watches

Sign up and get your API key from the Developer Dashboard

Endpoints

Core endpoints for accessing watch data

JSONB Spec Filtering

Filter watches by any specification stored in the JSONB specs column using the special spec[] query parameter syntax.

Pass spec keys as bracket-notation query parameters. Multiple spec filters are combined with AND logic — all must match.

?spec[key]=value&spec[another_key]=value

Common Spec Keys

spec[movement_type] spec[case_material] spec[dial_color] spec[water_resistance] spec[crystal] spec[power_reserve] spec[case_shape] spec[bracelet_material]

Try it

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.kello.app/api/v1/watches?spec[movement_type]=automatic&spec[case_material]=gold"

Error Responses

All errors return a consistent JSON structure with an appropriate HTTP status code.

401Unauthenticated

Missing or invalid API key. Include a valid Bearer token in the Authorization header.

{ "message": "Unauthenticated." }

403Forbidden

Your subscription tier does not grant access to this resource or action.

{ "message": "Your plan does not include access to this resource." }

404Not Found

The requested resource (watch, brand, webhook, etc.) was not found.

{ "message": "Resource not found." }

422Validation Error

Request body or query parameters failed validation. Check the errors object for field-level details.

{
  "message": "The given data was invalid.",
  "errors": {
    "endpoint_url": ["The endpoint url field is required."]
  }
}

429Rate Limited

You have exceeded your rate limit. Wait until the Retry-After period expires before retrying.

{
  "message": "Too many requests. Please retry after the period indicated in the Retry-After header."
}

Rate Limits

API rate limits vary by subscription tier

Plan	requests/day	Price
Free	50	Free
ProPopular	500	$59/month
Platinum	1,500	$79/month

Need more requests?

Upgrade Plan

Rate Limit Headers

Every API response includes headers to help you track your rate limit usage.

Header	Description
X-RateLimit-Limit	Maximum number of requests allowed per day for your plan
X-RateLimit-Remaining	Number of requests remaining in the current period
X-RateLimit-Reset	Unix timestamp when the rate limit resets
Retry-After	Seconds to wait before retrying (only present on 429 responses)

Example

HTTP/1.1 200 OK
X-RateLimit-Limit: 50
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1712160000

HTTP/1.1 429 Too Many Requests
Retry-After: 3600
X-RateLimit-Limit: 50
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1712160000