API documentation

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

Last reviewed: 21 June 2026. Source-of-truth exports: Markdown, OpenAPI, LLM reference.

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.

When to use the API

Use the BinHTML API when a script, CI job, internal tool, or deterministic automation already knows what HTML it needs to publish.

Use a website deployment platform instead when the generated output should become a public website, needs a custom domain, or requires server-side routes, databases, authentication, or environment variables.

If you are still deciding whether the output is an artifact, a report, or a deployed site, start with the complete guide to publishing AI-generated HTML.

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. You can also create one unlisted project link for the grouped artifacts.

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 always unlisted and noindex, and the project page only lists active unlisted artifacts from that project. Builder links use short retention; Pro unlocks permanent links and higher limits.

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
  • Up to 3 days artifact retention
  • Unlisted share links
  • 10 per minute publish rate
  • 10 active project links

Pro

  • 50 MB max HTML file size
  • Permanent or custom expiry
  • Unlisted and private share links
  • 60 per minute publish rate
  • 500 active project links

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. Builder project links are short-lived; Pro links can be permanent.

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.