Getting started

1. Choose a plan and create an API key

The API requires an active plan. Sign in, open Developer Settings from the account menu and activate a plan. Then create a key under API keys. The raw key is shown exactly once on creation, so store it in your secret manager immediately.

2. Create a session

A session represents one end user of your integration. Create one at the start of each end-user conversation:

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

{
  "sessionId": "abc123-def456-...",
  "createdAt": "2026-04-15T10:00:00Z",
  "expiresAt": "2026-04-22T10:00:00Z",
  "shoeCount": 0,
  "hasFootMeasurement": false
}

Store sessionId; every subsequent call threads it through the URL.

3. Add a foot measurement (optional)

curl -X POST https://www.getsize.shoes/api/public/v1/sessions/$SESSION_ID/foot-measurement \
  -H "X-Api-Key: gsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"rightFootLengthMm": 268, "leftFootLengthMm": 270}'

4. Identify a shoe the user owns

Walk the catalog with /shoe-selection: send the user's picks so far as selection.answers, show the options in nextStep, append the picked id and call again until complete is true.

curl -X POST https://www.getsize.shoes/api/public/v1/shoe-selection \
  -H "X-Api-Key: gsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"purpose": "ADD_TO_RACK", "selection": {"answers": ["nike", "FD2722", "FD2722-002", "US_MALE", "10"]}}'

{
  "selection": { "answers": ["nike", "FD2722", "FD2722-002", "US_MALE", "10"], "metadata": {} },
  "complete": true,
  "nextStep": null,
  "shoe": { "brandId": "nike", "modelId": "FD2722", "sizeSystem": "US_MALE", "size": "10", "lengthMm": 265, ... }
}

See Identifying shoes for the full pattern.

5. Add the identified shoe to the session rack

curl -X POST https://www.getsize.shoes/api/public/v1/sessions/$SESSION_ID/shoes \
  -H "X-Api-Key: gsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"shoe": {"answers": ["nike", "FD2722", "FD2722-002", "US_MALE", "10"], "metadata": {}}}'

{
  "id": 18825,
  "brandId": "nike",
  "modelId": "FD2722",
  ...
}

shoe takes the completed selection from step 4, not the shoe object in that response. Keep the returned id if you may want to remove the shoe later with DELETE /sessions/$SESSION_ID/shoes/{id}.

6. Get a size recommendation for a target shoe

Walk /shoe-selection again with "purpose": "RECOMMENDATION_TARGET" for the shoe the user is considering. That walk completes without a size, and its selection is the target.

curl -X POST https://www.getsize.shoes/api/public/v1/sessions/$SESSION_ID/recommendations \
  -H "X-Api-Key: gsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"target": {"answers": ["adidas", "SAMBAU2312", "KZ6720", "EU"], "metadata": {}}}'

{
  "recommendedSize": "44",
  "sizeSystem": "EU",
  "confidenceBasis": [ ... ]
}