Language

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

The key is the only credential the API reads. Cookies from a signed-in GetSize account are ignored, so a call made from a browser where you are signed in, such as from the API reference, works on the API session it names and never on your account's own shoes. The API does not set cookies or keep server-side state between calls other than the sessions you create.

Plans and Developer Settings

Using the API requires an active plan. Sign in and open Developer Settings from the account menu to choose one. See plans for the limits of each.

Developer Settings is also where you create, rename and revoke keys, follow your usage against the monthly quota, download invoices and see the activity on your account.

Keys belong to your account and only work while it has a plan. If you cancel the Free plan, requests with your keys return 401 UNAUTHENTICATED until you activate a plan again; the same keys then work without any change to your integration.

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 and quota

Your plan sets two limits. Each key has a per-minute rate limit (fixed window aligned to UTC minutes); going over it returns 429 RATE_LIMITED. The account has a monthly quota shared by all its keys; once it is used up, requests return 429 QUOTA_EXCEEDED until it resets. The quota resets on the same day each month as the day the account turned on API access.

Both are exposed on every authenticated response, not only on 429:

  • X-RateLimit-Limit: requests allowed this minute.
  • X-RateLimit-Remaining: requests left in the current minute.
  • X-RateLimit-Reset: Unix epoch (seconds) when the minute resets.
  • X-Quota-Limit: requests allowed this month, on plans that have a quota.
  • X-Quota-Remaining: requests left this month.
  • X-Quota-Reset: Unix epoch (seconds) when the quota resets.
  • Retry-After (on 429 only): seconds until the minute, or the month, resets.

Self-pace from these headers rather than probing with retries. We email you when the account reaches 80% and 100% of its quota.

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, QUOTA_EXCEEDED, SESSION_NOT_FOUND, INVALID_INPUT, NOT_FOUND, LIMIT_EXCEEDED, INTERNAL_ERROR.

Next steps