The Free Chord API for Developers

This API provides access to a structured collection of musical data, including chords, notes, and chord types. It is designed to be both educational and practical, allowing developers to retrieve musical information that can be used in web applications, learning tools, or creative projects.

The API has been designed to serve data in both English and Spanish, so you can use the relevant keys to get the data in the language you want.

The API includes the following main resources:

• Chords: 48 different chords combining various root notes and chord types.
• Notes: 17 musical notes including natural, sharp, and flat notes.
• Chord Types: 4 chord types, such as major and minor.

All endpoints return data in JSON format, and follow a clear, RESTful structure. For example:

• GET /chords – returns all available chords.
• GET /notes – returns the list of supported musical notes.
• GET /chord-types – returns all chord type definitions.

*Additional endpoints and query options are available for more advanced usage, which are explained in the final section.

The API is lightweight, fast, and ideal for quick integration into projects with musical features or for practicing API consumption techniques.

This API is designed for two main audiences:

• Web development beginners – If you're learning how to work with APIs, this is a perfect starting point. The API is simple, well-structured, and clearly documented. It allows you to practice making HTTP requests, handling JSON responses, and integrating external data into your projects.
  Additionally, the API is documented with Swagger and JSDoc, and the full source code is available on GitHub — great resources for learning and exploring real-world examples.


• Music lovers and creative coders – Whether you're building a music theory tool, an educational app, or just experimenting with creative web ideas, this API provides musical data that can enrich your project in a meaningful way.

Whether you're writing your first fetch() call or adding interactive musical elements to a blog or portfolio, this API aims to be useful, inspiring, and easy to use.

Using this API is simple and flexible. All endpoints return data in JSON format and can be accessed with any HTTP client or tool (such as fetch, axios, Postman, or curl).

Here are some of the most useful endpoints:

• GET /chords – Returns a list of all available chords. You can optionally filter results using query parameters:
  • /chords?note=c – Returns only chords based on note C.
  • /chords?type=major – Returns only major chords.
  • Combined: ?note=a_flat&type=7 - Returns "Ab 7" chord
  • Pagination: /chords?limit=4&page=2 – Returns four chords (from item 5 to 8, based on pagination).
• GET /chords/:id – Returns a single chord by its unique ID.
• GET /notes – Returns all available musical notes.
• GET /chord-types – Returns all chord type definitions.
• GET /chord-types/:id – Returns a single chord type by its unique ID.

Example using fetch in JavaScript:

fetch('https://your-api-url.com/chords?note=c&type=7')
.then(res => res.json())
.then(data => console.log(data))
.catch(err => console.error(err));

For more details and testing, check the interactive documentation available via Swagger where you can alse see object response examples.

This API is built with a set of powerful and well-known technologies. Here's a breakdown of the stack:

• Node.js – A JavaScript runtime built used to run the backend of the application and handle HTTP requests.
• Express – A minimalist web framework for Node.js, used to handle HTTP requests and define API routes.
• Mongoose – An Object Data Modeling (ODM) library for MongoDB, providing a straightforward way to interact with the database.
• Swagger UI & YAML – Swagger UI is used to provide an interactive, user-friendly interface for exploring the API. The API documentation is defined using a YAML file, which is processed to generate the documentation.
• Winston – A logging library for Node.js, used for logging important events and errors within the application.
• EJS (Embedded JavaScript) – A templating engine for rendering views and dynamic content on the server-side.
• CORS – Middleware to enable Cross-Origin Resource Sharing (CORS), allowing your API to be accessed from different domains.
• dotenv – A zero-dependency module to load environment variables from a `.env` file into the application, keeping sensitive data like API keys secure.
• YAML.js – A library to parse and serialize YAML data. It's used to load and manage configuration files in the YAML format.

These technologies work together to provide a fast, flexible, and scalable API that’s easy to develop, document, and maintain.

This API is designed to be easy to use, with comprehensive documentation and resources to help developers get started quickly.

If you are a junior developer or just starting out, you will find the following resources helpful:

• Swagger UI – Interactive API documentation for exploring all available endpoints. You can test requests directly from the UI. Access it via Swagger Documentation.
• JSDoc – The code is fully documented using JSDoc comments. The documentation is automatically generated into a web-based UI, which you can explore for detailed information about each function, endpoint, and the overall API structure. Access the documentation at JSDoc Documentation.
• GitHub Repository – The full source code of the API is available on GitHub. You can contribute, fork, or simply explore the codebase. View the Repository.
• Community – Feel free to reach out via GitHub Issues or the project's discussion board for help, feedback, or questions. We are happy to support developers at all levels.

Whether you're just learning how to work with APIs or you're a seasoned developer, these resources should help you get the most out of the API.