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/api

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 (localized by lang)
  - force: string (localized by lang)
  - level: string (localized by lang)
  - mechanic: string (localized by lang)
  - equipment: string (localized by lang)
  - primaryMuscles: array (items: string, localized by lang)
  - secondaryMuscles: array (items: string, localized by lang)
  - instructions: array (items: string, localized by lang)
  - category: string (localized by lang)
  - 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 failed while fetching exercises."
}

Lang

Language for response. Default is en. Supported values: en, pt, es. If omitted, the API can use the Accept-Language header.

Example Request:

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

Response Samples

RESPONSE SCHEMA: application/json

type: array
- items: object
  - _id: string
  - name: string (localized by lang)
  - force: string (localized by lang)
  - level: string (localized by lang)
  - mechanic: string (localized by lang)
  - equipment: string (localized by lang)
  - primaryMuscles: array (items: string, localized by lang)
  - secondaryMuscles: array (items: string, localized by lang)
  - instructions: array (items: string, localized by lang)
  - category: string (localized by lang)
  - 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', 'pt' or 'es'."
}

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 (localized by lang)
  - instructions: array (items: string, localized by lang)

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.",
    "The palms of the hands should be facing your torso."
  ]
}

{
  "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 must 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 (localized by lang)
  - force: string (localized by lang)
  - level: string (localized by lang)
  - mechanic: string (localized by lang)
  - equipment: string (localized by lang)
  - primaryMuscles: array (items: sstring)
  - secondaryMuscles: array (items: object - details not specified)
  - instructions: array (items: string, localized by lang)
  - category: string (localized by lang)
  - 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 ≥ 1. Default is 10.

Example Request:

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

Response Samples

RESPONSE SCHEMA: application/json

type: array
- items: object
  - _id: string
  - name: string (localized by lang)
  - force: string (localized by lang)
  - level: string (localized by lang)
  - mechanic: string (localized by lang)
  - equipment: string (localized by lang)
  - primaryMuscles: array
  - secondaryMuscles: array
  - instructions: array
  - category: string (localized by lang)
  - images: array
  - id: string

RESPONSE SCHEMA: application/json

type: object
- properties:
  - message: string

[
  {
    "_id": "677471841533c77a3a55b4c1",
    "name": "Bent-Over Two-Arm Long Bar Row",
    "force": "pull"
  }
]

{
  "message": "parameter 'limit' must be greater than 0"
}

Dynamic Filters

Apply filters based on exercise attributes. Example: (level=expert&force=push&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 (localized by lang)
  - force: string (localized by lang)
  - level: string (localized by lang)
  - mechanic: string (localized by lang)
  - equipment: string (localized by lang)
  - primaryMuscles: array (items: string, localized by lang)
  - secondaryMuscles: array (items: object - details not specified)
  - instructions: array (items: string, localized by lang)
  - category: string (localized by lang)
  - images: array (items: string)
  - id: string

RESPONSE SCHEMA: application/json

type: object
- properties:
  - message: string

[
  {
    "_id": "677471831533c77a3a55b4ff",
    "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."
    ],
    "category": "strength",
    "images": [
      "Plyo_Kettlebell_Pushups/0.jpg",
      "Plyo_Kettlebell_Pushups/1.jpg"
    ],
    "id": "Plyo_Kettlebell_Pushups",
    "__v": 0
  }
]

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

Search

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.

Example Request:

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

Response Samples

RESPONSE SCHEMA: application/json

type: object
- exercises: array (items: object)

RESPONSE SCHEMA: application/json

type: object
- properties: object
  - message: string

{
  "exercises": [
    {
      "_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": "Please provide a search term."
}

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

Base URL

Get Started

All Exercises

GET/exercises

Response Samples

Lang

Example Request:

GET/exercises?lang=en

Response Samples

Fields

Example Request:

GET/exercises?fields

Response Samples

Page

Example Request:

GET/exercises?page=

Response Samples

Limit

Example Request:

GET /exercises?limit=

Response Samples

Dynamic Filters

Example Request:

GET/exercises?level=

Response Samples

Search

Example Request:

GET /exercises/search?query=

Response Samples

Get Exercise Images

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

Response Samples

Image Structure