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>"}'| Field | Type | Behavior |
|---|---|---|
| url | string | Public http/https URL. Provide this OR html. |
| html | string | Raw HTML up to 512 KiB. Provide this OR url. |
| options.remove_navigation | boolean | Remove navigation and sidebars; default true. |
| options.remove_ads | boolean | Remove detected advertising containers; default true. |
| options.preserve_code_blocks | boolean | Request 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
- Add an HTTP Request node. Set method to POST and URL to
https://aingestor.com/api/v1/convert. - Enable a JSON body and pass
urlfrom the previous node, orhtmlif you already fetched the document. Do not send both fields. - Set the request timeout to 30,000 ms. Read the returned
markdownfield in your next node. - 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.
| HTTP | Error code | What to do |
|---|---|---|
| 400 | unsafe_url | Use a public HTTP/HTTPS destination. Private addresses are rejected, including redirects. |
| 413 | payload_too_large / response_too_large | Reduce the HTML input or source page size. |
| 422 | invalid_content_type / extraction_failed | Use an HTML document with readable content. JSON, images and PDFs are not accepted. |
| 429 | rate_limited | Wait before retrying; do not run a tight retry loop. |
| 502 | fetch_failed | The origin could not be fetched or returned an error. Try pasted HTML or another permitted public URL. |
| 504 | fetch_timeout / processing_timeout | Use a smaller/faster source. Retry with bounded backoff. |
| 508 | too_many_redirects | Use 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.