API and agents#

mdcraft offers a private API beta for Files to Markdown workflows.

What is available today#

• The browser studio is live today.
• Approved accounts can request API beta access from the product.
• The current API is focused on document-to-Markdown conversion.
• Approved accounts can create, rotate, and revoke API keys from the account area.

Current API endpoints#

The current beta surface is:

• PDF to Markdown for retrieval and knowledge ingestion
• DOCX to Markdown for docs migration
• image to Markdown for OCR-heavy recovery workflows
• project-scoped usage tracking and conversion lookup

The available endpoints are:

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

The API uses project-based keys and returns a stable conversionId so clients can fetch the same result again after the initial request.

Use either auth header:

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

API key secrets are only shown once when they are created or rotated. The product stores only the hash and key prefix.

Supported beta inputs#

The current Files -> Markdown API beta is focused on:

• PDF
• DOCX
• PNG
• JPG

Markdown export workflows remain part of the browser studio for now.

Response shape#

Each conversion response is built around:

• conversionId
• engineVersion
• inputFormat
• outputFormat
• status
• provider
• strategy
• warnings
• qualityScore
• artifactRefs
• 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#

The beta API has technical request protection 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-after, x-ratelimit-*, and x-mdcraft-limit-* headers.

MCP and CLI#

MCP and CLI support are not public yet. The current integration surface is the API beta.

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
• run a first conversion and inspect summary.providerDiagnostics