Markdown Badges
View Repo

API Reference

Markdown Badges provides a public, read-only HTTP API that returns badge data as JSON. No authentication or API key is required. It is designed for lightweight integrations such as IDE plugins, browser extensions, CLI tools, and similar developer utilities.

Base URL

https://markdown-badges.vercel.app/api

Endpoints

GET

/api/badges

Returns a list of badges. Results can be narrowed with a fuzzy search query and capped with a limit. When no parameters are provided, the first 20 badges are returned.

Query Parameters

Parameter Type Required Default Description
search string No — Fuzzy search against badge names. Must be at least 1 character when provided.
limit integer No 20 Maximum number of badges to return. Accepted range: 1–200.

Response Schema

Field Type Description
total integer Total badges matching the current filters, before slicing.
limit integer The effective limit applied to this response.
count integer Number of items in data (may be less than limit when results are exhausted).
data Badge[] Array of badge objects.

Badge Object

Field Type Description
id string Unique identifier for the badge.
name string Human-readable name of the technology or service.
url string (URL) Official website of the technology.
markdown string Ready-to-use Markdown snippet to embed the badge.
category string Category the badge belongs to (e.g. Frameworks, Languages).

Example Request

GET https://markdown-badges.vercel.app/api/badges?search=react&limit=5

Example Response

{
  "total": 3,
  "limit": 5,
  "count": 3,
  "data": [
    {
      "id": "react",
      "name": "React",
      "url": "https://reactjs.org/",
      "markdown": "![React](https://img.shields.io/badge/react-%2320232a.svg?style=for-the-badge&logo=react&logoColor=%2361DAFB)",
      "category": "Frameworks"
    },
    ...
  ]
}

Limitations

  • —

    Rate limit: 60 requests per minute per IP address. Exceeding this returns a 429 Too Many Requests response with a Retry-After header indicating when to retry.

  • —

    Static dataset: The badge catalogue is curated and updated manually. The API reflects the current dataset at deploy time, not a live data source.

  • —

    Maximum response size: A single request returns at most 200 badges (limit=200). Pagination is not supported beyond this cap.

  • —

    Read-only: The API exposes no write operations. Badge data cannot be created, updated, or deleted via the API.

Acceptable Use

This API is intended for use in developer tools, IDE plugins, browser extensions, CLI utilities, and similar integrations that help developers find and insert badges into their projects.

Please do not use this API to build a product or service that replicates or directly competes with Markdown Badges as a standalone application. If you are unsure whether your use case qualifies, check the source repository on GitHub or open an issue to discuss it.