Public API Overview

The GetSize Public API exposes shoe identification and size recommendation capabilities to external developers. Use it to embed GetSize recommendations in your own storefront, chatbot, or MCP tool.

Base URL

https://www.getsize.shoes/api/public/v1

Authentication

Every request requires an X-Api-Key header:

curl -H "X-Api-Key: gsk_live_..." https://www.getsize.shoes/api/public/v1/sessions -X POST

Keys are provisioned by GetSize admins. Contact us to obtain one.

Transport

HTTPS is mandatory. Our edge redirects plain HTTP to HTTPS, so a misconfigured client will typically see a 301/302 from the load balancer rather than a TLS_REQUIRED envelope. If you disable redirects and the app does see plain HTTP, it rejects the request with 400 TLS_REQUIRED.

Rate limits

Every key has a per-minute rate limit (default: 60 requests/minute, fixed window aligned to UTC minutes). Exceeding it returns 429 RATE_LIMITED.

Rate-limit state is exposed on every authenticated response (not only on 429):

  • X-RateLimit-Limit — total requests allowed this minute.
  • X-RateLimit-Remaining — requests remaining in the current window.
  • X-RateLimit-Reset — Unix epoch (seconds) when the window resets.
  • Retry-After (on 429 only) — integer seconds until the next window opens.

Self-pace from these headers rather than probing with retries.

CORS

This API is designed for server-to-server use. No CORS headers are emitted, so browser-based cross-origin requests will be blocked. Call from your backend only.

Error envelope

Every non-2xx response uses this shape:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry after 42 seconds.",
    "details": { "retryAfterSeconds": 42 }
  }
}

Codes: UNAUTHENTICATED, TLS_REQUIRED, TOO_MANY_AUTH_FAILURES, RATE_LIMITED, SESSION_NOT_FOUND, INVALID_INPUT, NOT_FOUND, LIMIT_EXCEEDED, INTERNAL_ERROR.

Next steps