# HTML to markdown API: send HTML, get markdown or text | Spider

Spider's transform API turns HTML you already have into markdown or plain text, without fetching the page. $0.0001 per document, pay as you go.

Canonical: https://spider.cloud/api/transform/

## Transform API. HTML in, markdown out.

Your agent sends HTML it already has, and Spider returns each document as markdown or plain text.

Request

```
curl https://api.spider.cloud/transform \  -H "Authorization: Bearer $SPIDER_API_KEY" \  -H "Content-Type: application/json" \  -d '{"data":[{"html":"<h1>Hello</h1><p>World</p>"}],"return_format":"markdown"}'
```

Response 200, content\[0]

1. \# Hello
2. World

Recorded November 19, 2026. These 2 lines are the whole of content\[0] this request returned.

In [this one recorded run](#recorded-run), a 19,362 byte product page came back as 4,073 bytes of markdown, 21.0% of the input, in 0.26 seconds from a laptop.

$0.0001 per document returned. Pay as you go, with no subscription.

[Get an API key](https://spider.cloud/register/)

before and after one page

Input HTML

19,362 bytes, 819 lines

```
  <title> It&#39;s Only the Himalayas | Books to Scrape - Sandbox </title>  <header class="header container-fluid">  </div>  <ul class="breadcrumb">  <a href="../../index.html">Home</a>  <h1>It&#39;s Only the Himalayas</h1>  <p class="price_color">£45.17</p>  In stock (19 available)  <div class="alert alert-warning" role="alert"><strong>Warning!</strong> This is a demo website for web scraping purposes. Prices and ratings [60 more characters]  <h2>Product Description</h2>  <p>“Wherever you go, whatever you do, just . . . don’t do anything stupid.” —My MotherDuring her yearlong adventure backpacking from South A [1,272 more characters]  <h2>Product Information</h2>  <table class="table table-striped">  <th>UPC</th><td>a22124811bfa8350</td>  <th>Product Type</th><td>Books</td>  <th>Price (excl. tax)</th><td>£45.17</td>  </table>  <h2>Products you recently viewed</h2>  <footer class="footer container-fluid">  <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script>
```

Lines quoted from the page by their numbers, with leading spaces trimmed.

`"return_format": "markdown"`

4,073 bytes, 76 lines, 21.0% of the input, 0.26 s

```
 It's Only the Himalayas | Books to Scrape - Sandbox [Books to Scrape](../../index.html) We love being scraped! * [Home](../../index.html) * [Books](../category/books_1/index.html) * [Travel](../category/books/travel_2/index.html) * It's Only the Himalayas ![It&#39;s Only the Himalayas](../../media/cache/6d/41/6d418a73cc7d4ecfd75ca11d854041db.jpg) # It's Only the Himalayas £45.17 ** In stock (19 available)  **Warning!** This is a demo website for web scraping purposes. Prices and ratings here were randomly assigned and have no real meaning. ## Product Description  ## Product Information |UPC|a22124811bfa8350| |Product Type|Books| |Price (excl. tax)|£45.17| |Price (incl. tax)|£45.17| |Tax|£0.00| |Availability|In stock (19 available)| |Number of reviews|0| ## Products you recently viewed
```

The header line, the breadcrumb, the headings, the price and the product table came through, and the scripts did not. Some flaws arrived with it: the lines that hold only `**` come from icon elements, `&#39;` is left in the image alt on line 7, the table has no separator row because the source table has no header row, and links stay relative.

`"return_format": "text"`

2,322 bytes, 10 lines, 12.0% of the input, 0.23 s

```
 It&#39;s Only the Himalayas | Books to Scrape - Sandbox Books to Scrape We love being scraped! Home Books Travel It&#39;s Only the Himalayas It&#39;s Only the Himalayas £45.17 In stock (19 availab [3 more characters] &nbsp; Warning! This is a demo website for web scraping purposes. Prices and ratings here were randomly assigned and have no real meaning. Product  [1,668 more characters] Add to basket Mesaerion: The Best Science ... £37.59 In stock Add to basket Olio £23.88 In stock  Add to basket
```

The markup is gone and the words run together on a few long lines. The header, the breadcrumb words and each Add to basket label stay in, and `&#39;` and `&nbsp;` are left as the page wrote them.

`"return_format": "markdown", "readability": true`

1,471 bytes, 3 lines, 7.6% of the input, 0.37 s

```
 It's Only the Himalayas # It's Only the Himalayas “Wherever you go, whatever you do, just . . . don’t do anything stupid.” —My MotherDuring her yearlong adventure backpacking from South Afri [1,265 more characters]
```

Reader-mode extraction kept the title, the h1 and the description, and dropped the price and the product table. Line 3 is the description as the page wrote it, a cut off teaser and then the full text.

- In

  - 19,362 bytes
  - the product page HTML, 819 lines

- Out

  - 4,073 bytes
  - `content[0]` as markdown, 76 lines, 21.0% of the input

- Seconds

  - 0.26 s
  - the markdown call, timed on the laptop that sent it

- Price

  - $0.0001
  - per document returned, from the rate card

Recorded November 19, 2026 from a laptop. The input is the HTML of one product page on books.toscrape.com, a public sandbox site, fetched once with /scrape before any of these calls. Transform fetched nothing.

## What comes back

A JSON object with one field, `content`: an array of strings, one for each document converted.

field

- `content`

  Each string is one document in the format you asked for. A document with empty HTML is skipped, so the array can hold fewer strings than `data` has documents.

The recorded responses held `content` and nothing else, with no status, error or cost field. The markdown response was 4,170 bytes for 4,073 bytes of markdown.

## What goes in the request

`data` and one format. The samples send the smallest document there is. The recorded runs sent the product page the same way, with its `url` beside the `html`.

```
curl https://api.spider.cloud/transform \  -H "Authorization: Bearer $SPIDER_API_KEY" \  -H "Content-Type: application/json" \  -d '{"data":[{"html":"<h1>Hello</h1><p>World</p>"}],"return_format":"markdown"}'
```

```
from spider import Spider client = Spider() result = client.transform(    [{"html": "<h1>Hello</h1><p>World</p>"}],    {"return_format": "markdown"},) print(result["content"][0])
```

```
import { Spider } from "@spider-cloud/spider-client"; const client = new Spider(); const result = await client.transform(  [{ html: "<h1>Hello</h1><p>World</p>" }],  { return_format: "markdown" },); console.log(result.content[0]);
```

- data

  - array
  - required
  - The documents, one object each. Each holds `html`, and may hold the page `url` and a `lang`. A body can be up to 10 MB, with no limit on how many documents it holds.

- return_format

  - string
  - raw
  - One of `markdown`, `commonmark`, `text`, `xml` or `raw`. One format per request.

- readability

  - boolean
  - false
  - Runs reader-mode extraction first, so only the main content is converted.

- clean

  - boolean
  - false
  - Removes scripts, styles, SVG, iframes, canvas, video, comments, hidden elements, inline `data:` images and elements marked as ads or tracking. It leaves nav and footer in place.

Sending `url` changed nothing in the recording. The markdown run without it came back with the same 4,170 byte body, and links stayed as the page wrote them.

## What a conversion costs

$0.0001 per document returned.

- The rate

  Each document that comes back in content is billed at $0.0001, the Transform row of the rate card. That makes $0.10 per 1,000 documents. Pay as you go, with no subscription.

- Getting the HTML

  Transform reads only the HTML you send. Getting a page from the web is a /scrape call, billed on its own, or a fetch of your own.

## When your own library is enough

- A fragment you control

  Short, clean HTML you wrote yourself converts fine with a library such as turndown, in your own process, at no cost per call.

- Whole pages from the web

  Pages like the one above carry headers, breadcrumbs, scripts and icon markup. Transform drops the scripts and styles, readability cuts a page to its main content, and one request carries many documents.

- Check the output on your pages

  The recorded markdown keeps relative links and lines that hold only `**`. Run a few of your own pages and decide whether you need a cleanup step after it.

## Common questions

What formats can transform return?

Set return_format to markdown, commonmark, text, xml or raw. Raw is the default. A request takes one format, and every document in it comes back in that format.

Does transform fetch the page?

No. It converts the HTML in the request and fetches nothing. To start from a URL, call /scrape, which returns markdown itself, or fetch the HTML yourself and send it here.

What does readability do?

It runs reader-mode extraction before the conversion, so only the main content is kept. In the run recorded on November 19, 2026, it kept the title, the h1 and the description of a product page and dropped the price and the product table. The markdown was 1,471 bytes with it and 4,073 without.

Does sending the page URL change the output?

Not in the recording. The markdown run with url and the same run without it returned the same 4,073 bytes of markdown, and links stayed relative, as the page wrote them.

How much HTML can one request carry?

Up to 10 MB of request body, with any number of documents in data. A document with empty HTML is skipped, so content can hold fewer strings than data has documents.

How much does transform cost?

$0.0001 per document returned, from the rate card on the pricing page. That makes $0.10 per 1,000 documents. Pay as you go, with no subscription.

### Keep reading

[Scrape API](https://spider.cloud/api/scrape/)

[Send a URL instead, and get the page back as markdown, HTML or text.](https://spider.cloud/api/scrape/)

[Crawl API](https://spider.cloud/api/crawl/)

[Follow a site's links from one URL and get each page's content.](https://spider.cloud/api/crawl/)

[Transform API reference](https://spider.cloud/docs/api/transform/)

[The request and the response for POST /transform.](https://spider.cloud/docs/api/transform/)

## Convert one page of your own

Pay as you go, $0.0001 per document, with no subscription.

[Get an API key](https://spider.cloud/register/)
