ShadoU API

What you can do

• Connect external apps to a ShadoU account
• Import activities into ShadoU
• Export activity data from ShadoU
• Read athlete profile and activity summaries
• Sync workout data, posts, and selected account metadata
• Build coaching, training, and analytics integrations

Supported integration methods

• OAuth 2.0 authorization
• GPX file import
• Strava connect + import
• Direct API integration
• Future support may include FIT, TCX, and webhook-based sync

Register an App

To use OAuth 2.0, developers must register an application in the ShadoU developer area.

Redirect URI rules

• Must exactly match a registered redirect URI
• HTTPS is required for production
• Localhost may be allowed in development

Security Requirements

• Never expose a client secret in public frontend code
• Use PKCE for mobile and public clients
• Store tokens securely
• Use HTTPS only
• Request the minimum required scopes
• Refresh and revoke tokens safely

Token handling

• Access tokens are short-lived
• Refresh tokens may be used if enabled for your app
• Revoked or expired tokens must not be retried indefinitely

Activity Import API

Apps that have been authorized by a user may submit activity data to ShadoU through the API.

Beta endpoint examples

curl -X POST https://shadou.top/api/activities.php \
  -H 'Authorization: Bearer shd_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "sport_type":"walk",
    "started_at":"2026-04-12T06:00:00Z",
    "ended_at":"2026-04-12T06:42:16Z",
    "duration_seconds":2536,
    "distance_meters":8420,
    "step_count":10240,
    "source_app":"Partner App",
    "source_mode":"immerse",
    "profile_sync":{
      "display_name":"DenisZ",
      "primary_sport":"walk",
      "country_code":"SI"
    }
  }'

The activity ingest endpoint now scores uploads immediately, stores the backend verified scoring version, and in immerse mode can sync profile fields in the same request. For immersive activity social flow, call action=start when recording begins to create the live start post, then upload the completed activity to create the linked completion post. The Android app should show a local Projected Score from SHADOU_ACTIVITY_ALGORITHM.md; the backend Verified Score uses the same formulas after verification.

Workout ingest is now the durable model for ERG, mixed sessions, and future planned training. Use a stable client_workout_id, stable client_step_id for planned steps or repeat groups, stable client_effort_id for actual blocks, and monotonic sample seq values. Finishing a workout links meaningful efforts back to legacy activity rows so existing scoring, feed, and wallet behavior stays compatible.

Walking rules: tracked GPS walking uses 5 SADO / km at 10:00/km before factors. General pedometer-style steps are separate at 1 SADO / 1k steps, capped at 15,000 steps/day. Send step_count when available and use source_mode=general-steps for background daily step sync with a stable external_id per user + UTC day. Same-day background rewards are net of steps already rewarded through tracked activities so the same walking is not paid twice.

For create-post, send a stable client_post_id per submit attempt so double taps and timeout retries return the same post.

Reward policy: manual GPX uploads and Strava imports can still be imported and scored, but ŠADO wallet rewards are only credited for direct ShadoU app uploads received within 24 hours of the activity.

Rate Limits

• reasonable per-user and per-app limits apply
• burst abuse may be throttled
• repeated invalid requests may be blocked

If your integration needs higher limits, contact ShadoU support.

Versioning

The API should be versioned to preserve stability.

Breaking changes should only be introduced in a new version.

Errors

Error responses should include a clear machine-readable code and a human-readable message.

Webhooks

• new activity created
• activity updated
• coach booking events
• wallet events
• marketplace events