GitHub

GitHub Markdown API

The GitHub Markdown API is a REST service that converts Markdownespecially GitHub Flavored Markdowninto the same HTML GitHub renders in READMEs, issues, and pull requests, so external apps can display content consistently with GitHub.

GitHub OpenAPI

Operations 2

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

POST /markdown Render Markdown to HTML · Render a Markdown document #
Ask an LLM
“How do I turn Markdown into HTML the same way GitHub displays it?”
“Can issue references like #42 link to the right repository when I render GitHub Flavored Markdown?”
Tell an agent
Render {text} as HTML.
Render {text} in {mode} mode with repository context {context}.
POST /markdown/raw Render plain-text Markdown like a README · Render a Markdown document in raw mode #
Ask an LLM
“Can I send Markdown as plain text instead of JSON and get HTML back?”
“What's the size limit for rendering a raw Markdown document without GitHub Flavored extensions?”
Tell an agent
Render this plain-text Markdown file in raw mode, the way a README displays.
Post my Markdown as text/plain and return raw-mode HTML.

Documentation

📖
Documentation
https://docs.github.com/en/rest/markdown

Specifications

⚙
OpenAPI
https://artifacts.apis.io/github/openapi/github-markdown-api-openapi.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/github:github-markdown-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

github-markdown-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Github Markdown API
  version: 1.1.4
  contact:
    name: Support
    url: https://support.github.com/contact?tags=dotcom-rest-api
  license:
    name: MIT
    url: https://spdx.org/licenses/MIT
  termsOfService: https://docs.github.com/articles/github-terms-of-service
  x-github-plan: api.github.com
  description: 'Operations tagged markdown across 2 of this provider''s published API definitions: github-github-full.yml, github-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.github.com
tags:
- name: Markdown
  description: Render GitHub flavored Markdown
paths:
  /markdown:
    post:
      summary: Render a Markdown document
      description: Depending on what is rendered in the Markdown, you may need to provide additional token scopes for labels, such as `issues:read` or `pull_requests:read`.
      operationId: markdown/render
      tags:
      - Markdown
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/rest/markdown/markdown#render-a-markdown-document
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                text:
                  description: The Markdown text to render in HTML.
                  type: string
                mode:
                  description: The rendering mode.
                  enum:
                  - markdown
                  - gfm
                  default: markdown
                  example: markdown
                  type: string
                context:
                  description: The repository context to use when creating references in `gfm` mode.  For example, setting `context` to `octo-org/octo-repo` will change the text `#42` into an HTML link to issue 42 in the `octo-org/octo-repo` repository.
                  type: string
              required:
              - text
              type: object
            examples:
              default:
                summary: Rendering markdown
                value:
                  text: Hello **world**
      responses:
        '200':
          description: Response
          headers:
            Content-Type:
              $ref: '#/components/headers/content-type'
            Content-Length:
              example: '279'
              schema:
                type: string
            X-CommonMarker-Version:
              $ref: '#/components/headers/x-common-marker-version'
          content:
            text/html:
              schema:
                type: string
              examples:
                default:
                  summary: Example response
                  value: <p>Hello <strong>world</strong></p>
        '304':
          $ref: '#/components/responses/not_modified'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: markdown
        subcategory: markdown
    servers:
    - url: https://api.github.com
  /markdown/raw:
    post:
      summary: Render a Markdown document in raw mode
      description: You must send Markdown as plain text (using a `Content-Type` header of `text/plain` or `text/x-markdown`) to this endpoint, rather than using JSON format. In raw mode, GitHub Flavored Markdown is not supported and Markdown will be rendered in plain format like a README.md file. Markdown content must be 400 KB or less.
      operationId: markdown/render-raw
      tags:
      - Markdown
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/rest/markdown/markdown#render-a-markdown-document-in-raw-mode
      parameters: []
      requestBody:
        required: false
        content:
          text/plain:
            schema:
              type: string
            examples:
              default:
                value:
                  text: Hello **world**
          text/x-markdown:
            schema:
              type: string
            examples:
              default:
                summary: Rendering markdown
                value:
                  text: Hello **world**
      responses:
        '200':
          description: Response
          headers:
            X-CommonMarker-Version:
              $ref: '#/components/headers/x-common-marker-version'
          content:
            text/html:
              schema:
                type: string
              examples:
                default:
                  summary: Example response
                  value: <p>Hello <strong>world</strong></p>
        '304':
          $ref: '#/components/responses/not_modified'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: markdown
        subcategory: markdown
    servers:
    - url: https://api.github.com
components:
  headers:
    x-common-marker-version:
      example: 0.17.4
      schema:
        type: string
    content-type:
      example: text/html
      schema:
        type: string
  responses:
    not_modified:
      description: Not modified
externalDocs:
  description: GitHub v3 REST API
  url: https://docs.github.com/rest/
x-refined-from:
- github-github-full.yml
- github-openapi.json