MuscleLib API Documentation

Start building your project using the MuscleLib API

Base URL

All of the endpoints are prefixed with the base URL. The base URL for the MuscleLib API is:

https://libapi.vercel.app

Get Started

All Exercises

Retrieve a list of all exercises available in the database. This endpoint supports various query parameters for filtering and pagination.

https://libapi.vercel.app/api/exercises

Response Samples

RESPONSE SCHEMA: application/json

type: array
- items: object
  - _id: string
  - name: string
  - force: string
  - level: string
  - mechanic: string
  - equipment: string
  - primaryMuscles: array (items: string)
  - secondaryMuscles: array (items: object) - details not specified)
  - instructions: array (items: string)
  - category: string
  - images: array (items: string)
  - id: string

RESPONSE SCHEMA: application/json

type: object
- properties:
  - message: string
  - error: string


  {
    "_id": "677471831533c77a3a55b2e0",
    "name": "3/4 Sit-Up",
    "force": "pull",
    "level": "beginner",
    "mechanic": "compound",
    "equipment": "body only",
    "primaryMuscles": [
      "abdominals"
    ],
    "secondaryMuscles": [],
    "instructions": [
      "Lie down on the floor and secure your feet"
    ],
    "category": "strength",
    "images": [
      "3_4_Sit-Up/0.jpg",
      "3_4_Sit-Up/1.jpg"
    ],
    "id": "3_4_Sit-Up"
  }


  {
    "message": "Error fetching exercises.",
    "error": "Operation `exercises.distinct()` buffering timed out after 10000ms"
  }

Lang

Language for response Default is en Suported values: en, pt.

Example Request:

https://libapi.vercel.app/api/exercises?lang=en

Response Samples

RESPONSE SCHEMA: application/json

type: array
- items: object
  - _id: string
  - name: string
  - force: string
  - level: string
  - mechanic: string
  - equipment: string
  - primaryMuscles: array (items: string)
  - secondaryMuscles: array (items: object) - details not specified)
  - instructions: array (items: string)
  - category: string
  - images: array (items: string)
  - id: string

RESPONSE SCHEMA: application/json

type: object
- properties:
  - message: string


  [
    {
      "_id": "677471841533c77a3a55b2e6",
      "name": "Advanced Kettlebell Windmill",
      "force": "push",
      "level": "intermediate",
      "mechanic": "isolation",
      "equipment": "kettlebells",
      "primaryMuscles": [
        "abdominals"
      ],
      "secondaryMuscles": [
        "glutes",
        "hamstrings",
        "shoulders"
      ],
      "instructions": [
        "Clean and press a kettlebell overhead with one arm."
      ],
      "category": "strength",
      "images": [
        "Advanced_Kettlebell_Windmill/0.jpg",
        "Advanced_Kettlebell_Windmill/1.jpg"
      ],
      "id": "Advanced_Kettlebell_Windmill"
    }


  {
    "message": "Invalid language. Use 'en' or 'pt'."
  }

Fields

Comma-separated list of fields to return e.g.: (name,instructions).

Example Request:

https://libapi.vercel.app/api/exercises?fields=instructions

Response Samples

RESPONSE SCHEMA: application/json

type: object
- items: object
  - _id: string
  - name: string
  - instructions: array (items: string)

RESPONSE SCHEMA: application/json

type: object
- properties:
  - message: string


  {
    "_id": "677471841533c77a3a55b2e9",
    "name": "Alternate Hammer Curl",
    "instructions": [
      "Stand up with your torso upright and a dumbbell in each hand being held at arms length. The elbows should be close to the torso.",
      "The palms of the hands should be facing your torso. This will be your starting position."
    ]
  }


  {
    "message": "The field(s) parameter(s) cannot be empty. Valid fields are: force, level, mechanic, equipment, primaryMuscles, secondaryMuscles, instructions, category, images, name."
  }

Page

Page number for pagination muste be an integer ≥ 1. Default is 1.

Example Request:

https://libapi.vercel.app/api/exercises?page=10

Response Samples

RESPONSE SCHEMA: application/json

type: array
- items: object
  - _id: string
  - name: string
  - force: string
  - level: string
  - mechanic: string
  - equipment: string
  - primaryMuscles: array (items: sstring)
  - secondaryMuscles: array (items: object - details not specified)
  - instructions: array (items: string)
  - category: string
  - images: array (items: string)
  - id: string

RESPONSE SCHEMA: application/json

type: obeject
- properties:
  - message: string


  {
    "_id": "677471841533c77a3a55b4d4",
    "name": "One-Arm Open Palm Kettlebell Clean",
    "force": "pull",
    "level": "intermediate",
    "mechanic": "compound",
    "equipment": "kettlebells",
    "primaryMuscles": [
      "hamstrings"
    ],
    "secondaryMuscles": [
      "forearms",
      "glutes",
      "lower back",
      "quadriceps",
      "shoulders"
    ],
    "instructions": [
      "Place one kettlebell between your feet."
    ],
    "category": "strength",
    "images": [
      "One-Arm_Open_Palm_Kettlebell_Clean/0.jpg",
      "One-Arm_Open_Palm_Kettlebell_Clean/1.jpg"
    ],
    "id": "One-Arm_Open_Palm_Kettlebell_Clean",
    "__v": 0
  }


  {
    "message": "parameter 'page' is invalid. use a value greater than or equal to 0."
  }

Limit

Number of items to return per page. Must be an integer between ≥ 1. Default is 1.

Example Request:

https://libapi.vercel.app/api/exercises?limit=2

Response Samples

RESPONSE SCHEMA: application/json

type: array
- items: object
  - _id: string
  - name: string
  - force: string
  - level: string
  - mechanic: string
  - equipment: string
  - primaryMuscles: array (items: string)
  - secondaryMuscles: array (items: object - details not specified)
  - instructions: array (items: string)
  - category: string
  - images: array (items: string)
  - id: string

RESPONSE SCHEMA: application/json

type: object
- properties:
  - message: string


  [
    {
      "_id": "677471831533c77a3a55b2e0",
      "name": "3/4 Sit-Up",
      "force": "pull",
      "level": "beginner",
      "mechanic": "compound",
      "equipment": "body only",
      "primaryMuscles": [
        "abdominals"
      ],
      "secondaryMuscles": [],
      "instructions": [
        "Lie down on the floor and secure your feet. Your legs should be bent at the knees."
      ],
      "category": "strength",
      "images": [
        "3_4_Sit-Up/0.jpg",
        "3_4_Sit-Up/1.jpg"
      ],
      "id": "3_4_Sit-Up",
      "__v": 0
    },
    {
      "_id": "677471831533c77a3a55b2e1",
      "name": "90/90 Hamstring",
      "force": "push",
      "level": "beginner",
      "mechanic": null,
      "equipment": "body only",
      "primaryMuscles": [
        "hamstrings"
      ],
      "secondaryMuscles": [
        "calves"
      ],
      "instructions": [
        "Lie on your back, with one leg extended straight out."
      ],
      "category": "stretching",
      "images": [
        "90_90_Hamstring/0.jpg",
        "90_90_Hamstring/1.jpg"
      ],
      "id": "90_90_Hamstring",
      "__v": 0
    }
  ]


  {
    "message": "parameter 'limit' is invalid. use a value greater than 0."
  }

Dynamic Filters

Apply filters based on exercise atrubutes e.g.: (primaryMuscles=Chest).

Example Request:

https://libapi.vercel.app/api/exercises?level=expert&force=push&primaryMuscles=chest

Response Samples

RESPONSE SCHEMA: application/json

type: array
- items: object
  - _id: string
  - name: string
  - force: string
  - level: string
  - mechanic: string
  - equipment: string
  - primaryMuscles: array (items: string)
  - secondaryMuscles: array (items: object - details not specified)
  - instructions: array (items: string)
  - category: string
  - images: array (items: string)
  - id: string

RESPONSE SCHEMA: application/json

type: object
- properties:
  - message: string


  [
    {
      "_id": "677471841533c77a3a55b4ff",
      "name": "Plyo Kettlebell Pushups",
      "force": "push",
      "level": "expert",
      "mechanic": "compound",
      "equipment": "kettlebells",
      "primaryMuscles": [
        "chest"
      ],
      "secondaryMuscles": [
        "shoulders",
        "triceps"
      ],
      "instructions": [
        "Place a kettlebell on the floor. Place yourself in a pushup position, on your toes with one hand on the ground and one hand holding the kettlebell, with your elbows extended. This will be your starting position."
      "category": "strength",
      "images": [
        "Plyo_Kettlebell_Pushups/0.jpg",
        "Plyo_Kettlebell_Pushups/1.jpg"
      ],
      "id": "Plyo_Kettlebell_Pushups",
      "__v": 0
    }
  ]


  {
    "message": "No exercises found."
  }

Search Exercises

The endpoint allows users to search for exercises in the MuscleLib API database. This endpoint supports various query parameters to filter and paginate the results, making the search more efficient and personalized.

https://libapi.vercel.app/api/exercises/search?query=crucifix

Response Samples

RESPONSE SCHEMA: application/json

type: object
- properties:
  - exercises: array
    - items: object
      - _id: string
      - name: string
      - force: string
      - level: string
      - mechanic: string
      - equipment: string
      - primaryMuscles: array
        
        items: string
      - secondaryMuscles: array
        
        items: string
      - instructions: array
        
        items: string
      - category: string
      - images: array
        
        items: string

RESPONSE SCHEMA: application/json

type: object
- properties:
  - message: string


  {
    "exercises": [
      {
        "_id": "677471841533c77a3a55b399",
        "name": "Crucifix",
        "force": "static",
        "level": "beginner",
        "mechanic": "isolation",
        "equipment": "other",
        "primaryMuscles": [
          "shoulders"
        ],
        "secondaryMuscles": [
          "forearms"
        ],
        "instructions": [
          "In the crucifix, you statically hold weights out to the side for time. While the event can be practiced using dumbbells, it is best to practice with one of the various implements used, such as axes and hammers, as it feels different.",
          "Begin standing, and raise your arms out to the side holding the implements. Your arms should be parallel to the ground. In competition, judges or sensors are used to let you know when you break parallel. Hold for as long as you can. Typically, the weights should be heavy enough that you fail in 30-60 seconds."
        ],
        "category": "strongman",
        "images": [
          "/exercises/Crucifix/0.jpg",
          "/exercises/Crucifix/1.jpg"
        ]
      }
    ]
  }


  {
    "message": "No exercises found. No suggestions available."
  }

Get Exercise Images

The endpoint allows users to retrieve images associated with exercises from the MuscleLib API. Each exercise has its images stored in a specific directory.

https://libapi.vercel.app/api/exercises/Stiff-Legged_Barbell_Deadlift/0.jpg

Response Samples

RESPONSE SCHEMA: image/jpeg

RESPONSE SCHEMA: application/json

type: object
- properties:
  - message: string
  - availableOptions: array
    - items: string


  {
    "message": "The $exerciseName provided is incorrect or does not exist in the database. Try:",
    "availableOptions": [
      "Stiff-Legged_Barbell_Deadlift"
    ]
  }

Image Structure

Exercise images are organized in folders, where each folder corresponds to an exercise. Inside each folder, there are two images named 0.jpg and 1.jpg. For example:

Image paths for the exercise "3/4 Sit-Up":

0.jpg

1.jpg

https://libapi.vercel.app/api/exercises/3_4_Sit-Up/0.jpg

https://libapi.vercel.app/api/exercises/3_4_Sit-Up/1.jpg

Image paths for the exercise "Stiff-Legged_Barbell_Deadlift":

0.jpg

1.jpg

https://libapi.vercel.app/api/exercises/Stiff-Legged_Barbell_Deadlift/0.jpg

https://libapi.vercel.app/api/exercises/Stiff-Legged_Barbell_Deadlift/1.jpg

Menu

Base URL

Get Started

All Exercises

GET/api/exercises

Response Samples

Lang

Example Request:

GET/api/exercises?lang=en

Response Samples

Fields

Example Request:

GET/api/exercises?fields

Response Samples

Page

Example Request:

GET/api/exercises?page=

Response Samples

Limit

Example Request:

GET/api/exercises?limit=

Response Samples

Dynamic Filters

Example Request:

GET/api/exercises?level=

Response Samples

Search Exercises

GET/api/exercises/search

Response Samples

Get Exercise Images

GET /exercises/{exerciseName}/{imageIndex}.jpg

Response Samples

Image Structure