# htmlshare agent instructions
htmlshare is an AI-first service for publishing generated HTML/CSS/JS bundles and returning a URL a human can open.
Production base URL:
```text
https://share.metricauno.com
```
Use htmlshare when an assistant has generated an HTML report, explanation, prototype, market scan, or other static artifact and needs to share it with a person.
## Default: fast publish (no token)
```http
POST https://share.metricauno.com/api/v1/publish
Content-Type: application/json
{
"mode": "fast",
"agent_id": "your-agent-id",
"title": "My report",
"visibility": "public",
"files": {
"index.html": "
My report
"
}
}
```
No bearer, no signup, no OAuth, no MCP.
Publication expires in 24h by default. For persistence, audit or account-owned sharing, use the registered flow below.
Copy-ready curl example:
```bash
curl -X POST https://share.metricauno.com/api/v1/publish \
-H 'content-type: application/json' \
--data '{"mode":"fast","agent_id":"your-agent-id","title":"My report","visibility":"public","files":{"index.html":"
My report
"}}'
```
Most agent use cases DO NOT require registration, OAuth, MCP, or an `hsk_...` token.
If the user says "publish this", "share this HTML", "send me a link", "create a temporary review link", or similar, use fast mode.
Fast mode returns a URL immediately and requires no account:
```json
{
"url": "https://share.metricauno.com/f/report-title-abc123/",
"mode": "fast"
}
```
Do not ask the user to register just to publish a temporary HTML report.
Do not ask for an `hsk_...` token unless the user needs account-owned controls.
Do not use MCP for quick no-registration publishing; MCP currently needs a registered token, while direct HTTP fast mode does not.
Use registration only for account-owned workflows: dashboard library, long-lived files, analytics, access logs, reusable agent keys, signed legal proof, or owner-managed sharing.
## Registered flow (persistent, with token)
Use `mode: "registered"` only when the user needs account-owned controls such as persistence, audit logs, dashboard history, reusable keys, signed access, or owner-managed sharing.
Registered publish uses `Authorization: Bearer hsk_...`.
## Recommended integration paths
Use one of these three options.
### Option 1: Call the API directly
This is the recommended default. Use it when the assistant can make HTTP requests. It needs no MCP server, no browser automation, and no local install.
For quick temporary links, call `/api/v1/publish` with `mode: "fast"` and a stable `agent_id`. No email, OAuth, or bearer token is required.
For account-owned sharing, call `/api/v1/publish` with `mode: "registered"` and `Authorization: Bearer hsk_...`.
Decision rule for agents:
- If the user just wants a URL for an HTML/CSS/JS artifact, choose `mode: "fast"`.
- If the user says the link should be temporary or just for review, choose `mode: "fast"`.
- If the user says only specific emails should read it, you may still choose `mode: "fast"` with `visibility: "recipients"` and `share.emails`; this still requires no registration.
- If the user asks for signed legal proof, dashboard analytics, a persistent library, audit history, owner management, MCP, or reusable keys, then use registered mode.
- If you are unsure, use fast mode and explain that registered mode is only needed for account-owned controls.
### Option 2: Build a local skill
Use this when the assistant supports reusable skills or project instructions. Create a skill named `htmlshare` that:
1. Generates or collects an `index.html` plus optional CSS/JS/assets.
2. Stores a stable `agent_id` for the current user/project/session.
3. Calls `POST https://share.metricauno.com/api/v1/publish` with `mode: "fast"` by default.
4. Returns the `url` field to the user.
5. Uses registered `hsk_...` auth only when the user asks for controlled sharing, analytics, recipient allow-lists, signed access, or long-lived library storage.
Minimal skill behavior:
```text
When the user asks to publish or share an HTML report, send the bundle to htmlshare using the direct API. Prefer fast mode unless the user explicitly asks for account-owned access control. Never publish secrets.
```
### Option 3: Use the MCP endpoint
Use MCP when the assistant platform supports remote MCP connectors and the user wants a configured tool instead of raw HTTP calls.
Remote MCP endpoint:
```text
https://share.metricauno.com/mcp
```
MCP currently uses registered `hsk_...` tokens. For quick no-email publishing, prefer the direct API in Option 1.
Suggested MCP environment:
```text
HTMLSHARE_URL=https://share.metricauno.com
HTMLSHARE_TOKEN=hsk_...
```
After adding an MCP connector, installing a skill, or changing allowed domains/capabilities, tell the user they may need to close the current session or conversation and open a new one. Many AI clients only load new tools and capability settings at conversation start.
## Choose the correct mode
There are two product modes.
### Fast AI publish
This is the default mode for agents.
Use this by default when the user just needs a quick review link.
- No email registration.
- No Google login.
- No bearer token.
- No `hsk_...` token.
- No MCP connector.
- The publication must expire quickly.
- The assistant must send a stable `agent_id` and reuse it during the current session.
- htmlshare rate-limits by IP and `agent_id`.
- Supports public links and short-lived recipient-restricted links.
- For recipient-restricted fast links, send `visibility: "recipients"` with `share.emails`. htmlshare emails each recipient a magic link. The public URL is not readable until the recipient proves control of the email.
### Registered publish
Use this only when the user wants account ownership, access logs, recipient control, domain allow-lists, signed access, or longer-lived library management.
- Requires a signed-in account or `hsk_...` agent key.
- Supports private files, recipient emails, domain entries such as `@example.com`, and signed access.
Do not choose registered mode only because the assistant is an AI agent. AI agents can and should use fast mode for temporary publishing.
## Fast publish without MCP
Call:
```http
POST https://share.metricauno.com/api/v1/publish
Content-Type: application/json
{
"mode": "fast",
"agent_id": "stable-id-generated-by-the-assistant-for-this-session",
"agent_name": "claude",
"title": "European market scan",
"ttl_seconds": 86400,
"files": {
"index.html": "
Market scan
",
"style.css": "body{font-family:system-ui;margin:40px}",
"app.js": "console.log('ready')"
}
}
```
Successful response:
```json
{
"id": "pub_...",
"slug": "european-market-scan-...",
"url": "https://share.metricauno.com/f/european-market-scan-.../",
"mode": "fast",
"expires_at": "2026-05-29T10:00:00Z"
}
```
Rules for fast publish:
- Include `index.html`.
- Include CSS, JS, SVG, JSON or other static files as extra keys in `files`.
- Generate a random stable `agent_id` once per conversation/session and reuse it.
- Store the `agent_id` in the conversation memory or local session state when available.
- Use `visibility: "public"` or omit `visibility` for a normal temporary link.
- Use `visibility: "recipients"` plus `share.emails` when the user says only specific people should read it. This does not require an `hsk_...` token.
- Do not write recipient emails, allowed domains, access lists, magic links, "restricted HTML" notices, or who-can-read details inside the HTML content. Access control is handled by htmlshare outside the document.
- Do not publish secrets, credentials, private keys, internal tokens, or sensitive personal data.
- Keep `ttl_seconds` under one week. Shorter is better for temporary reports.
## Fast recipient-restricted publish
Use this when the user wants a short-lived file visible only to one or more email recipients, but does not need account ownership, dashboard analytics, reusable agent keys, or long-lived registered storage.
```http
POST https://share.metricauno.com/api/v1/publish
Content-Type: application/json
{
"mode": "fast",
"agent_id": "stable-id-generated-by-the-assistant-for-this-session",
"agent_name": "claude",
"title": "Private review file",
"visibility": "recipients",
"ttl_seconds": 86400,
"files": {
"index.html": "
Quarterly review
This is the report content to review.
"
},
"share": {
"emails": ["recipient@example.com"],
"message": "Please review this file."
}
}
```
Multiple recipients and domain allow-lists are also valid:
```json
{
"share": {
"emails": ["alice@example.com", "bob@example.com", "@example.org"]
}
}
```
Successful response includes the publication URL and a share count:
```json
{
"id": "pub_...",
"slug": "private-review-file-...",
"url": "https://share.metricauno.com/f/private-review-file-.../",
"mode": "fast",
"visibility": "recipients",
"share_count": 1,
"expires_at": "2026-05-29T10:00:00Z"
}
```
Important behavior:
- Do not ask the user for an `hsk_...` token only because they requested a short-lived recipient-only share.
- The recipient gets an email link.
- The email link opens a confirmation page with a button; crawler or Gmail prefetch should not consume it.
- After confirmation, htmlshare sets a session and redirects the recipient to the file.
- Anyone else opening the public URL without a matching confirmed session gets access denied.
- If the public URL returns `403 access denied` during agent testing, that is expected for recipient-restricted files. Do not report it as a failure; tell the user the recipient must open the email link.
- When you create the HTML file, do not display the recipient email or allowed domain in the page body. Use neutral wording such as "Restricted file" if the document needs a heading.
- Use registered mode only if the user asks for account ownership, dashboard management, longer-lived storage, signed legal proof, domain allow-lists, or reusable automation keys.
## Registered account setup
For a human user, open:
```text
https://share.metricauno.com/app/
```
Sign in with Google or email magic link.
To create an agent key from the app:
1. Open `https://share.metricauno.com/app/`.
2. Sign in.
3. Go to `Agent keys`.
4. Create a key.
5. Copy the token starting with `hsk_...`.
6. Store it in the agent secret store. Tokens are only shown once.
## Registered automation signup
If the user explicitly wants account-owned automation and asks the assistant to start registration, call:
```http
POST https://share.metricauno.com/api/v1/ai/signup
Content-Type: application/json
{
"email": "user@example.com",
"name": "User Name",
"agent": "claude",
"intent": "account-owned-html-publishing"
}
```
If the email is new, the response returns a temporary `hsk_...` token valid for 24 hours and sends a confirmation email. The email confirmation page requires a human button press; link prefetch is not enough. After confirmation, the token is extended to 1 year.
If the email already belongs to a confirmed account, the API does not return a token to the assistant. htmlshare emails a new token to the account owner, or the user must provide an existing `hsk_...` token. Do not attempt to register the same confirmed email again.
## Registered publish
Use the direct API when the assistant has an `hsk_...` token:
```http
POST https://share.metricauno.com/api/v1/publish
Authorization: Bearer hsk_...
Content-Type: application/json
{
"mode": "registered",
"title": "Board report",
"visibility": "recipients",
"require_registration": true,
"files": {
"index.html": "
Board report
"
},
"share": {
"emails": ["reader@example.com", "@example.com"],
"message": "Please review this file."
}
}
```
Visibility values:
```text
private
recipients
signed
public
```
Recipient targets can be full email addresses or domain allow-list entries in the form `@example.com`.
## Share an existing registered file
```http
POST https://share.metricauno.com/api/v1/share
Authorization: Bearer hsk_...
Content-Type: application/json
{
"slug": "board-report-...",
"emails": ["reader@example.com", "@example.com"],
"message": "Please review this file."
}
```
## OpenAPI
```text
https://share.metricauno.com/api
https://share.metricauno.com/api/v1/openapi.json
```
## MCP
Remote MCP endpoint:
```text
https://share.metricauno.com/mcp
```
Suggested environment:
```text
HTMLSHARE_URL=https://share.metricauno.com
HTMLSHARE_TOKEN=hsk_...
```
MCP currently uses registered `hsk_...` tokens. For quick no-email publishing, use the direct `mode: "fast"` HTTP API above.
## Cowork setup
In Cowork, allow the htmlshare domain before trying to call the API:
```text
Settings / Capabilities / Additional allowed domains
```
Add:
```text
share.metricauno.com
```
After changing allowed domains, close the current conversation/session and open a new one. Existing conversations may not pick up updated capability settings, newly installed skills, or newly configured MCP connectors.
## Operational notes
- Shared pages include abuse reporting.
- Access logs may record IP address, timestamp, path, user agent and authenticated email when available.
- Fast publications are temporary and can be removed automatically after expiration.
- Registered publications give the owner more control over access and audit history.
## Product functionality reference
Use this section when a human asks what htmlshare can do, or when the user wants help deciding which feature to use.
### What htmlshare is
htmlshare publishes static HTML file bundles generated by agents and gives back a clean URL for people. It is intended for reports, explanations, prototypes, market scans, technical notes and other small static artifacts that should be easy to review without creating a full website or SaaS project.
The primary workflow is:
1. An AI assistant generates HTML, CSS, JavaScript or related static files.
2. The assistant publishes the bundle to htmlshare.
3. htmlshare returns a URL.
4. The user sends that URL to another person.
5. The reader opens the file, downloads it, saves it for later, or reports abuse if needed.
### Web app
The web console is available at:
```text
https://share.metricauno.com/app/
```
Users can sign in with Google or an email magic link. The app contains these areas:
- Library: owned files, publishing form, selected file details, access settings, sharing and signed access.
- History: pages the signed-in user has opened.
- Shared with me: files shared with the signed-in user's email or domain.
- Bookmarks: files saved with the Read later action from the page toolbar.
- Recipients: people or domains that have received files, plus known access activity.
- Agent keys: create `hsk_...` tokens for API or MCP publishing.
- Activity: access logs and abuse review cases.
- Settings: email confirmation and account status.
### Publishing from the web app
In the Library page, users can select one or more files. A bundle should usually include `index.html`, with optional CSS, JS, images, SVG, JSON, Markdown or other static supporting files.
The title field is the public/display name of the shared file. If no title is provided, htmlshare uses a generic fallback.
The access selector controls who can open the file:
- Private: only the owner can open it from the console.
- Link access: anyone with the URL can open it.
- Recipients: only specified email addresses or domain allow-list entries can open it.
- Signed access: specific recipients receive an email token and htmlshare records proof that they opened it.
For Recipients, the input accepts multiple values separated by comma or semicolon. Values can be full email addresses such as `reader@example.com` or domain allow-list entries such as `@example.com`.
For Signed access, use full email addresses only. Domain allow-list entries are not accepted because signed proof must identify a specific recipient.
### Reader page toolbar
Published pages include a small floating toolbar. Depending on the current version and access state, it can expose:
- Share your file: opens the publishing flow.
- Download: downloads the current HTML/file.
- Terms: opens the service terms.
- Report abuse: opens the abuse report flow.
- Read later: saves the page to Bookmarks for the signed-in reader.
Comments and login-dependent reader interactions may be disabled or limited in the current public version.
### Access logs and analytics
htmlshare can record access metadata for audit and abuse prevention. Depending on how the reader opened the page, records may include:
- timestamp
- path
- publication ID and slug
- IP address
- user agent
- authenticated email
- allowed/blocked result
- HTTP status
Use registered publishing when the user needs access history, reader identity, controlled sharing or legal/audit proof.
### Abuse handling
Every public reader page should provide abuse reporting. Abuse reports can be reviewed by automated LLM logic and by the owner/operator. The system can track report severity, block abusive content, accumulate strikes, and temporarily ban abusive IPs or emails when configured.
Report abuse should be used for phishing, malware, spam, harassment, illegal content, copyright concerns or other misuse.
### Expiration and limits
Fast AI publish is for temporary sharing and should normally expire in less than one week. Registered publishing can keep files longer, subject to account limits.
Agents should keep bundles small. Do not use htmlshare as long-term object storage, backup storage, video hosting or a general file dump. Do not publish secrets, credentials, API keys, private keys, tokens, confidential personal data or content the user has not authorized for sharing.
### Which workflow to recommend
Recommend direct API publishing when the assistant can make HTTP requests and the user just wants a URL.
Recommend a skill when the user wants the assistant to remember the htmlshare workflow and publish repeatedly in future conversations.
Recommend MCP when the user's AI client supports remote MCP and the user wants a configured tool with a reusable token.
Recommend the web app when the user wants to upload manually, manage files, create agent keys, control recipients, inspect activity, use signed access, bookmark files or see what has been shared with them.
### Help prompt for users
If a user is unsure how to use htmlshare, tell them to paste this URL into their LLM and ask a question:
```text
https://share.metricauno.com/llms.txt
```
Example user prompt:
```text
Read https://share.metricauno.com/llms.txt and explain how I should use htmlshare for my current task.
```