mdmdcraft.aiDocs
Try the studio
Developers

API and agents

Private beta access for API, CLI, and MCP-backed agent workflows.

What is available today#

  • Unified conversion API for supported document paths.
  • Project API keys with account-managed create, rotate, and revoke.
  • CLI login through browser device-code approval.
  • Hosted MCP at https://mdcraft.ai/mcp with OAuth consent.

Current API endpoints#

  • POST /api/v1/convert
  • POST /api/v1/convert/file-to-markdown
  • GET /api/v1/conversions/{conversionId}
  • GET /api/v1/conversions/{conversionId}/artifacts
  • GET /api/v1/account/usage

Every conversion returns a stable conversionId.

Use either auth header:

  • Authorization: Bearer <api key>
  • x-api-key: <api key>

Secrets are shown once. mdcraft stores only the hash and prefix.

Supported beta conversions#

Current paths:

  • PDF, DOCX, DOC, HTML, TXT, Markdown, and images to Markdown
  • Markdown to PDF, DOCX, HTML, and TXT

Broader Pandoc-level formats will use the same API contract as worker support matures.

Response shape#

Core fields: conversionId, engineVersion, inputFormat, outputFormat, status, provider, strategy, warnings, qualityScore, artifactRefs, and summary.providerDiagnostics.

Provider diagnostics include the selected provider, attempted OCR providers, routing reason, fallback status, model, pages processed, OCR confidence, and estimated cost when available.

Technical limits#

Technical request protection is separate from studio plan limits:

  • project conversions: 30 requests per 10 minutes
  • key conversions: 20 requests per 10 minutes
  • project concurrency: 3 in-flight conversions
  • key concurrency: 2 in-flight conversions

429 responses include retry and limit headers.

CLI#

Start with:

npx @mdcraft/cli

The default terminal flow guides login, format selection, and output confirmation. See the CLI guide for scripted commands, batch conversion, and CI usage.

MCP#

Hosted MCP reuses the API backend contract and ledger. Start with the MCP guide when connecting ChatGPT, Claude Code, Cursor, or a local CLI stdio fallback.

Requesting beta access#

  • create an account
  • request API beta access from the account or developers area
  • wait for approval
  • create an API key from the account area or approve CLI login from the browser
  • run a first conversion and inspect summary.providerDiagnostics