API Documentation

ClawHub Skill for OpenClaw Agents#

The EnConvert skill is published on ClawHub, the skill registry for OpenClaw agents. Installing it gives an agent six operations: read a URL into markdown, search the web, list a site's URLs, extract typed fields from pages, and convert a file to markdown or to PDF. Every page read carries a render_quality score from 0.0 to 1.0, so a bot wall or an empty single-page-app shell arrives flagged instead of being passed along as if it were the page.

Install: openclaw skills install @enconvert/enconvert · Listing: clawhub.ai/enconvert/skills/enconvert · Version: 0.0.1 · Source: enconvert/clawhub-enconvert

What a ClawHub skill is#

A ClawHub skill is a single markdown instruction file. The agent reads it and executes the calls itself with curl. That is the whole mechanism.

This matters more than it sounds. The six operations below are not registered tool schemas. Nothing appears in a tool list, no argument object is validated before a call goes out, and there is no SDK sitting between the agent and the API. The skill tells the agent which endpoint to hit, which header to send and what the response looks like; the agent composes the HTTP request. Call them operations, not tools, and the behaviour you observe will make sense: an agent that has not read the file will not call anything, and an agent that has read it can deviate from it.

The practical upside is that nothing needs installing beyond curl, and the same instructions work on any platform that can run a shell command.

The six operations#

Operation Endpoint What comes back
Perceive URL POST /v2/perceive render_quality, plus an outputs object of 15-minute signed URLs
Web Search POST /v2/lookup results[] with title, url, snippet, position
Discover URLs POST /v2/discover urls[] and total, with no page rendered
Extract Structured POST /v2/distill results[], one entry per URL, each with data and extraction_tier
Convert File to Markdown POST /v1/convert/anything-to-markdown JSON carrying presigned_url
Convert File to PDF POST /v1/convert/anything-to-pdf JSON carrying presigned_url

Every call sends the header X-API-Key, never Authorization: Bearer. All six run against the same REST API documented across this site, so your plan quota and rate limits apply exactly as they do everywhere else.

Web search is POST /v2/lookup. The V2 namespace has no endpoint named after the word "search"; a request to one returns 404. If an agent reaches for that path, the skill file it read was out of date.

Install#

Install it with the OpenClaw CLI:

openclaw skills install @enconvert/enconvert

That is the form the ClawHub listing renders. Add --global to install it for every project rather than the current one, and openclaw skills update --all later to pick up new versions.

The ClawHub CLI installs the same skill, if that is the tool you already have:

npm i -g clawhub
clawhub install @enconvert/enconvert

The npm package clawhub is the CLI. There is an unrelated package of the same name on PyPI whose releases are all yanked, so pip install clawhub is not a route to this CLI.

Give the skill your API key#

The skill reads one secret: ENCONVERT_API_KEY.

  1. Generate a private API key in the dashboard. Private keys start with sk_.
  2. Make it available to the agent, either as ENCONVERT_API_KEY in the environment the agent runs in, or injected for this skill through your OpenClaw config. The skills configuration reference covers the per-skill env block.
  3. Confirm the key works before asking the agent to do anything:
curl -sS https://api.enconvert.com/v1/whoami -H "X-API-Key: $ENCONVERT_API_KEY"
# {"project_id":"2","plan_slug":"free"}

A public pk_ key is rejected here with a 403. Public keys exist for browser widgets and no operation in this skill accepts one. See Private Keys.

Without the key, the skill silently never loads. OpenClaw filters skills at load time against the requirements declared in the file: this one needs the ENCONVERT_API_KEY env var and the curl binary on PATH. If either is missing the skill is simply ineligible, and there is no error message to read. The symptom is an agent that answers as though it had never heard of EnConvert. Check curl --version and the whoami call above before debugging anything else.

What comes back from a page read#

The response shape of POST /v2/perceive is the single thing most worth understanding before an agent runs it:

curl -sS -X POST https://api.enconvert.com/v2/perceive \
  -H "X-API-Key: $ENCONVERT_API_KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","outputs":["markdown"],"only_main_content":true}'

Three rules govern the reply:

  • render_quality comes first. It is a number from 0.0 to 1.0 in a 200 response, not an HTTP error. A low score means the render is degraded, so treat the content as suspect rather than authoritative.
  • Every artifact under outputs is a 15-minute signed URL, markdown included. outputs.markdown.url is a link, not the text of the page. So are html_cleaned, html_raw, screenshot, screenshot_full_page, pdf, links and images. Fetch each with a plain GET and no X-API-Key header: the signature in the URL is the authentication, and attaching your key would hand it to the storage host for nothing. More in Signed URLs.
  • structured is the exception. It comes back inline at the top level of the response, not under outputs.

An agent that expects inline markdown reads an object where it wanted text, and reports the page as empty. Two steps, not one:

MD=$(curl -sS -X POST https://api.enconvert.com/v2/perceive \
  -H "X-API-Key: $ENCONVERT_API_KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","outputs":["markdown"]}' \
  | grep -o '"url":"[^"]*"' | head -n1 | cut -d'"' -f4)
curl -sS "$MD"   # no key here

File conversion works the same way at the end: the JSON carries presigned_url, and you fetch that with a plain GET and no key.

Converting a file#

Both convert endpoints take multipart/form-data with a single field named file. Do not set Content-Type by hand; the multipart boundary sets it.

curl -sS -X POST https://api.enconvert.com/v1/convert/anything-to-markdown \
  -H "X-API-Key: $ENCONVERT_API_KEY" -F "[email protected]"

The filename extension decides the input format. This is the flow's sharpest edge on an agent platform, where the input is usually a URL rather than a local path: download the source first with no X-API-Key header (it is a third-party host), keep the original filename, then post the bytes. A name the API cannot read is repaired from the bytes when the format carries a signature (a PDF, an image or a DOCX survives it), but a text format has none, so markdown saved as notes.lJzoMq6Akq comes back as 400 Invalid file format '.ljzomq6akq' for anything-to-markdown. The scripts/convert.sh helper bundled with the skill does the whole download-post-fetch sequence correctly.

Troubleshooting#

The agent never mentions EnConvert. The skill did not load. Either ENCONVERT_API_KEY is not visible to the agent process or curl is not on PATH. Load-time filtering is silent by design, so there is nothing in the logs to find.

401 or 403 on every call. The key is missing, wrong, or a public pk_ key. Run the whoami call above; it fails in exactly the same way and tells you in one line.

A 404 from web search. The agent guessed an endpoint named after the word "search". No such path exists. Web search is POST /v2/lookup.

400 Invalid file format. The uploaded file had no usable extension and no signature in its bytes to recover one from, which is every text format: CSV, HTML, Markdown, plain text. Keep the source filename, or rename the download to one with the right suffix.

The page comes back empty, or as [object Object]. outputs.markdown is a signed URL. Fetch it. Only structured arrives inline.

A download link stopped working. Signed URLs last 15 minutes. Run the operation again rather than trying to refresh the link.

For a coding agent that supports the Model Context Protocol instead, MCP Setup exposes the same operations as real registered tools.

Frequently asked questions#

How do I install the EnConvert skill in OpenClaw?#

Run openclaw skills install @enconvert/enconvert. That is the command the ClawHub listing shows. The ClawHub CLI installs the same skill with clawhub install @enconvert/enconvert after npm i -g clawhub. Then set ENCONVERT_API_KEY to a private sk_ key from your dashboard, because the skill will not load without it.

How do I make an OpenClaw agent read a web page as markdown?#

Ask it for the page once the skill is installed. It calls POST /v2/perceive with outputs: ["markdown"], then fetches outputs.markdown.url with a plain GET and no key. Markdown is roughly six times smaller than the raw HTML of the same page, which cuts the token cost of everything the agent does with it afterwards.

Why does the skill do nothing at all?#

OpenClaw filters skills at load time against their declared requirements. This one declares the ENCONVERT_API_KEY env var and the curl binary. If either is absent the skill is excluded before the agent ever sees it, with no error message. That is the cause almost every time.

Is the skill a registered tool the agent can call?#

No. It is a markdown instruction file the agent reads and acts on with curl. There is no tool schema and no argument validation, which is why the skill file spells out each endpoint, header and response shape. Nothing else needs installing.

Can I use a public pk_ key?#

No. Public keys are for browser widgets and every operation here rejects them with a 403. Use a private key that starts with sk_, generated in Dashboard, API keys.

How does the agent know a page failed to render?#

Every perceive response carries render_quality, a number from 0.0 to 1.0 inside a normal 200. A challenge page, a cookie wall or a script that never settled scores low. The skill instructs the agent to read that score first and surface a degraded read rather than presenting it as reliable.

← MCP Setup Dify →