API Documentation

Check if a watch serial number appears in the multi-source stolen database.

Authentication

Include your API key in one of two ways:

Header: X-API-Key

X-API-Key: ak_live_xxxxxxxxxxxxxxxxxxxx

Header: Authorization Bearer

Authorization: Bearer ak_live_xxxxxxxxxxxxxxxxxxxx

Endpoint

GET

/api/v1/stolen/check

Query Parameters

serial (required)

Watch serial number to check. Case-insensitive.

brand (required)

Watch brand/manufacturer. Case-insensitive. Examples: Rolex, Omega, Patek Philippe.

Response

Success (200 OK)

{
  "serial_number": "123456",
  "brand": "Rolex",
  "overall_status": "clean",
  "overall_confidence": 0.85,
  "checked_at": "2026-04-04T15:30:00Z",
  "total_sources": 6,
  "sources_checked": 4,
  "has_alert": false,
  "sources": [
    {
      "source": "aikakone_registry",
      "sourceLabel": "Aikakone Community Registry",
      "status": "clean",
      "checked_at": "2026-04-04T15:30:00Z",
      "confidence": 1.0,
      "details": "Not found in Aikakone registry.",
      "responseTime": 45
    },
    {
      "source": "alpha_hands",
      "sourceLabel": "Alpha Hands",
      "status": "clean",
      "checked_at": "2026-04-04T15:30:00Z",
      "confidence": 0.8,
      "details": "Not found in Alpha Hands registry.",
      "responseTime": 150
    }
  ]
}

Status Codes

200

Check completed successfully

400

Missing or invalid parameters

401

Invalid or missing API key

429

Rate limit exceeded. Check X-RateLimit headers.

500

Server error. Try again later.

Rate Limiting

Default limits are 60 requests per minute and 10,000 per day. Check these headers in the response:

X-RateLimit-Limit-Minute

Requests allowed per minute

X-RateLimit-Remaining-Minute

Requests remaining in current minute

X-RateLimit-Reset-Minute

ISO timestamp when minute counter resets

X-RateLimit-Limit-Day

Requests allowed per day

X-RateLimit-Remaining-Day

Requests remaining in current day

X-RateLimit-Reset-Day

ISO timestamp when day counter resets

Code Examples

curl -H "X-API-Key: ak_live_xxxxxxxxxxxxxxxxxxxx" \
  "https://aikakone.io/api/v1/stolen/check?serial=123456&brand=Rolex"

Error Handling

All error responses include a JSON body with an error field:

{
  "error": "Invalid API key"
}

Common Errors

Missing API Key

Make sure to include the X-API-Key or Authorization header

Missing Parameters

Both serial and brand query parameters are required

Rate Limit Exceeded

Wait until the reset timestamp or contact us for higher limits

Best Practices

1. Store API Keys Securely

Never commit API keys to version control. Use environment variables or secrets management.

2. Implement Retry Logic

Handle 5xx errors with exponential backoff. Check rate limit headers before retrying.

3. Cache Results When Possible

Stolen status doesn't change frequently. Cache results for 24 hours to reduce API calls.

4. Monitor Rate Limits

Watch the X-RateLimit headers to stay within limits. Request higher limits if needed.

Questions or Issues?

Get Support