Wger Ingredient Sync API

openapi: 3.2.0
info:
  title: wger Ingredient Sync 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: ingredient-sync
  description: The same data as ingredientinfo, but cursor paginated for mirroring the whole catalogue. No `count`, and only `next`/`previous` rather than arbitrary offsets. Combine with the `last_update__gt` filter for incremental syncs.
paths:
  /api/v2/ingredient-sync/:
    get:
      operationId: ingredient_sync_list
      description: 'Cursor-paginated read-only endpoint designed for syncing the ingredient

        catalogue.


        Unlike /api/v2/ingredient/, this endpoint uses cursor pagination so deep

        pagination stays fast and is intended for clients such as local wger instances.


        For incremental syncs, combine with the `last_update__gt` filter to only

        fetch ingredients that changed since that time.


        Note: the response does not contain a `count` key.'
      parameters:
      - in: query
        name: carbohydrates
        schema:
          type: number
      - in: query
        name: carbohydrates_sugar
        schema:
          type: number
      - in: query
        name: code
        schema:
          type: string
      - in: query
        name: created
        schema:
          type: string
          format: date-time
      - in: query
        name: created__gt
        schema:
          type: string
          format: date-time
      - in: query
        name: created__lt
        schema:
          type: string
          format: date-time
      - name: cursor
        required: false
        in: query
        description: The pagination cursor value.
        schema:
          type: string
      - in: query
        name: energy
        schema:
          type: integer
      - in: query
        name: fat
        schema:
          type: number
      - in: query
        name: fat_saturated
        schema:
          type: number
      - in: query
        name: fiber
        schema:
          type: number
      - in: query
        name: id
        schema:
          type: integer
      - in: query
        name: id__gt
        schema:
          type: integer
      - in: query
        name: id__gte
        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: id__lt
        schema:
          type: integer
      - in: query
        name: id__lte
        schema:
          type: integer
      - in: query
        name: is_vegan
        schema:
          type: boolean
      - in: query
        name: is_vegetarian
        schema:
          type: boolean
      - in: query
        name: language
        schema:
          type: integer
      - in: query
        name: language__code
        schema:
          type: string
        description: Filter by language code. Multiple values may be separated by commas. Unknown codes are ignored.
      - in: query
        name: language__in
        schema:
          type: array
          items:
            type: integer
        description: Multiple values may be separated by commas.
        explode: false
        style: form
      - in: query
        name: last_imported
        schema:
          type: string
          format: date-time
      - in: query
        name: last_imported__gt
        schema:
          type: string
          format: date-time
      - in: query
        name: last_imported__lt
        schema:
          type: string
          format: date-time
      - in: query
        name: last_update
        schema:
          type: string
          format: date-time
      - in: query
        name: last_update__gt
        schema:
          type: string
          format: date-time
      - in: query
        name: last_update__lt
        schema:
          type: string
          format: date-time
      - in: query
        name: license
        schema:
          type: integer
      - in: query
        name: license_author
        schema:
          type: string
      - in: query
        name: name
        schema:
          type: string
      - in: query
        name: name__search
        schema:
          type: string
      - in: query
        name: nutriscore
        schema:
          type:
          - string
          - 'null'
          title: Nutri-Score
          enum:
          - a
          - b
          - c
          - d
          - e
        description: 'Nutri-Score grade from Open Food Facts


          * `a` - A

          * `b` - B

          * `c` - C

          * `d` - D

          * `e` - E'
      - in: query
        name: nutriscore__gt
        schema:
          type: string
      - in: query
        name: nutriscore__gte
        schema:
          type: string
      - in: query
        name: nutriscore__in
        schema:
          type: array
          items:
            type: string
        description: Multiple values may be separated by commas.
        explode: false
        style: form
      - in: query
        name: nutriscore__lt
        schema:
          type: string
      - in: query
        name: nutriscore__lte
        schema:
          type: string
      - name: ordering
        required: false
        in: query
        description: Which field to use when ordering the results.
        schema:
          type: string
      - name: page_size
        required: false
        in: query
        description: Number of results to return per page.
        schema:
          type: integer
      - in: query
        name: protein
        schema:
          type: number
      - in: query
        name: sodium
        schema:
          type: number
      - in: query
        name: source_name
        schema:
          type: string
      - in: query
        name: uuid
        schema:
          type: string
          format: uuid
      tags:
      - ingredient-sync
      security:
      - cookieAuth: []
      - tokenAuth: []
      - headlessJwtAuth: []
      - oidcAuth: []
      - jwtAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CursorPaginatedIngredientInfoList'
          description: ''
  /api/v2/ingredient-sync/{id}/:
    get:
      operationId: ingredient_sync_retrieve
      description: 'Cursor-paginated read-only endpoint designed for syncing the ingredient

        catalogue.


        Unlike /api/v2/ingredient/, this endpoint uses cursor pagination so deep

        pagination stays fast and is intended for clients such as local wger instances.


        For incremental syncs, combine with the `last_update__gt` filter to only

        fetch ingredients that changed since that time.


        Note: the response does not contain a `count` key.'
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        description: A unique integer value identifying this ingredient.
        required: true
      tags:
      - ingredient-sync
      security:
      - cookieAuth: []
      - tokenAuth: []
      - headlessJwtAuth: []
      - oidcAuth: []
      - jwtAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngredientInfo'
          description: ''
components:
  schemas:
    CursorPaginatedIngredientInfoList:
      type: object
      required:
      - results
      properties:
        next:
          type:
          - string
          - 'null'
          format: uri
          example: http://api.example.org/accounts/?cursor=cD00ODY%3D"
        previous:
          type:
          - string
          - 'null'
          format: uri
          example: http://api.example.org/accounts/?cursor=cj0xJnA9NDg3
        results:
          type: array
          items:
            $ref: '#/components/schemas/IngredientInfo'
    IngredientInfo:
      type: object
      description: Ingredient info serializer
      properties:
        id:
          type: integer
          readOnly: true
        uuid:
          type: string
          format: uuid
          readOnly: true
        remote_id:
          type:
          - string
          - 'null'
          maxLength: 200
        source_name:
          type:
          - string
          - 'null'
          maxLength: 200
        source_url:
          title: Link
          description: Link to product
          oneOf:
          - type: string
            format: uri
            maxLength: 200
          - type: string
            maxLength: 0
        code:
          type:
          - string
          - 'null'
          maxLength: 200
        name:
          type: string
          maxLength: 200
          minLength: 3
        common_name:
          type:
          - string
          - 'null'
          maxLength: 200
        brand:
          type:
          - string
          - 'null'
          title: Brand name of product
          maxLength: 200
        created:
          type: string
          format: date-time
          readOnly: true
          title: Date
        last_update:
          type: string
          format: date-time
          readOnly: true
          title: Date
        last_imported:
          type:
          - string
          - 'null'
          format: date-time
          readOnly: true
          title: Date
        energy:
          type: integer
          maximum: 2147483647
          minimum: -2147483648
          description: In kcal per 100g
        protein:
          type: string
          format: decimal
          pattern: ^-?\d{0,3}(?:\.\d{0,3})?$
          description: In g per 100g of product
        carbohydrates:
          type: string
          format: decimal
          pattern: ^-?\d{0,3}(?:\.\d{0,3})?$
          description: In g per 100g of product
        carbohydrates_sugar:
          type:
          - string
          - 'null'
          format: decimal
          pattern: ^-?\d{0,3}(?:\.\d{0,3})?$
          title: Sugar content in carbohydrates
          description: In g per 100g of product
        fat:
          type: string
          format: decimal
          pattern: ^-?\d{0,3}(?:\.\d{0,3})?$
          description: In g per 100g of product
        fat_saturated:
          type:
          - string
          - 'null'
          format: decimal
          pattern: ^-?\d{0,3}(?:\.\d{0,3})?$
          title: Saturated fat content in fats
          description: In g per 100g of product
        fiber:
          type:
          - string
          - 'null'
          format: decimal
          pattern: ^-?\d{0,3}(?:\.\d{0,3})?$
          description: In g per 100g of product
        sodium:
          type:
          - string
          - 'null'
          format: decimal
          pattern: ^-?\d{0,3}(?:\.\d{0,3})?$
          description: In g per 100g of product
        is_vegan:
          type:
          - boolean
          - 'null'
          title: Vegan
          description: Whether the ingredient is suitable for a vegan diet
        is_vegetarian:
          type:
          - boolean
          - 'null'
          title: Vegetarian
          description: Whether the ingredient is suitable for a vegetarian diet
        nutriscore:
          title: Nutri-Score
          description: 'Nutri-Score grade from Open Food Facts


            * `a` - A

            * `b` - B

            * `c` - C

            * `d` - D

            * `e` - E'
          oneOf:
          - $ref: '#/components/schemas/NutriscoreEnum'
          - $ref: '#/components/schemas/BlankEnum'
          - $ref: '#/components/schemas/NullEnum'
        weight_units:
          type: array
          items:
            $ref: '#/components/schemas/IngredientWeightUnit'
        language:
          allOf:
          - $ref: '#/components/schemas/Language'
          readOnly: true
        license:
          allOf:
          - $ref: '#/components/schemas/License'
          readOnly: true
        license_title:
          type: string
          title: The original title of this object, if available
          maxLength: 300
        license_object_url:
          title: Link to original object, if available
          oneOf:
          - type: string
            format: uri
            maxLength: 200
          - type: string
            maxLength: 0
        license_author:
          type: string
          title: Author(s)
          description: If you are not the author, enter the name or source here.
          maxLength: 3500
        license_author_url:
          title: Link to author profile, if available
          oneOf:
          - type: string
            format: uri
            maxLength: 200
          - type: string
            maxLength: 0
        license_derivative_source_url:
          title: Link to the original source, if this is a derivative work
          description: Note that a derivative work is one which is not only based on a previous work, but which also contains sufficient new, creative content to entitle it to its own copyright.
          oneOf:
          - type: string
            format: uri
            maxLength: 200
          - type: string
            maxLength: 0
        image:
          allOf:
          - $ref: '#/components/schemas/IngredientImage'
          readOnly: true
        thumbnails:
          allOf:
          - $ref: '#/components/schemas/Thumbnails'
          readOnly: true
      required:
      - carbohydrates
      - created
      - energy
      - fat
      - id
      - image
      - language
      - last_imported
      - last_update
      - license
      - name
      - protein
      - thumbnails
      - uuid
      - weight_units
    License:
      type: object
      description: License serializer
      properties:
        id:
          type: integer
          readOnly: true
        full_name:
          type: string
          description: If a license has been localized, e.g. the Creative Commons licenses for the different countries, add them as separate entries here.
          maxLength: 60
        short_name:
          type: string
          title: Short name, e.g. CC-BY-SA 3
          maxLength: 15
        url:
          title: Link
          description: Link to license text or other information
          oneOf:
          - type: string
            format: uri
            maxLength: 200
          - type: string
            maxLength: 0
      required:
      - full_name
      - id
      - short_name
    BlankEnum:
      enum:
      - ''
    NullEnum:
      enum:
      - null
    IngredientImage:
      type: object
      description: Image serializer
      properties:
        id:
          type: integer
          readOnly: true
        uuid:
          type: string
          format: uuid
          readOnly: true
        ingredient_id:
          type:
          - integer
          - 'null'
          readOnly: true
        ingredient_uuid:
          type: string
          readOnly: true
        image:
          type: string
          format: uri
          description: Only PNG and JPEG formats are supported
        created:
          type: string
          format: date-time
          readOnly: true
        last_update:
          type: string
          format: date-time
          readOnly: true
        size:
          type: integer
          maximum: 2147483647
          minimum: -2147483648
        width:
          type: integer
          readOnly: true
        height:
          type: integer
          readOnly: true
        license:
          type: integer
        license_title:
          type: string
          title: The original title of this object, if available
          maxLength: 300
        license_object_url:
          title: Link to original object, if available
          oneOf:
          - type: string
            format: uri
            maxLength: 200
          - type: string
            maxLength: 0
        license_author:
          type: string
          title: Author(s)
          description: If you are not the author, enter the name or source here.
          maxLength: 3500
        license_author_url:
          title: Link to author profile, if available
          oneOf:
          - type: string
            format: uri
            maxLength: 200
          - type: string
            maxLength: 0
        license_derivative_source_url:
          title: Link to the original source, if this is a derivative work
          description: Note that a derivative work is one which is not only based on a previous work, but which also contains sufficient new, creative content to entitle it to its own copyright.
          oneOf:
          - type: string
            format: uri
            maxLength: 200
          - type: string
            maxLength: 0
      required:
      - created
      - height
      - id
      - image
      - ingredient_id
      - ingredient_uuid
      - last_update
      - size
      - uuid
      - width
    NutriscoreEnum:
      enum:
      - a
      - b
      - c
      - d
      - e
      type: string
      description: '* `a` - A

        * `b` - B

        * `c` - C

        * `d` - D

        * `e` - E'
    IngredientWeightUnit:
      type: object
      description: IngredientWeightUnit serializer
      properties:
        id:
          type: integer
          readOnly: true
        uuid:
          type: string
          format: uuid
          readOnly: true
        ingredient:
          type: integer
          readOnly: true
        gram:
          type: integer
          maximum: 2147483647
          minimum: -2147483648
          title: Amount in grams
        name:
          type: string
          maxLength: 200
      required:
      - gram
      - id
      - ingredient
      - name
      - uuid
    Language:
      type: object
      description: Language serializer
      properties:
        id:
          type: integer
          readOnly: true
        short_name:
          type: string
          title: Language short name
          description: ISO 639-1
          maxLength: 2
        full_name:
          type: string
          title: Language full name
          maxLength: 30
        full_name_en:
          type: string
          title: Language full name in English
          maxLength: 30
      required:
      - full_name
      - full_name_en
      - id
      - short_name
    Thumbnails:
      type: object
      description: 'Shape of the ``thumbnails`` field, used for schema generation only.


        The aliases are read from settings.THUMBNAIL_ALIASES and are the same for

        every thumbnailed image in the API. Without this, the generated schema falls

        back to a plain string for the dict the method fields return.'
      properties:
        small:
          type: string
          format: uri
        medium:
          type: string
          format: uri
      required:
      - medium
      - small
  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