Web service reference

The HTTP service is a FastAPI application. Start it with the server command, as described in the Command line reference. The service needs the server extra: install collective.html2blocks[server]. The interactive API documentation is available at /docs.

Every response includes the X-Process-Time header, which holds the processing time in seconds.

Endpoints

Method	Path	Request body	Response
GET	/	None	An object with the title, description and version keys.
GET	/ok	None	{"status": "up"}
POST	/html	html and converter	A list of blocks.
POST	/markdown	markdown and converter	A list of blocks.
POST	/volto	html, format, default_blocks and additional_blocks	An object with the blocks and blocks_layout keys.

POST /html

Convert HTML to a list of blocks.

Field	Type	Required	Default	Description
html	string	Yes	None	The HTML to convert.
converter	string	No	"slate"	The converter to use. Only "slate" is accepted.

If converter has any other value, the service responds with status 400.

POST /markdown

Convert Markdown to a list of blocks.

Field	Type	Required	Default	Description
markdown	string	Yes	None	The Markdown to convert.
converter	string	No	"slate"	The converter to use. Only "slate" is accepted.

If converter has any other value, the service responds with status 400.

POST /volto

Convert HTML or Markdown to the structure that Volto uses for a content item.

Field	Type	Required	Default	Description
html	string	Yes	None	The HTML or Markdown to convert. The field has this name for both formats.
format	string	No	"html"	The format of html, either "html" or "markdown".
default_blocks	list of objects	No	null	Blocks to place before the converted blocks.
additional_blocks	list of objects	No	null	Blocks to place after the converted blocks.

If format has any other value, the service responds with status 422, the validation error status of FastAPI.

Example

Request:

{"html": "# Hello", "format": "markdown"}

The response has the blocks and blocks_layout keys. The block identifiers are random UUIDs.