openapi: 3.2.0
info:
  title: wger Trophy API
  version: 2.7.0a2
  description: "Self hosted FLOSS workout and fitness tracker.\n\n## Authentication\n\nSystem-wide data such as the exercise database, ingredients and units can be\nread without authenticating. Everything tied to a user account needs one of the\nfollowing, which are tried in this order:\n\n* `Authorization: Token <key>` with a personal API key. Users create one on the\n  API key page of their profile, e.g. `/en/user/api-key`.\n* `Authorization: Bearer <token>` with a JWT access token.\n* The session cookie, which is what a logged-in browser uses.\n\n## Pagination\n\nList endpoints take `limit` and `offset`, and answer with `count`, `next`,\n`previous` and `results`. The default page size is 20 and `limit` is capped\nat 999.\n\n`/api/v2/ingredient-sync/` is the exception. It uses cursor pagination so that\nsyncing the catalogue stays fast no matter how far a client has paginated. That\nresponse carries no `count`, and clients follow `next` instead of picking an\noffset.\n\n## Filtering and ordering\n\nMost list endpoints accept filters on a subset of their fields, plus `ordering`\nwith a field name that can be prefixed with `-` to reverse it. Both are listed\nper endpoint.\n\n## Unknown fields are dropped on write\n\nA field that the endpoint does not declare is ignored instead of rejected. Such\na request still answers 200 or 201, and the unknown field simply has no effect,\nso check a write against the response body rather than the status code.\n\n## Rate limits\n\nThe ingredient endpoints are rate limited because the catalogue holds millions\nof rows, and creating exercises is capped as well. Limits count per user for\nauthenticated callers and per IP otherwise. Exceeding one answers 429.\n"
  license:
    name: AGPL-3.0-or-later
    url: https://www.gnu.org/licenses/agpl-3.0.html
servers:
- url: /
  description: This server
- url: https://wger.de
  description: The "official" upstream wger instance
tags:
- name: trophy
paths:
  /api/v2/trophy/:
    get:
      operationId: trophy_list
      description: 'API endpoint for Trophy objects.


        Returns active trophies. Hidden trophies are excluded unless:

        - The user has earned them, or

        - The user is staff


        list:

        Return a list of active trophies


        retrieve:

        Return a specific trophy by ID'
      parameters:
      - in: query
        name: id
        schema:
          type: integer
      - in: query
        name: id__in
        schema:
          type: array
          items:
            type: integer
        description: Multiple values may be separated by commas.
        explode: false
        style: form
      - in: query
        name: is_active
        schema:
          type: boolean
      - in: query
        name: is_hidden
        schema:
          type: boolean
      - in: query
        name: is_progressive
        schema:
          type: boolean
      - in: query
        name: is_repeatable
        schema:
          type: boolean
      - name: limit
        required: false
        in: query
        description: Number of results to return per page.
        schema:
          type: integer
      - name: offset
        required: false
        in: query
        description: The initial index from which to return the results.
        schema:
          type: integer
      - name: ordering
        required: false
        in: query
        description: Which field to use when ordering the results.
        schema:
          type: string
      - in: query
        name: trophy_type
        schema:
          type: string
          enum:
          - count
          - date
          - other
          - pr
          - sequence
          - time
          - volume
        description: 'The type of criteria used to evaluate this trophy


          * `time` - Time-based

          * `volume` - Volume-based

          * `count` - Count-based

          * `sequence` - Sequence-based

          * `date` - Date-based

          * `pr` - Personal Record

          * `other` - Other'
      - in: query
        name: trophy_type__in
        schema:
          type: array
          items:
            type: string
        description: Multiple values may be separated by commas.
        explode: false
        style: form
      tags:
      - trophy
      security:
      - cookieAuth: []
      - tokenAuth: []
      - headlessJwtAuth: []
      - oidcAuth: []
      - jwtAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedTrophyList'
          description: ''
  /api/v2/trophy/{id}/:
    get:
      operationId: trophy_retrieve
      description: 'API endpoint for Trophy objects.


        Returns active trophies. Hidden trophies are excluded unless:

        - The user has earned them, or

        - The user is staff


        list:

        Return a list of active trophies


        retrieve:

        Return a specific trophy by ID'
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        description: A unique integer value identifying this Trophy.
        required: true
      tags:
      - trophy
      security:
      - cookieAuth: []
      - tokenAuth: []
      - headlessJwtAuth: []
      - oidcAuth: []
      - jwtAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Trophy'
          description: ''
  /api/v2/trophy/progress/:
    get:
      operationId: trophy_progress_list
      description: "\n        Return all trophies with progress information for the current user.\n\n        For each trophy, returns:\n        - Trophy information (id, name, description, type, etc.)\n        - Whether the trophy has been earned\n        - Earned timestamp (if earned)\n        - Progress percentage (0-100)\n        - Current and target values (for progressive trophies)\n\n        Hidden trophies are excluded unless earned (or user is staff).\n        "
      summary: Get trophy progress
      parameters:
      - in: query
        name: id
        schema:
          type: integer
      - in: query
        name: id__in
        schema:
          type: array
          items:
            type: integer
        description: Multiple values may be separated by commas.
        explode: false
        style: form
      - in: query
        name: is_active
        schema:
          type: boolean
      - in: query
        name: is_hidden
        schema:
          type: boolean
      - in: query
        name: is_progressive
        schema:
          type: boolean
      - in: query
        name: is_repeatable
        schema:
          type: boolean
      - name: ordering
        required: false
        in: query
        description: Which field to use when ordering the results.
        schema:
          type: string
      - in: query
        name: trophy_type
        schema:
          type: string
          enum:
          - count
          - date
          - other
          - pr
          - sequence
          - time
          - volume
        description: 'The type of criteria used to evaluate this trophy


          * `time` - Time-based

          * `volume` - Volume-based

          * `count` - Count-based

          * `sequence` - Sequence-based

          * `date` - Date-based

          * `pr` - Personal Record

          * `other` - Other'
      - in: query
        name: trophy_type__in
        schema:
          type: array
          items:
            type: string
        description: Multiple values may be separated by commas.
        explode: false
        style: form
      tags:
      - trophy
      security:
      - cookieAuth: []
      - tokenAuth: []
      - headlessJwtAuth: []
      - oidcAuth: []
      - jwtAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TrophyProgress'
          description: ''
components:
  schemas:
    TrophyTypeEnum:
      enum:
      - time
      - volume
      - count
      - sequence
      - date
      - pr
      - other
      type: string
      description: '* `time` - Time-based

        * `volume` - Volume-based

        * `count` - Count-based

        * `sequence` - Sequence-based

        * `date` - Date-based

        * `pr` - Personal Record

        * `other` - Other'
    TrophyProgress:
      type: object
      description: 'Serializer for trophy progress information.


        Used for showing progress on all trophies (earned and unearned).

        This is not a ModelSerializer as it aggregates data from multiple sources.'
      properties:
        trophy:
          allOf:
          - $ref: '#/components/schemas/Trophy'
          readOnly: true
        is_earned:
          type: boolean
        earned_at:
          type:
          - string
          - 'null'
          format: date-time
        progress:
          type: number
          format: double
        current_value:
          type:
          - string
          - 'null'
        target_value:
          type:
          - string
          - 'null'
        progress_display:
          type:
          - string
          - 'null'
      required:
      - current_value
      - earned_at
      - is_earned
      - progress
      - progress_display
      - target_value
      - trophy
    Trophy:
      type: object
      description: 'Serializer for Trophy model.


        Shows trophy information for listing active trophies.'
      properties:
        id:
          type: integer
          readOnly: true
        uuid:
          type: string
          format: uuid
          readOnly: true
        name:
          type: string
          description: Translate the trophy name
          readOnly: true
        description:
          type: string
          description: Translate the trophy description
          readOnly: true
        image:
          type:
          - string
          - 'null'
          description: Build absolute URL to trophy image, if possible.
          readOnly: true
        trophy_type:
          allOf:
          - $ref: '#/components/schemas/TrophyTypeEnum'
          readOnly: true
          description: 'The type of criteria used to evaluate this trophy


            * `time` - Time-based

            * `volume` - Volume-based

            * `count` - Count-based

            * `sequence` - Sequence-based

            * `date` - Date-based

            * `pr` - Personal Record

            * `other` - Other'
        is_hidden:
          type: boolean
          readOnly: true
          title: Hidden
          description: If true, this trophy is hidden until earned
        is_progressive:
          type: boolean
          readOnly: true
          title: Progressive
          description: If true, this trophy shows progress towards completion
        is_repeatable:
          type: boolean
          readOnly: true
          title: Repeatable
          description: If true, this trophy can be earned multiple times
        order:
          type: integer
          readOnly: true
          description: Display order of the trophy
      required:
      - description
      - id
      - image
      - is_hidden
      - is_progressive
      - is_repeatable
      - name
      - order
      - trophy_type
      - uuid
    PaginatedTrophyList:
      type: object
      required:
      - count
      - results
      properties:
        count:
          type: integer
          example: 123
        next:
          type:
          - string
          - 'null'
          format: uri
          example: http://api.example.org/accounts/?offset=400&limit=100
        previous:
          type:
          - string
          - 'null'
          format: uri
          example: http://api.example.org/accounts/?offset=200&limit=100
        results:
          type: array
          items:
            $ref: '#/components/schemas/Trophy'
  securitySchemes:
    cookieAuth:
      type: apiKey
      in: cookie
      name: sessionid
    headlessJwtAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Access token issued by the allauth headless endpoints
    jwtAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    oidcAuth:
      type: oauth2
      description: Access token issued by the OAuth2/OIDC provider
      flows:
        authorizationCode:
          authorizationUrl: https://wger.de/identity/o/authorize
          tokenUrl: https://wger.de/identity/o/api/token
          scopes:
            api:read: View your training, nutrition and body data
            api:write: Add and change your training, nutrition and body data
    tokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: Token-based authentication with required prefix "Token"
externalDocs:
  url: https://wger.readthedocs.io
  description: wger documentation