Run the web service

This guide shows you how to run the HTTP service and how to convert content through it. The request and response formats are listed in the Web service reference.

Run the service from a project

If you installed collective.html2blocks[server] in your project, start the service with the server command. The server extra provides the web framework and the server, so a plain collective.html2blocks install does not include it.

uv run html2blocks server --port 8090

The service listens on 127.0.0.1 by default. To accept connections from other machines, or from a container, pass --host 0.0.0.0.

uv run html2blocks server --host 0.0.0.0 --port 8090

To run the latest released version without installing the package in your project, use uvx. This command works only with released versions of the package.

uvx --from "collective.html2blocks[server]" html2blocks server --port 8090

Run the container image

The official container image is ghcr.io/collective/html2blocks. The service listens on port 8000 inside the container, so map that port to a port on your machine.

docker run -p 8090:8000 ghcr.io/collective/html2blocks:latest

To run a specific release, replace latest with the version number, for example 1.0.0a1.

Convert content

Send HTML to the /html endpoint to get a list of blocks.

curl -X POST http://127.0.0.1:8090/html -H "Content-Type: application/json" -d '{"html": "<p>Hello</p>"}'

Send Markdown to the /markdown endpoint, using the markdown field.

curl -X POST http://127.0.0.1:8090/markdown -H "Content-Type: application/json" -d '{"markdown": "# Hello"}'

Send content to the /volto endpoint to get the full structure with blocks and blocks_layout. The field is always called html, even for Markdown. Set format to "markdown" when the content is Markdown.

curl -X POST http://127.0.0.1:8090/volto -H "Content-Type: application/json" -d '{"html": "# Hello", "format": "markdown"}'

Omit format, or set it to "html", when the content is HTML.

Check that the service is running

Request the health endpoint. It returns {"status": "up"} when the service is running.

curl http://127.0.0.1:8090/ok

The root endpoint, /, returns the service title, description and version. The interactive API documentation is available at /docs.