{
  "openapi": "3.1.0",
  "info": {
    "title": "GetMarkdown Agent API",
    "version": "1.0.0",
    "summary": "Machine-readable agent surface for GetMarkdown, the file-to-Markdown converter.",
    "description": "GetMarkdown converts supported PDF, Office, HTML, text, image, and audio files into clean Markdown. Free conversions run in the user's browser and have no API; this specification documents every machine-readable endpoint agents can call directly: Markdown content negotiation, agent guidance documents, the JSON agent status API, and the MCP server. File submission itself is a user action performed through the web interface at https://www.getmarkdown.com/ (free) or /pro (Advanced PDF).",
    "contact": {
      "name": "GetMarkdown",
      "url": "https://www.getmarkdown.com/contact",
      "email": "aark@getmarkdown.com"
    },
    "license": {
      "name": "Site content © GetMarkdown",
      "url": "https://www.getmarkdown.com/terms"
    }
  },
  "servers": [
    {
      "url": "https://www.getmarkdown.com",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "Content negotiation",
      "description": "Markdown representations of GetMarkdown pages."
    },
    {
      "name": "Agent guidance",
      "description": "Instructions and reference documents written for LLM agents."
    },
    {
      "name": "Agent API",
      "description": "JSON endpoints agents can call programmatically."
    },
    {
      "name": "MCP",
      "description": "Model Context Protocol server exposing GetMarkdown guidance as tools."
    },
    {
      "name": "Discovery",
      "description": "Crawler and agent discovery files."
    }
  ],
  "paths": {
    "/": {
      "get": {
        "operationId": "getHomepage",
        "summary": "Get the GetMarkdown homepage",
        "description": "Returns the homepage. Supports HTTP content negotiation: send `Accept: text/markdown` to receive the Markdown representation (Content-Location: /index.md). Send `Accept: text/html` for HTML. Requests that accept neither representation return 406 with a Markdown explanation.",
        "tags": [
          "Content negotiation"
        ],
        "parameters": [
          {
            "name": "Accept",
            "in": "header",
            "required": false,
            "description": "Media type preference. `text/markdown` selects the Markdown representation.",
            "schema": {
              "type": "string",
              "examples": [
                "text/markdown",
                "text/html"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Homepage in the negotiated representation.",
            "headers": {
              "Vary": {
                "schema": {
                  "type": "string"
                },
                "description": "Always includes Accept and Accept-Encoding."
              },
              "Content-Location": {
                "schema": {
                  "type": "string"
                },
                "description": "/index.md when Markdown is negotiated."
              },
              "Link": {
                "schema": {
                  "type": "string"
                },
                "description": "Alternate link to the Markdown representation."
              }
            },
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              },
              "text/markdown": {
                "schema": {
                  "$ref": "#/components/schemas/MarkdownDocument"
                }
              }
            }
          },
          "406": {
            "description": "Accept header matches neither supported representation.",
            "content": {
              "text/markdown": {
                "schema": {
                  "$ref": "#/components/schemas/MarkdownDocument"
                }
              }
            }
          }
        }
      }
    },
    "/index.md": {
      "get": {
        "operationId": "getHomepageMarkdown",
        "summary": "Get the homepage as Markdown",
        "description": "Direct Markdown representation of the homepage, without content negotiation.",
        "tags": [
          "Content negotiation"
        ],
        "responses": {
          "200": {
            "description": "Markdown document.",
            "content": {
              "text/markdown": {
                "schema": {
                  "$ref": "#/components/schemas/MarkdownDocument"
                }
              }
            }
          }
        }
      }
    },
    "/developers.md": {
      "get": {
        "operationId": "getDeveloperResourcesMarkdown",
        "summary": "Get developer resources as Markdown",
        "description": "Integration status, agent endpoints, and developer resources in Markdown.",
        "tags": [
          "Agent guidance"
        ],
        "responses": {
          "200": {
            "description": "Markdown document.",
            "content": {
              "text/markdown": {
                "schema": {
                  "$ref": "#/components/schemas/MarkdownDocument"
                }
              }
            }
          }
        }
      }
    },
    "/llms.txt": {
      "get": {
        "operationId": "getLlmsTxt",
        "summary": "Get concise agent instructions",
        "description": "The llms.txt guidance file: when to use GetMarkdown, limits, workflow selection, and canonical links.",
        "tags": [
          "Agent guidance"
        ],
        "responses": {
          "200": {
            "description": "llms.txt document.",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/MarkdownDocument"
                }
              }
            }
          }
        }
      }
    },
    "/llms-full.txt": {
      "get": {
        "operationId": "getLlmsFullTxt",
        "summary": "Get the expanded LLM reference",
        "description": "Expanded product, privacy, package, and troubleshooting reference for agents that need more context.",
        "tags": [
          "Agent guidance"
        ],
        "responses": {
          "200": {
            "description": "llms-full.txt document.",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/MarkdownDocument"
                }
              }
            }
          }
        }
      }
    },
    "/api/agent/status": {
      "get": {
        "operationId": "getAgentStatus",
        "summary": "Get the agent integration status",
        "description": "Returns a JSON description of every agent-facing endpoint, supported formats, limits, and the current conversion API availability. Use this for capability discovery before choosing a workflow.",
        "tags": [
          "Agent API"
        ],
        "responses": {
          "200": {
            "description": "Agent status document.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentStatus"
                }
              }
            }
          }
        }
      }
    },
    "/api/mcp": {
      "post": {
        "operationId": "callMcpServer",
        "summary": "Call the GetMarkdown MCP server",
        "description": "Model Context Protocol endpoint using the Streamable HTTP transport. POST a JSON-RPC 2.0 message (`initialize`, `tools/list`, or `tools/call`; notifications return 202). The server is stateless, so no session management is required. Tools: `get_agent_guidance`, `list_supported_formats`, `recommend_workflow`, `get_developer_resources`.",
        "tags": [
          "MCP"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/JsonRpcRequest"
              },
              "examples": {
                "initialize": {
                  "summary": "Initialize the MCP session",
                  "value": {
                    "jsonrpc": "2.0",
                    "id": 1,
                    "method": "initialize",
                    "params": {
                      "protocolVersion": "2025-06-18",
                      "capabilities": {},
                      "clientInfo": {
                        "name": "example-agent",
                        "version": "1.0.0"
                      }
                    }
                  }
                },
                "toolsList": {
                  "summary": "List MCP tools",
                  "value": {
                    "jsonrpc": "2.0",
                    "id": 2,
                    "method": "tools/list"
                  }
                },
                "toolsCall": {
                  "summary": "Call an MCP tool",
                  "value": {
                    "jsonrpc": "2.0",
                    "id": 3,
                    "method": "tools/call",
                    "params": {
                      "name": "recommend_workflow",
                      "arguments": {
                        "format": "pdf",
                        "fileSizeMb": 80,
                        "pageCount": 200
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC 2.0 response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonRpcResponse"
                }
              }
            }
          },
          "202": {
            "description": "Notification accepted; no response body."
          },
          "400": {
            "description": "Malformed JSON-RPC request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonRpcResponse"
                }
              }
            }
          },
          "405": {
            "description": "Method not supported by this stateless endpoint (GET or DELETE).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/openapi.json": {
      "get": {
        "operationId": "getOpenApiSpec",
        "summary": "Get this OpenAPI specification",
        "description": "The OpenAPI 3.1 document describing every GetMarkdown agent endpoint.",
        "tags": [
          "Discovery"
        ],
        "responses": {
          "200": {
            "description": "OpenAPI specification.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "OpenAPI 3.1 document."
                }
              }
            }
          }
        }
      }
    },
    "/sitemap.xml": {
      "get": {
        "operationId": "getSitemap",
        "summary": "Get the XML sitemap",
        "description": "Every public GetMarkdown URL.",
        "tags": [
          "Discovery"
        ],
        "responses": {
          "200": {
            "description": "Sitemap XML.",
            "content": {
              "application/xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/robots.txt": {
      "get": {
        "operationId": "getRobotsTxt",
        "summary": "Get robots.txt",
        "description": "Crawler directives for GetMarkdown, including allowed paths and sitemap location.",
        "tags": [
          "Discovery"
        ],
        "responses": {
          "200": {
            "description": "robots.txt document.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "MarkdownDocument": {
        "type": "string",
        "description": "A UTF-8 Markdown (or plain text) document."
      },
      "Error": {
        "type": "object",
        "description": "Structured JSON error returned by every GetMarkdown API endpoint.",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code, e.g. `not_found`."
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of what went wrong."
              },
              "hint": {
                "type": "string",
                "description": "Actionable next step, usually a URL to recover with."
              }
            }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "description": "Envelope for structured JSON errors.",
        "properties": {
          "error": {
            "$ref": "#/components/schemas/Error"
          }
        }
      },
      "AgentStatus": {
        "type": "object",
        "required": [
          "service",
          "version",
          "conversionApiAvailable",
          "endpoints",
          "supportedFormats",
          "limits"
        ],
        "properties": {
          "service": {
            "type": "string",
            "const": "getmarkdown"
          },
          "version": {
            "type": "string",
            "description": "Spec version of the agent surface."
          },
          "conversionApiAvailable": {
            "type": "boolean",
            "description": "Always false: file conversion is performed by the user through the web interface, not through an API."
          },
          "endpoints": {
            "type": "array",
            "description": "Every documented agent endpoint.",
            "items": {
              "type": "object",
              "required": [
                "method",
                "path",
                "description"
              ],
              "properties": {
                "method": {
                  "type": "string"
                },
                "path": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                }
              }
            }
          },
          "supportedFormats": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "File extensions accepted by the free browser converter."
          },
          "limits": {
            "type": "object",
            "properties": {
              "maxFileSizeMb": {
                "type": "number",
                "const": 10
              },
              "maxFilesPerBatch": {
                "type": "number",
                "const": 8
              }
            }
          },
          "workflows": {
            "type": "object",
            "properties": {
              "freeBrowserConversion": {
                "type": "string",
                "format": "uri"
              },
              "advancedPdf": {
                "type": "string",
                "format": "uri"
              }
            }
          }
        }
      },
      "JsonRpcRequest": {
        "type": "object",
        "required": [
          "jsonrpc",
          "method"
        ],
        "properties": {
          "jsonrpc": {
            "type": "string",
            "const": "2.0"
          },
          "id": {
            "description": "Request identifier. Omit for notifications.",
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ]
          },
          "method": {
            "type": "string",
            "examples": [
              "initialize",
              "tools/list",
              "tools/call",
              "notifications/initialized"
            ]
          },
          "params": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "JsonRpcResponse": {
        "type": "object",
        "required": [
          "jsonrpc"
        ],
        "properties": {
          "jsonrpc": {
            "type": "string",
            "const": "2.0"
          },
          "id": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ]
          },
          "result": {
            "type": "object",
            "additionalProperties": true,
            "description": "Result payload when the request succeeded."
          },
          "error": {
            "type": "object",
            "description": "JSON-RPC error object when the request failed.",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "number",
                "description": "JSON-RPC error code, e.g. -32601 (method not found), -32602 (invalid params), -32700 (parse error)."
              },
              "message": {
                "type": "string"
              },
              "data": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        }
      }
    }
  }
}