OpenAPI Specification

The Unmarkdown™ API is documented in a machine-readable OpenAPI 3.1 specification. This spec can be used with API clients, code generators, and testing tools.

Specification URL

The OpenAPI spec is available at:

https://unmarkdown.com/openapi.json

Fetch the Spec

curl https://unmarkdown.com/openapi.json

const res = await fetch('https://unmarkdown.com/openapi.json');
const spec = await res.json();
console.log(spec.info.title);  // "Unmarkdown API"
console.log(spec.info.version); // "1.0.0"

import requests

res = requests.get('https://unmarkdown.com/openapi.json')
spec = res.json()
print(spec['info']['title'])

What Is Included

The OpenAPI spec covers all v1 API endpoints:

• POST /v1/convert - Convert markdown to destination-specific output
• POST /v1/documents - Create a document
• GET /v1/documents - List documents
• GET /v1/documents/
  - Get a document
• PATCH /v1/documents/
  - Update a document
• DELETE /v1/documents/
  - Delete a document
• POST /v1/documents/
  /publish - Publish a document
• DELETE /v1/documents/
  /publish - Unpublish a document
• POST /v1/documents/publish - Create and publish in one call
• POST /v1/demo/publish - Demo publish (no auth)
• POST /v1/demo/claim - Claim a demo document
• GET /v1/templates - List templates
• GET /v1/usage - Get usage stats

Each endpoint includes request parameters, request body schemas, response schemas, and error responses.

Using with Tools

Swagger UI / Swagger Editor:
Import the URL into Swagger Editor to browse the API interactively.

Postman:
Import https://unmarkdown.com/openapi.json as a collection in Postman for ready-to-use request templates.

Code generation:
Use OpenAPI Generator to generate client libraries in 50+ languages:

npx @openapitools/openapi-generator-cli generate \
  -i https://unmarkdown.com/openapi.json \
  -g typescript-fetch \
  -o ./unmarkdown-client

Versioning

The spec follows the same versioning as the API. All current endpoints are under the v1 prefix. Breaking changes will introduce a new version prefix.