A Codex, Claude, or Cursor workflow generates a landing page and should return a URL in the same run.
HTML publishing guide
Publish HTML from an AI Agent: Return a Preview Link via API
An agent publishing workflow is useful when an AI tool, coding agent, or internal script already has the HTML and should return a browser preview in the same run without asking a person to upload the files manually. HTMLShare exposes separate endpoints for one HTML document and for a list of static project files.
Quick answer
Authenticate with a Bearer access token, POST the generated document to /api/skill/publish, or send a file list to /api/skill/publish-files. Include index.html for multi-file projects, keep the returned project URL with the run, and pass replace when a later iteration should update an existing project.
Real use cases
An internal report generator creates index.html, CSS, JavaScript, and image assets for stakeholder review.
A product team wants each revision to update one review project instead of creating an unrelated link every time.
Steps
1
Authenticate the publisher
Use the access token issued through the HTMLShare CLI or Skill authorization flow as an Authorization: Bearer header. Keep the token on the server or inside the tool runtime; do not place it in browser-side HTML.
2
Choose the endpoint that matches the artifact
Send a self-contained document to POST /api/skill/publish with name, sourceType: html, and html. For CSS, JavaScript, images, fonts, JSON, or multiple pages, use POST /api/skill/publish-files and send each file with a path plus content or contentBase64.
3
Validate and store the response
The successful response includes projectId, deploymentId, and url. Open the URL in a clean browser session, record it with the build or agent run, and return the link to the person who needs to review the output.
4
Replace only when the project identity is intentional
For a new revision of the same review artifact, pass the existing project identifier through replace. Use a new project when you need separate review history or want the old version to remain distinct.
Examples
Single HTML request
POST /api/skill/publish with { name: 'Pricing prototype', sourceType: 'html', html: '<!doctype html>…' }. The response gives the agent a browser URL it can return to the user.
Static project request
POST /api/skill/publish-files with files such as index.html, styles.css, app.js, and assets/logo.svg. Keep the paths relative to index.html so the published preview can load them.
Practical tips
- Install the HTMLShare Skill when the agent should publish and return the link as part of its workflow.
- Use one HTML document only when the page is genuinely self-contained.
- Use index.html at the project root for a file-list or ZIP-style static project.
- Pass a skill or client version when the publishing tool has a version to report.
- Treat the returned URL as a review link and move production traffic to production infrastructure.
Common mistakes
- Sending an HTML source folder to the single-document endpoint.
- Forgetting the Authorization: Bearer header or putting the access token in page JavaScript.
- Sending only index.html while the page references CSS, scripts, images, fonts, or JSON files.
- Using replace for unrelated artifacts and losing the separation between review rounds.
Best practices
- Keep the generated project sanitized; static files are not a substitute for access control.
- Open the response URL and check images, scripts, and responsive behavior before sending it onward.
- Handle unauthorized, missing_index_html, file_too_large, project_too_large, and unsupported_file_type errors as user-readable states.
- Log projectId and deploymentId so a later revision can be traced to the right artifact.
FAQ
What is the HTMLShare publish API?
It is an authenticated API for turning a static HTML document or a list of static project files into an HTMLShare preview project. The API returns a project URL when publishing succeeds.
Which endpoint should an AI agent use?
Use /api/skill/publish for one self-contained HTML document. Use /api/skill/publish-files when the generated artifact has multiple files or local assets.
Can an AI agent return the HTMLShare link in the same run?
Yes. After a successful Skill or API request, read the returned url, open it for a quick verification, and pass that preview link back to the user or review workflow.
Can the API host a server-rendered app?
No. The Skill API is for static HTML, CSS, JavaScript, and supported asset files. Use an application hosting workflow when the project needs server code, private environment variables, authentication, or a database.
How large can an upload be?
The current static publishing limits are 5 MB for a single HTML document and 20 MB for a multi-file project. Check the API response and keep generated artifacts below those limits.
Turn the HTML into a link
Use the Skill API when an AI tool or automation already owns the static output: authenticate with a Bearer token, choose the single-file or file-list endpoint, validate the returned URL, and use replace only for an intentional revision of the same project.