Endurain API

openapi: 3.1.0
info:
  title: Endurain API
  version: '2026-10-28'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-10-28: 23 operation(s) read from 8 public documentation page(s) (each operation
    names its page in x-source). This is not the provider''s published contract; Endurain has published no machine-readable contract that the
    pipeline could find. Engine: local.'
  x-evidence-tiers:
    code-example: 3
    documentation: 20
    pages-with-code: 1
    pages-read: 8
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-10-28'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://docs.endurain.com/reference/garmin
  - https://docs.endurain.com/reference/strava
  - https://docs.endurain.com/integrate/api-keys
  - https://docs.endurain.com/getting-started/bare-metal
  - https://docs.endurain.com/developer-guide/writing-docs
  - https://docs.endurain.com/integrate/authentication
  - https://docs.endurain.com/integrate/account-security
  - https://docs.endurain.com/integrate/oauth-sso-pkce
paths:
  /activities/create/upload:
    post:
      operationId: post_activities_create_upload
      tags:
      - Activities
      summary: Upload a .gpx, .tcx, .fit, or .gz activity file
      x-source: https://docs.endurain.com/integrate/api-keys
      parameters:
      - name: X-API-Key
        in: header
        required: true
        schema:
          type: string
        description: Raw API key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostActivitiesCreateUploadRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /activities/ingestion-jobs/{jobId}:
    get:
      operationId: get_activities_ingestion_jobs_jobId
      tags:
      - Activities
      summary: Garmin Connect linking and sync.
      x-source: https://docs.endurain.com/reference/garmin
      parameters:
      - name: jobId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/v1/activities:
    get:
      operationId: get_api_v1_activities
      tags:
      - Api
      summary: Retrieve the authenticated user's activities.
      x-source: https://docs.endurain.com/integrate/oauth-sso-pkce
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/v1/activities/create/upload:
    post:
      operationId: post_api_v1_activities_create_upload
      tags:
      - Api
      summary: Upload a .gpx, .tcx, .fit, or .gz activity file
      x-source: https://docs.endurain.com/integrate/api-keys
      parameters:
      - name: X-API-Key
        in: header
        required: true
        schema:
          type: string
        description: Raw API key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1ActivitiesCreateUploadRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/v1/auth/login:
    post:
      operationId: post_api_v1_auth_login
      tags:
      - Api
      summary: Initial Login Request
      x-source: https://docs.endurain.com/integrate/account-security
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1AuthLoginRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV1AuthLoginResponse'
      x-evidence:
        kind: documentation
  /api/v1/auth/mfa/verify:
    post:
      operationId: post_api_v1_auth_mfa_verify
      tags:
      - Api
      summary: MFA Verification
      x-source: https://docs.endurain.com/integrate/account-security
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1AuthMfaVerifyRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV1AuthMfaVerifyResponse'
      x-evidence:
        kind: documentation
  /api/v1/auth/refresh:
    post:
      operationId: post_api_v1_auth_refresh
      tags:
      - Api
      summary: Authentication - Endurain documentation
      x-source: https://docs.endurain.com/integrate/authentication
      parameters:
      - name: X-Client-Type
        in: header
        required: true
        schema:
          type: string
        description: web
      - name: X-CSRF-Token
        in: header
        required: false
        schema:
          type: string
        description: Current CSRF token (optional for bootstrap refresh)
      - name: endurain_refresh_token
        in: header
        required: true
        schema:
          type: string
        description: Refresh token cookie
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV1AuthRefreshResponse'
      x-evidence:
        kind: documentation
  /api/v1/profile/api_keys:
    post:
      operationId: post_api_v1_profile_api_keys
      tags:
      - Api
      summary: Create API Key Request
      x-source: https://docs.endurain.com/integrate/api-keys
      parameters:
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
        description: Bearer {access_token}
      - name: X-Client-Type
        in: header
        required: true
        schema:
          type: string
        description: web
      - name: X-CSRF-Token
        in: header
        required: true
        schema:
          type: string
        description: CSRF token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1ProfileApiKeysRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV1ProfileApiKeysResponse'
      x-evidence:
        kind: documentation
  /api/v1/profile/mfa/backup-codes:
    post:
      operationId: post_api_v1_profile_mfa_backup_codes
      tags:
      - Api
      summary: Regenerate Backup Codes
      x-source: https://docs.endurain.com/integrate/account-security
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1ProfileMfaBackupCodesRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV1ProfileMfaBackupCodesResponse'
      x-evidence:
        kind: documentation
  /api/v1/public/idp/login/{idpSlug}:
    get:
      operationId: get_api_v1_public_idp_login_idpSlug
      tags:
      - Api
      summary: Initiate OAuth login with PKCE challenge.
      x-source: https://docs.endurain.com/integrate/oauth-sso-pkce
      parameters:
      - name: idpSlug
        in: path
        required: true
        schema:
          type: string
      - name: code_challenge
        in: query
        required: true
        schema:
          type: string
        description: Base64url‑encoded SHA256 hash of code_verifier.
      - name: code_challenge_method
        in: query
        required: true
        schema:
          type: string
        description: Must be S256.
      - name: redirect
        in: query
        required: false
        schema:
          type: string
        description: Frontend path after successful login.
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/v1/public/idp/session/{sessionId}/tokens:
    post:
      operationId: post_api_v1_public_idp_session_sessionId_tokens
      tags:
      - Api
      summary: Exchange a session for access and refresh tokens (PKCE verification).
      x-source: https://docs.endurain.com/integrate/oauth-sso-pkce
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1PublicIdpSessionSessionidTokensRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV1PublicIdpSessionSessionidTokensResponse'
      x-evidence:
        kind: documentation
  /auth/refresh:
    post:
      operationId: post_auth_refresh
      tags:
      - Auth
      summary: Authentication - Endurain documentation
      x-source: https://docs.endurain.com/integrate/authentication
      parameters:
      - name: X-Client-Type
        in: header
        required: true
        schema:
          type: string
        description: web
      - name: X-CSRF-Token
        in: header
        required: false
        schema:
          type: string
        description: Current CSRF token (optional for bootstrap refresh)
      - name: endurain_refresh_token
        in: header
        required: true
        schema:
          type: string
        description: Refresh token cookie
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostAuthRefreshResponse'
      x-evidence:
        kind: documentation
  /endurain-project/endurain/archive/refs/tags:
    get:
      operationId: get_endurain_project_endurain_archive_refs_tags
      tags:
      - Endurain Project
      summary: GET /endurain-project/endurain/archive/refs/tags
      x-source: https://docs.endurain.com/getting-started/bare-metal
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl -L \"https://github.com/endurain-project/endurain/archive/refs/tags/ $TAG .tar.gz\"  | tar xz\n EXTRACTED = $( ls -d endurain-*\
          \ ) \n shopt -s dotglob\nmv \" $EXTRACTED \" /* .\n shopt -u dotglob\nrm -rf \" $EXTRACTED \" \n 4. Create Environment Configuration\
          \ \n Prepare data storage. \n mkdir -p /path/to/endurain_data/{ data,logs } \n Copy the provided example. \n cp /path/to/endurain/.env.example/path/to/end"
  /profile/api_keys:
    get:
      operationId: get_profile_api_keys
      tags:
      - Profile
      summary: List API Keys Response
      x-source: https://docs.endurain.com/integrate/api-keys
      parameters:
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
        description: Bearer {access_token}
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetProfileApiKeysResponse'
      x-evidence:
        kind: documentation
    post:
      operationId: post_profile_api_keys
      tags:
      - Profile
      summary: The API key management routes
      x-source: https://docs.endurain.com/developer-guide/writing-docs
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /profile/idp/{idpId}/link/token:
    post:
      operationId: post_profile_idp_idpId_link_token
      tags:
      - Profile
      summary: Generate IdP link token
      x-source: https://docs.endurain.com/integrate/account-security
      parameters:
      - name: idpId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostProfileIdpIdpidLinkTokenRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /profile/idp/{idpId}/unlink:
    post:
      operationId: post_profile_idp_idpId_unlink
      tags:
      - Profile
      summary: Remove IdP link
      x-source: https://docs.endurain.com/integrate/account-security
      parameters:
      - name: idpId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostProfileIdpIdpidUnlinkRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /profile/mfa/backup-codes:
    post:
      operationId: post_profile_mfa_backup_codes
      tags:
      - Profile
      summary: Regenerate MFA backup codes
      x-source: https://docs.endurain.com/integrate/account-security
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostProfileMfaBackupCodesRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostProfileMfaBackupCodesResponse'
      x-evidence:
        kind: documentation
  /profile/mfa/disable:
    put:
      operationId: put_profile_mfa_disable
      tags:
      - Profile
      summary: Disable MFA
      x-source: https://docs.endurain.com/integrate/account-security
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutProfileMfaDisableRequest'
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /profile/mfa/enable:
    put:
      operationId: put_profile_mfa_enable
      tags:
      - Profile
      summary: Enable MFA
      x-source: https://docs.endurain.com/integrate/account-security
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutProfileMfaEnableRequest'
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /profile/password:
    put:
      operationId: put_profile_password
      tags:
      - Profile
      summary: Change own password
      x-source: https://docs.endurain.com/integrate/account-security
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutProfilePasswordRequest'
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /repos/endurain-project/endurain/releases:
    get:
      operationId: get_repos_endurain_project_endurain_releases
      tags:
      - Repos
      summary: GET /repos/endurain-project/endurain/releases
      x-source: https://docs.endurain.com/getting-started/bare-metal
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: 'curl -s https://api.github.com/repos/endurain-project/endurain/releases | grep -oP ''"tag_name": "\K([^"]+)'' | head -n 1 ) '
  /uv:
    get:
      operationId: get_uv
      tags:
      - Uv
      summary: GET /uv
      x-source: https://docs.endurain.com/getting-started/bare-metal
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl  python3-dev\n 2. Install Required Runtime Tools \n Install the required tools from their official sources: \n uv (Python)\
          \ → https://docs.astral.sh/uv/ \n Node.js 24 → https://nodejs.org/en/download \n PostgreSQL 18 → https://www.postgresql.org/download/\
          \ \n 3. Download Endurain Release \n Run the following command to download and unpack the latest release. \n mkdir -p /path/to/endurain\n\
          \ cd /path/to/e"
components:
  schemas:
    PostActivitiesCreateUploadRequest:
      type: object
      properties:
        file:
          type: string
          description: Activity file (multipart/form-data)
      required:
      - file
    PostApiV1ActivitiesCreateUploadRequest:
      type: object
      properties:
        file:
          type: string
          description: Activity file (multipart/form-data)
      required:
      - file
    PostApiV1AuthLoginRequest:
      type: object
      properties:
        username:
          type: string
          description: User's email or username.
        password:
          type: string
          description: User's password.
      required:
      - username
      - password
    PostApiV1AuthLoginResponse:
      type: object
      properties:
        mfa_required:
          type: boolean
          description: Indicates MFA verification is required.
        username:
          type: string
          description: Echoed username.
        message:
          type: string
          description: Human‑readable status message.
    PostApiV1AuthMfaVerifyRequest:
      type: object
      properties:
        username:
          type: string
          description: User's email or username.
        mfa_code:
          type: string
          description: TOTP code or backup code.
      required:
      - username
      - mfa_code
    PostApiV1AuthMfaVerifyResponse:
      type: object
      properties:
        session_id:
          type: string
          description: Unique session identifier.
        access_token:
          type: string
          description: Bearer access token.
        refresh_token:
          type: string
          description: Refresh token (web clients receive via HttpOnly cookie).
        csrf_token:
          type: string
          description: CSRF token (web clients).
        token_type:
          type: string
          description: Token type, e.g., bearer.
        expires_in:
          type: integer
          description: Access token lifetime in seconds.
        refresh_token_expires_in:
          type: integer
          description: Refresh token lifetime in seconds.
    PostApiV1AuthRefreshResponse:
      type: object
      properties:
        session_id:
          type: string
        access_token:
          type: string
        csrf_token:
          type: string
        token_type:
          type: string
        expires_in:
          type: integer
        refresh_token_expires_in:
          type: integer
    PostApiV1ProfileApiKeysRequest:
      type: object
      properties:
        name:
          type: string
          description: Human-readable label (max 100 characters)
        scopes:
          type: array
          description: Array of API-key scopes to grant. Currently only activities:upload is accepted
        expires_at:
          type: string
          description: ISO 8601 expiry datetime. Omit or null for no expiry
        current_password:
          type: string
          description: Required for accounts with a local password. Omit for SSO-only accounts
        mfa_code:
          type: string
          description: Required when MFA is enabled on the account
      required:
      - name
      - scopes
    PostApiV1ProfileApiKeysResponse:
      type: object
      properties:
        id:
          type: string
        user_id:
          type: integer
        name:
          type: string
        key_prefix:
          type: string
        scopes:
          type: string
        expires_at:
          type: string
        last_used_at:
          type: string
          description: nullable
        created_at:
          type: string
        is_active:
          type: boolean
        key:
          type: string
          description: Raw API key, returned only on creation
    PostApiV1ProfileMfaBackupCodesRequest:
      type: object
      properties:
        current_password:
          type: string
          description: Required for accounts with a local password. Omit for SSO-only accounts.
        mfa_code:
          type: string
          description: Required when MFA is enabled on the account.
    PostApiV1ProfileMfaBackupCodesResponse:
      type: object
      properties:
        codes:
          type: array
          description: New backup codes.
        created_at:
          type: string
          description: Timestamp of generation.
    PostApiV1PublicIdpSessionSessionidTokensRequest:
      type: object
      properties:
        code_verifier:
          type: string
          description: PKCE code verifier generated by the client.
      required:
      - code_verifier
    PostApiV1PublicIdpSessionSessionidTokensResponse:
      type: object
      properties:
        session_id:
          type: string
          description: Echoed session identifier.
        access_token:
          type: string
          description: JWT access token.
        refresh_token:
          type: string
          description: JWT refresh token.
        expires_in:
          type: string
          description: Access token lifetime in seconds.
        refresh_token_expires_in:
          type: string
          description: Refresh token lifetime in seconds.
        token_type:
          type: string
          description: Bearer token type.
    PostAuthRefreshResponse:
      type: object
      properties:
        session_id:
          type: string
        access_token:
          type: string
        csrf_token:
          type: string
        token_type:
          type: string
        expires_in:
          type: integer
        refresh_token_expires_in:
          type: integer
    GetProfileApiKeysResponse:
      type: object
      properties:
        id:
          type: string
        user_id:
          type: integer
        name:
          type: string
        key_prefix:
          type: string
        scopes:
          type: string
        expires_at:
          type: string
        last_used_at:
          type: string
        created_at:
          type: string
        is_active:
          type: boolean
    PostProfileIdpIdpidLinkTokenRequest:
      type: object
      properties:
        current_password:
          type: string
          description: Required for accounts with a local password. Omit for SSO-only accounts.
        mfa_code:
          type: string
          description: Required when MFA is enabled on the account. Accepts TOTP codes or backup codes.
    PostProfileIdpIdpidUnlinkRequest:
      type: object
      properties:
        current_password:
          type: string
          description: Required for accounts with a local password. Omit for SSO-only accounts.
        mfa_code:
          type: string
          description: Required when MFA is enabled on the account. Accepts TOTP codes or backup codes.
    PostProfileMfaBackupCodesRequest:
      type: object
      properties:
        current_password:
          type: string
          description: Required for accounts with a local password. Omit for SSO-only accounts.
        mfa_code:
          type: string
          description: Required when MFA is enabled on the account. Accepts TOTP codes or backup codes.
    PostProfileMfaBackupCodesResponse:
      type: object
      properties:
        codes:
          type: array
          description: New backup codes.
        created_at:
          type: string
          description: Timestamp of generation.
    PutProfileMfaDisableRequest:
      type: object
      properties:
        current_password:
          type: string
          description: Required for accounts with a local password. Omit for SSO-only accounts.
        mfa_code:
          type: string
          description: Required when MFA is enabled on the account. Accepts TOTP codes or backup codes.
    PutProfileMfaEnableRequest:
      type: object
      properties:
        current_password:
          type: string
          description: Required for accounts with a local password. Omit for SSO-only accounts.
        mfa_code:
          type: string
          description: Required when MFA is enabled on the account. Accepts TOTP codes or backup codes.
    PutProfilePasswordRequest:
      type: object
      properties:
        current_password:
          type: string
          description: Required for accounts with a local password. Omit for SSO-only accounts.
        mfa_code:
          type: string
          description: Required when MFA is enabled on the account. Accepts TOTP codes or backup codes.
  securitySchemes:
    X-API-Key:
      type: apiKey
      in: header
      name: X-API-Key
      x-source: https://docs.endurain.com/reference/authentication/
tags:
- name: Activities
- name: Api
- name: Auth
- name: Endurain Project
- name: Profile
- name: Repos
- name: Uv
security:
- X-API-Key: []