# ShareHammer API Reference

> Instant static web hosting for AI agents and humans.
> Base URL: https://api.sharehammer.com/api/v1

## Authentication

Anonymous requests create temporary nails (24h expiry).
Authenticated requests create permanent nails.

### Get an API key:
1. POST /auth/send-code {"email": "you@example.com"}
2. POST /auth/verify {"email": "you@example.com", "code": "123456", "grant": "api_key"}
   Returns: { api_key: "sh_live_..." }
3. Use header: Authorization: Bearer sh_live_...

## Endpoints

### Create Nail
POST /nails
Body: {"files": [{"path": "index.html", "size": 1024, "contentType": "text/html"}]}
Auth: Optional (anonymous = 24h expiry, authenticated = permanent)
Response: {
  "slug": "abc123",
  "url": "https://abc123.sharehammer.com",
  "upload": {
    "files": [{"path": "index.html", "uploadUrl": "https://...presigned-r2-url...", "contentType": "text/html"}]
  }
}

### Upload Files
PUT {uploadUrl} (from create response)
Headers: Content-Type: {contentType from create response}
Body: raw file bytes (binary supported natively — PUT the actual bytes, e.g. PNG/font data)

### Binary files via MCP / JSON
The MCP publish tools (publish_files / update_nail) take file content as a string. For binary assets
(PNG icons, fonts, etc.) set encoding:"base64" on the file and pass base64 content — a
"data:<type>;base64,…" data URI is also accepted and auto-detected. Without base64, content is stored
as UTF-8 text (correct for HTML/CSS/JS/SVG). The raw HTTP API above sidesteps this entirely: just PUT
the bytes to the presigned URL.

### JavaScript & PWAs
.js / .mjs files are served with a text/javascript content type, so <script type=module> and
navigator.serviceWorker.register('sw.js') work — static sites can be installable, offline-capable PWAs.
(When you open a .js URL directly in a browser tab it shows a syntax-highlighted source view; the same
URL loaded as a script/worker subresource serves the raw asset. Append ?raw to force raw bytes.)

### Finalize Nail
POST /nails/{slug}/finalize
Response: {"slug": "abc123", "url": "https://abc123.sharehammer.com", "status": "active", "expires_at": "..."}

### Update Nail (redeploy)
PUT /nails/{slug}
Auth: Required (Bearer token)
Body: {"files": [...]} (same format as create)
Response: same as create (with presigned URLs for changed files)
Then upload changed files and POST /nails/{slug}/finalize

### Update Metadata
PATCH /nails/{slug}
Auth: Required
Body: {"title": "My Nail", "description": "...", "og_image_url": "...", "embed_enabled": true}

## Embedding
Nails can be embedded in third-party pages, but embedding is OPT-IN per nail and OFF by default.
- Enable: PATCH /nails/{slug} with {"embed_enabled": true} (or set embed_enabled via the MCP update_nail_meta tool).
- Embed view: append ?embed=1 to the nail URL (e.g. https://{slug}.sharehammer.com/?embed=1) — renders the nail with chrome stripped. Add &chrome=full to keep the branded header.
- iframe: <iframe src="https://{slug}.sharehammer.com/?embed=1" width="640" height="480" frameborder="0" allowfullscreen></iframe>
- Auto-resize: the embed page posts {type:"sharehammer:embed:height",height} via postMessage; listen on the host to size the iframe. Helper script: https://sharehammer.com/_embed/resize.js
- oEmbed: GET https://sharehammer.com/oembed?url={nail-url}&format=json — returns rich oEmbed JSON. Returns 404 if the nail is not opted in, password-protected, expired, or missing.
- Password-protected nails are never embeddable/framable regardless of embed_enabled.

### List Nails
GET /nails
Auth: Required
Response: {"nails": [...], "pagination": {"next_cursor": "...", "has_more": true}}

### Get Nail
GET /nails/{slug}
Auth: Required
Response: nail details with file list

### Delete Nail
DELETE /nails/{slug}
Auth: Required

## File Requirements
- path: relative file path (e.g. "index.html", "css/style.css")
- size: file size in bytes (must match actual upload)
- contentType: MIME type (e.g. "text/html", "image/png", "text/javascript")

## Limits
- Anonymous: 5 requests/hour, 10MB total, 50 files, 24h expiry
- Authenticated: 60 requests/hour, 100MB total, 200 files, permanent

## Custom Domains
POST /domains {"hostname": "example.com"}
Auth: Required
Then CNAME example.com to proxy.sharehammer.com
POST /domains/{id}/links {"siteSlug": "abc123", "path": ""}

## Project Binding (.sharehammer.json)
Create a .sharehammer.json file in your project directory to bind it to a nail:
{"slug": "my-project-docs", "forge": "client-work"}
- The CLI reads this file on deploy and updates the existing nail instead of creating a new one
- After the first deploy, the CLI writes this file automatically
- AI agents (via MCP) should check for this file before deploying
- Slug resolution priority: --slug flag > .sharehammer.json > random generated slug

## Notes
- Nails are served at https://{slug}.sharehammer.com
- Presigned upload URLs expire in 15 minutes
- All file paths are relative (no leading slash)
- index.html at root is served for / requests
- Single HTML file uploads are auto-renamed to index.html by the dashboard
- ZIP files can be uploaded and extracted client-side in the dashboard