Sessions

A session represents one end user of your integration. It holds the shoes they own and their foot measurement, and is the scope within which a recommendation is computed.

Lifecycle

  • Create at the start of each end-user conversation with POST /sessions.
  • The returned sessionId is an opaque string. Pass it in the URL of subsequent calls.
  • Sessions expire after 7 days of inactivity by default. Expired sessions return SESSION_NOT_FOUND.
  • Each session is bound to the developer key that created it. Other keys cannot access it even if they know the id.
  • Delete a session explicitly with DELETE /sessions/{id}. Deletion also wipes any shoes and the foot measurement associated with it.

Inactivity TTL

Every authenticated session call — GET or POST — renews the 7-day inactivity clock. expiresAt on the session view reflects the freshly extended timestamp; read it back after any call if you need an authoritative value. There is no separate "extend" endpoint; a cheap GET /sessions/{id} is the canonical heartbeat.

Session-per-conversation rule

Never share a session across conversations. Each end user should get their own session. Reusing sessions leaks shoe data between users.

Endpoints

POST   /api/public/v1/sessions
GET    /api/public/v1/sessions/{sessionId}
DELETE /api/public/v1/sessions/{sessionId}

POST   /api/public/v1/sessions/{sessionId}/shoes
GET    /api/public/v1/sessions/{sessionId}/shoes
DELETE /api/public/v1/sessions/{sessionId}/shoes/{shoeId}

POST   /api/public/v1/sessions/{sessionId}/foot-measurement
GET    /api/public/v1/sessions/{sessionId}/foot-measurement

POST   /api/public/v1/sessions/{sessionId}/recommendations

Limits

  • Max 20 shoes per session. The 21st POST /shoes returns 409 LIMIT_EXCEEDED. Remove one with DELETE /shoes/{shoeId} before adding another.
  • Max 1 foot measurement per session. A second POST /foot-measurement returns 409 LIMIT_EXCEEDED; clear the existing measurement by deleting the session (there is no endpoint to replace a single measurement in place).

Foot-measurement request shape

The public API stores left and right lengths separately so asymmetric feet are recommended on the larger side:

POST /sessions/{id}/foot-measurement
{ "rightFootLengthMm": 268, "leftFootLengthMm": 270 }

Values must be in the range 100..400 mm. The internal /api/v2/sizing/** surface uses a single lengthMm field — that is not the canonical public API and integrators should use /api/public/v1/** exclusively.