API Specification

OpenAPI

Machine-readable OpenAPI 3.0 specification for programmatic integration.

openapi.json

Complete API specification with schemas and examples

View JSON Download

Endpoints

GET/health

Health Check

Returns API health status and version information.

GET/extract

Extract Markdown (GET)

Extract markdown from a URL using query parameters.

POST/extract

Extract Markdown (POST)

Extract markdown from a URL with full options support.

Request Headers

Header	Required	Description
x-api-key	No	API key when API_KEYS auth is enabled
x-api-version	No	Optional API version pin (current: 1.0.0)
Authorization	No	Bearer token for API authentication
Idempotency-Key	No	Unique key for idempotent requests (max 64 chars)
Content-Type	Yes	Must be application/json for POST requests

Key Schemas

Extract Request

JSON Schema

{
  "url": "https://example.com/article"
}

Enable strict mode by sending x-strict-mode: 1 header or strict_mode=1 query parameter.

Success Response

JSON Schema

{
  "success": true,
  "version": "1.0.0",
  "extractionPolicyVersion": "2026-02-13.v1",
  "url": "https://example.com/article",
  "canonicalUrl": "https://example.com/article",
  "title": "Article Title",
  "markdown": "# Article Title\n\nContent here...",
  "contentHash": "a1b2c3d4e5f6...",
  "extractedAt": "2025-02-13T10:00:00Z",
  "diagnostics": {
    "strictMode": true,
    "contentType": "text/html",
    "contentLength": 4523,
    "redirectCount": 0
  }
}

Error Response

JSON Schema

{
  "success": false,
  "code": "invalid_url",
  "message": "URL is required and must be a string",
  "requestId": "7f1c9f34-3b56-4a3a-9d65-1bb09a9fc431"
}

Error Codes

Code	Status	Description
`invalid_url`	400	URL is missing, malformed, or uses unsupported protocol
`blocked_url`	400	URL points to blocked hostname (localhost, private IP)
`fetch_failed`	400	Failed to fetch URL (network error or HTTP error)
`timeout`	400	Request exceeded 30-second timeout limit
`too_large`	400	Response body exceeded 10MB size limit
`unsupported_content_type`	400	Content-Type not HTML, markdown, or plain text
`empty_content`	400	Response body empty after filtering
`too_many_redirects`	400	Redirect chain exceeded max redirects
`unauthorized`	401	Invalid or missing API key
`rate_limited`	429	Request quota exceeded
`idempotency_conflict`	409	Same idempotency key used with different URL
`unsupported_api_version`	400	Requested API version is not supported
`invalid_request`	400	Request body is invalid JSON
`internal_error`	500	Unhandled internal server error

Strict Mode

When strict mode is enabled via x-strict-mode: 1 or strict_mode=1, the API performs additional validation:

Validates Content-Type is supported (HTML, markdown, or plain text)
Ensures content is not empty after filtering
Blocks private IP ranges and localhost URLs
Enforces response size limits (10MB)

Strict mode is opt-in via header/query and reported in diagnostics.

Idempotency Key

Include an Idempotency-Key header to ensure the same request returns identical results. Useful for:

Retrying failed requests without duplicate processing
Maintaining consistency across distributed systems
Reducing API calls for repeated URL extractions

Keys are unique per account and expire after 24 hours. Maximum length: 64 characters.

Back to Documentation Try Demo