# Clankerweb for Agents

Clankerweb is a static site publishing service designed for both humans and AI agents.

Its main agent-facing value is simple:

- an agent can take a folder of static files
- confirm the root contains index.html
- send one upload request
- get a live URL back immediately

This makes Clankerweb one of the simplest ways for an agent to publish a website without building a custom deploy pipeline.

## Audience

- people using coding agents such as Codex-style assistants
- developers who want a reusable publish skill for static sites
- teams that want an agent-friendly deploy API with minimal setup

## Main documents

- /SKILL.md
- /llms.txt
- https://app.clankerweb.com/agent/connect

## Authentication modes

Clankerweb supports two publish modes.

### 1. API key publishing

Use this when:

- the user wants a permanent site
- the user wants to update an existing site
- the user wants a custom slug or domain under the configured base domain

The request uses:

- Authorization: Bearer <apiKey>

If the user does not already have an API key, send them to:

- https://app.clankerweb.com/agent/connect

They should sign in, create an upload key, copy the one-time token, and paste it back into the agent chat.

### 2. Temporary email publishing

Use this when:

- the user wants the fastest first publish
- the user has no API key yet
- a generated temporary URL is acceptable

The request uses:

- X-Email: <userEmail>

Important behavior:

- domain is ignored when X-Email is used
- the system generates the slug and live URL
- the service emails a claim link to the user
- the site stays live for 1 hour unless the user claims it from email

If the user wants a custom domain or a replacement deployment, do not use this flow. Use the API key flow instead.

## File structure requirements

For HTML sites, publish the directory whose root contains index.html.

Example:

my-site/
  index.html
  styles.css
  script.js

Publish my-site/, not the parent directory containing it.

## Primary API workflows

### Publish a new authenticated site

- method: POST
- endpoint: https://app.clankerweb.com/upload
- auth: Authorization: Bearer <apiKey>

The response includes:

- data.link.subdomain
- data.link.url
- data.deployment.status
- liveUrl

### Publish a temporary site by email

- method: POST
- endpoint: https://app.clankerweb.com/upload
- auth: X-Email: <userEmail>

The response includes:

- data.link.subdomain
- data.link.url
- data.deployment.status
- liveUrl
- temporary.email
- temporary.expiresAt
- temporary.message

### Replace an existing site

- method: PUT
- endpoint: https://app.clankerweb.com/upload
- auth: Authorization: Bearer <apiKey>
- include the existing domain field

### Inspect existing sites

- method: GET
- endpoint: https://app.clankerweb.com/profile
- auth: Authorization: Bearer <apiKey>

## Recommended agent workflow

1. Resolve the folder or file the user wants published.
2. Confirm the publish root contains index.html for HTML sites.
3. Check whether CLANKERWEB_API_KEY is available.
4. Decide the publish mode.
5. If the user needs a permanent site, custom domain, or update flow, use the API key mode.
6. If the user does not have an API key and accepts a generated temporary URL, use the X-Email mode.
7. For a new permanent site, call POST /upload.
8. For replacing a site, call GET /profile if needed, then PUT /upload.
9. Return the liveUrl to the user.
10. Mention whether the deployment status is READY.

## Why this is easy for agents

- one-step upload flow
- no need to teach the agent a provider-specific deployment pipeline
- same service handles new sites and updates
- the agent can return a live URL in the same task
- the temporary email mode removes the initial API-key setup blocker

## Human-facing page

The main human landing page is:

- /index.html

This page contains install instructions, prompt examples, and direct links to the skill file.