Partner API
Read-only HTTP access to SmartRunning workout and training plan templates. Partner platforms call the API server-to-server using a static API key; the key is scoped per integration and rate-limited per key.
The live machine-readable contract is served at /api/openapi.json, with an interactive Swagger UI at /api/docs on any running SmartRunning instance.
Authentication
Every request includes the X-API-Key HTTP header. Keys have the form sr_live_<lookup>_<secret> in production and sr_test_<lookup>_<secret> for integration testing.
Plaintext keys are shown exactly once at creation. SmartRunning stores only a bcrypt hash of the secret portion, and a short non-secret prefix used to locate the partner record on each request.
Revocation is immediate: once a key is revoked, the next request returns 401 Unauthorized.
Endpoints
| Method | Path | Purpose |
|---|---|---|
GET | /api/workout-templates | List public workout templates |
GET | /api/workout-templates/{id} | Fetch a single workout template |
GET | /api/training-plan-templates | List public training plan templates |
GET | /api/training-plan-templates/{id} | Fetch a single training plan template |
List endpoints support search, page, per_page, and updatedSince parameters (per_page is clamped to the range [1, 100]). Workout templates additionally accept category; training plan templates accept goalDistance. Full parameter and response schemas are in the OpenAPI document.
Versioning and incremental sync
Every template document carries a monotonic version integer (starts at 1, increments by 1 on every real change) and an updatedAt timestamp. Pass the highest updatedAt you've seen back as updatedSince on the next poll to fetch only what changed. The version field lets you detect modifications without diffing fields.
Visibility
Partners see only templates that are both public and active. Private or archived templates are excluded from listings, and fetching one by ID returns 404.
Rate limits
Authenticated partner requests are bucketed per key at 60 requests per minute and 10 000 requests per day. Exceeding either limit returns 429 Too Many Requests.
Example
curl -H "X-API-Key: sr_live_<lookup>_<secret>" \
'https://your-smartrunning-host/api/workout-templates?per_page=5'
Onboarding
Keys are provisioned by SmartRunning. To request access, describe your integration and contact us at hans@smartrunning.coach. We will mint a key, provide it to you over a secure channel, and note the scopes granted to the integration.