API reference

URL to Markdown API: make your first request

Send a public URL or raw HTML to one endpoint. Receive Markdown, token counts and a request ID for your RAG pipeline, agent or automation. The public endpoint is available for integration testing without an API key.

1. Choose URL or HTML input

POST /api/v1/convert with Content-Type: application/json. Use exactly one source field. Raw HTML is the quickest deterministic test; URL mode fetches the source server and does not execute client-side JavaScript.

Public URL

curl -X POST https://aingestor.com/api/v1/convert \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/",
    "options": {
      "remove_navigation": true,
      "remove_ads": true,
      "preserve_code_blocks": true
    }
  }'

Raw HTML

curl -X POST https://aingestor.com/api/v1/convert \
  -H 'Content-Type: application/json' \
  -d '{"html":"<main><h1>Hello</h1><p>Useful content for an agent.</p></main>"}'
FieldTypeBehavior
urlstringPublic http/https URL. Provide this OR html.
htmlstringRaw HTML up to 512 KiB. Provide this OR url.
options.remove_navigationbooleanRemove navigation and sidebars; default true.
options.remove_adsbooleanRemove detected advertising containers; default true.
options.preserve_code_blocksbooleanRequest code preservation; default true. Check output on your document types.

2. Integrate with Python or JavaScript

Check the HTTP status before reading a successful conversion. Keep a client timeout of at least 30 seconds. Cache useful results in your own workflow and use bounded retries for transient failures.

Python requests

import requests

response = requests.post(
    "https://aingestor.com/api/v1/convert",
    json={
        "url": "https://example.com/",
        "options": {
            "remove_navigation": True,
            "remove_ads": True,
            "preserve_code_blocks": True,
        },
    },
    timeout=30,
)

response.raise_for_status()
print(response.json()["markdown"])

JavaScript / Node.js fetch

const response = await fetch("https://aingestor.com/api/v1/convert", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    url: "https://example.com/",
    options: {
      remove_navigation: true,
      remove_ads: true,
      preserve_code_blocks: true,
    },
  }),
});

if (!response.ok) throw new Error("HTTP " + response.status);
const result = await response.json();
console.log(result.markdown);

3. Convert HTML or URLs in n8n

  1. Add an HTTP Request node. Set method to POST and URL to https://aingestor.com/api/v1/convert.
  2. Enable a JSON body and pass url from the previous node, or html if you already fetched the document. Do not send both fields.
  3. Set the request timeout to 30,000 ms. Read the returned markdown field in your next node.
  4. Route non-2xx responses to an error branch. A source that blocks fetching may still be usable as pasted HTML you are permitted to process.

Understand the response

The schema shown is illustrative; counts and timing depend on the input. Token counts use cl100k_base. Estimated savings are a cost illustration, not a quote for your model. Preserve the request ID when contacting support.

This endpoint converts one document at a time. It does not crawl an entire domain, bypass login or CAPTCHA, render browser JavaScript, generate embeddings or perform semantic chunking.

JSON response shape

{
  "markdown": "# Hello\n\nUseful content for an agent.",
  "tokens_before": 22,
  "tokens_after": 9,
  "reduction_percent": 59.09,
  "estimated_cost_savings": "$0.0001",
  "title": null,
  "description": "Hello Useful content for an agent.",
  "processing_ms": 100,
  "request_id": "returned-request-id"
}

Limits and errors

Current defaults: 512 KiB raw HTML, 5 MiB fetched HTML, 512 KiB Markdown output, five redirects and a 20-second processing budget. Public API calls are limited to 60 per IP per hour; the playground uses 30 per IP per hour. For production volume, contact us about your requirements.

HTTPError codeWhat to do
400unsafe_urlUse a public HTTP/HTTPS destination. Private addresses are rejected, including redirects.
413payload_too_large / response_too_largeReduce the HTML input or source page size.
422invalid_content_type / extraction_failedUse an HTML document with readable content. JSON, images and PDFs are not accepted.
429rate_limitedWait before retrying; do not run a tight retry loop.
502fetch_failedThe origin could not be fetched or returned an error. Try pasted HTML or another permitted public URL.
504fetch_timeout / processing_timeoutUse a smaller/faster source. Retry with bounded backoff.
508too_many_redirectsUse the final public URL or correct the redirect chain.

Error responses include error.code, error.message and request_id. A 502 from a blocked or failing origin does not mean every source is unavailable.

More HTML examplesHTML vs Markdown for LLMsContent extraction patternsIntegration support