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 | "all" No 20 Maximum number of badges to return. Accepted range: 1–200. Pass all to return every matching badge with no cap.

Response Schema

Field Type Description
total integer Total badges matching the current filters, before slicing.
limit integer | null The effective limit applied to this response. null when limit=all was requested.
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.
categories string[] One or more categories 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)",
      "categories": ["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.

  • —

    Default response size: Without an explicit limit the API returns 20 badges. The cap is 200 for numeric values; use limit=all to retrieve the full catalogue in a single request.

  • —

    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.