API Reference

Authentication

All requests require an API key. Create one in Settings → API Keys and send it as a bearer token (or an x-api-key header). Keys are rate-limited to 60 requests/minute; credits are the real spend cap.

Authorization: Bearer <your-api-key>
# or
x-api-key: <your-api-key>

Base URL: https://markstream.dev

Convert a source

Converts one source to markdown and returns the result inline. Charges 1 credit on success; failed conversions are automatically refunded. The request body is selected by Content-Type: JSON for a URL, multipart for a file.

curl -X POST https://markstream.dev/api/v1/convert \
  -H 'Authorization: Bearer <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com/article"}'

Example response

{
  "id": "V1StGXR8_Z5jdHi6B-myT",
  "status": "completed",
  "title": "Example Article",
  "sourceType": "url",
  "sourceUrl": "https://example.com/article",
  "provider": "jina",
  "markdown": "# Example Article\n\nClean markdown content…",
  "contentChars": 4821,
  "creditsCharged": 1,
  "createdAt": 1733011200000
}

Get a conversion

Fetch a past conversion (owned by the key's account), including its full markdown. Returns the same shape as the convert response.

curl https://markstream.dev/api/v1/conversions/V1StGXR8_Z5jdHi6B-myT \
  -H 'Authorization: Bearer <your-api-key>'

Response shape

Supported sources

• Any web page — rendered to clean markdown, boilerplate stripped.
• Facebook & SimilarWeb — login-walled marketing sources, routed to dedicated scrapers automatically by URL.
• Files — PDF, Word (.docx), Excel (.xlsx/.xls), CSV, and images. Scanned/image PDFs are OCR'd. Max 10 MB; HTML uploads are rejected (use the URL form).

Errors & status codes

Errors are JSON: { "error": string, "code": string }. A failed conversion never costs a credit.