API documentation

Publish generated HTML from scripts, agents, and automations. Each request returns a hosted BinHTML link plus dashboard and source download URLs.

Publish with your own API key

Sign up, open Settings, create an API key, then use the API or MCP endpoint from your tools.

Create key →

Quick start

Create an API key in your BinHTML settings, keep it in your local environment, then send a publish request.

  1. 1. Create a key
    Open Settings, then create an API key.
  2. 2. Publish HTML
    Send a complete HTML document to BinHTML.
  3. 3. Share the link
    Use the returned share URL anywhere.

Publish HTML

This endpoint creates a new BinHTML artifact and returns the links your tool or agent should hand back to the user.

POST https://binhtml.com/api/v1/artifacts

Send your API key with Authorization: Bearer. The x-binhtml-api-key header is also supported.

Publish request

Replace $BINHTML_API_KEY with a key from your settings.

curl -X POST https://binhtml.com/api/v1/artifacts \
  -H "Authorization: Bearer $BINHTML_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Agent report",
    "projectName": "Launch workspace",
    "visibility": "unlisted",
    "sourceHtml": "<!doctype html><html><body><h1>Report</h1></body></html>"
  }'

Projects

Add projectName when you want related outputs grouped together in the dashboard. Pro accounts can also create one unlisted project link.

title

string

description

string

projectName

Optional project name for grouping related artifacts.

sourceHtml

A complete HTML document including <!doctype html> or an <html> tag.

visibility

string

expiresAt

Optional future expiry timestamp.

Create a project link

Returns one unlisted link for the project index.

curl -X POST https://binhtml.com/api/v1/projects/share \
  -H "Authorization: Bearer $BINHTML_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "projectName": "Launch workspace"
  }'

View or disable a project link

Project links can be copied, checked, or revoked at any time.

curl https://binhtml.com/api/v1/projects/$PROJECT_ID/share \
  -H "Authorization: Bearer $BINHTML_API_KEY"

curl -X DELETE https://binhtml.com/api/v1/projects/$PROJECT_ID/share \
  -H "Authorization: Bearer $BINHTML_API_KEY"

Project links are a Pro feature. They are always unlisted and noindex, and the project page only lists active unlisted artifacts from that project.

Version updates

Use the artifact ID from a previous publish to replace the current HTML while keeping the same share link.

Version update request

The existing share URL stays the same.

curl -X POST https://binhtml.com/api/v1/artifacts/$ARTIFACT_ID/versions \
  -H "Authorization: Bearer $BINHTML_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Agent revision",
    "sourceHtml": "<!doctype html><html><body><h1>Updated report</h1></body></html>"
  }'

Plans and limits

BinHTML applies plan limits at publish time, whether the request comes from the dashboard, API, or MCP.

Builder

  • 10 MB max HTML file size
  • 3-day artifact retention
  • Unlisted share links
  • 10 publishes per hour

Pro

  • 50 MB max HTML file size
  • Permanent artifacts
  • Private links
  • Shareable project links
  • Higher publish limits

Responses

Successful requests return artifact metadata, version details, and the URLs needed for sharing or management.

Publish response

Agents usually return the share URL to the user.

{
  "artifact": {
    "id": "7d9f6c84-9c6b-4f8e-8d8a-3a8097a56a91",
    "slug": "agent-report-a1b2c3d4",
    "title": "Agent report",
    "visibility": "unlisted",
    "expiresAt": null,
    "createdAt": "2026-05-14T10:30:00.000Z",
    "project": {
      "id": "2e1a8d5a-2b73-4a9e-9d91-83ec19001b3a",
      "name": "Launch workspace",
      "slug": "launch-workspace"
    }
  },
  "version": {
    "number": 1,
    "sizeBytes": 72,
    "renderMode": "sandboxed-html"
  },
  "urls": {
    "share": "https://binhtml.com/a/agent-report-a1b2c3d4",
    "management": "https://binhtml.com/dashboard/artifacts/7d9f6c84-9c6b-4f8e-8d8a-3a8097a56a91",
    "sourceDownload": "https://binhtml.com/dashboard/artifacts/7d9f6c84-9c6b-4f8e-8d8a-3a8097a56a91/source"
  }
}

Error response

Failed requests include a readable message.

{
  "error": {
    "code": "invalid_request",
    "message": "sourceHtml must include <!doctype html> or an <html> tag."
  }
}

FAQ

Short answers for people using the API from agents, scripts, and automations.

How do I publish HTML from an agent?

Have the agent send a POST request to /api/v1/artifacts with a title, sourceHtml, and your BinHTML API key. The response includes the share URL it should give back to you.

Is an API key required?

Yes. API requests need a BinHTML API key so the artifact is saved to the right workspace and protected by your plan limits.

Can the API create project links?

Yes. Publish artifacts with the same projectName, then use the project share endpoint to create one unlisted project link. Project share links are a Pro feature.

What limits apply?

Plan limits apply at publish time, including file size, retention, visibility options, and publish-rate limits.

Why are artifact and project pages noindex?

BinHTML share pages are intended for direct links. The noindex setting keeps generated artifacts and project indexes out of search results by default.

Rendering and source access

Published HTML is rendered in a sandboxed viewer. Source downloads remain available from the dashboard.

Shared HTML renders inside a sandboxed iframe.

The iframe does not receive same-origin access to BinHTML.

Dashboard source downloads require the signed-in owner.

External resources referenced by the HTML may still load from their own origins.