Stacktree API documentation

The publish primitive for agent-made HTML.

private by default MCP-native replace-in-place

Handing this to a coding agent? Give it the OpenAPI spec and go: api.stacktr.ee/openapi.json for the HTTP API, or agents.stacktr.ee/openapi.json for the pay-per-publish front-door. MCP server: https://api.stacktr.ee/mcp. Machine-readable index: stacktr.ee/llms.txt.

For a guided walkthrough with your actual API key inlined into snippets, open app.stacktr.ee/connect.

Connect an agent

Hand it to the agent

If you have an agent open, give it this and it does the rest — installs, verifies, and learns the tool surface:

Fetch and follow the setup instructions at https://stacktr.ee/prompt.md

Works in any agent that can fetch a URL. The instructions are plain Markdown at stacktr.ee/prompt.md — read them before you run them if you like.

npx stacktree-install — recommended

One command wires every agent at once — Claude Code, Cursor, Codex, OpenCode, Amp — and drops the stacktree-publish skill in for Claude:

npx stacktree-install

It signs you in via a one-time code at app.stacktr.ee/connect/cli and mints an API key automatically; pass an existing key as an argument (npx stacktree-install stk_live_…) to skip sign-in.

Claude.ai — custom connector

No CLI, no API key copy-paste.

1. Open claude.ai/settings/connectors → Add custom connector.
2. Paste https://api.stacktr.ee/mcp as the Remote MCP server URL.
3. Leave OAuth Client ID/Secret blank — Stacktree auto-registers via Dynamic Client Registration (RFC 7591).
4. Click Add → Claude.ai redirects you to Stacktree to sign in and approve. Tools are then available in any conversation.

Claude Code · Codex — CLI

One-line install. Identical syntax between the two:

claude mcp add stacktree -- npx -y stacktree-mcp
codex mcp add stacktree -- npx -y stacktree-mcp

Both expose the same 41 tools (see MCP server). Set STACKTREE_API_KEY in your shell — generate one at app.stacktr.ee/api-keys.

Prefer a skill? Installs SKILL.md + helper script into your agent's skills directory:

npx skills@latest add stevysmith/stacktree-skill
export STACKTREE_API_KEY=stk_live_...

Source: github.com/stevysmith/stacktree-skill · the whole collection at stacktr.ee/skills

MCP config file — Cursor / Claude Desktop / Windsurf / Zed

{
  "mcpServers": {
    "stacktree": {
      "command": "npx",
      "args": ["-y", "stacktree-mcp"],
      "env": { "STACKTREE_API_KEY": "stk_live_..." }
    }
  }
}

Drop into ~/.cursor/mcp.json, ~/Library/Application Support/Claude/claude_desktop_config.json, ~/.codeium/windsurf/mcp_config.json, or the context_servers key in Zed's settings.

Slack

Add the Slack app (one approval; installing mints the workspace its own free identity, no Stacktree account needed). Then ⋮ → Host on Stacktree on any message with an .html or .md file — channels or DMs — posts a private link back into the conversation. Re-uploading the same filename republishes to the same URL. /stacktree link migrates the workspace's sites into a dashboard account. Details: stacktr.ee/slack.

HTTP API

Auth

Three methods, all resolve to the same user context:

Upload a single HTML/markdown file or a zip. multipart/form-data. Anonymous uploads work — no auth header — and live 24 hours.

curl -F file=@page.html \
     -F password=hunter2 \
     -F expires_in_hours=72 \
     -H "Authorization: Bearer stk_live_..." \
     https://api.stacktr.ee/sites

{
  "id": "…",
  "url": "https://stacktr.ee/p/abc123…/",
  "visibility": "unlisted",
  "expires_at": 1781234567,
  "expires_at_iso": "2026-06-08T12:02:47Z",
  "ttl_seconds": 604800,
  "expiry_clamped": false,
  "expiry_ceiling_hours": 168,
  "expiry_source": "plan_ceiling",
  "file_count": 1,
  "size_bytes": 1234,
  "has_password": true,
  "agentation": false
}

Replace a site's files in place — the URL never changes, and no second page is created. Two body shapes: application/json with an html string, which is what the paid rails already speak, or multipart/form-data with the same fields as POST (the only shape that carries a zip, a PDF or e2e ciphertext). Three credentials, one per request: an account key or OAuth token; the page's own claim_token while it is unclaimed (Authorization: Claim <claim_token>, see below); or, on a wallet-paid page, a signed wallet challenge. Anything else is a 401. E2E-encrypted sites must be replaced with e2e=true multipart uploads (no silent downgrade to plaintext).

curl -X PUT https://api.stacktr.ee/sites/my-deck \
     -H "Authorization: Bearer stk_live_..." \
     -H "Content-Type: application/json" \
     -d '{"html":"<!doctype html><h1>v2</h1>"}'

The optional fields are the same either way: expected_updated_at (refuse the write if the page changed underneath you), pii_check, and on multipart e2e. On JSON, filename replaces a page published as a machine asset at its own path instead of relocating it to index.html.

Update settings without re-uploading files. JSON body.

curl -X PATCH \
     -H "Authorization: Bearer stk_live_..." \
     -H "Content-Type: application/json" \
     -d '{"agentation": true, "expires_in_hours": null}' \
     https://api.stacktr.ee/sites/my-deck

List · fetch · raw · delete · restore

Share tokens

POST   https://api.stacktr.ee/sites/:idOrSlug/share-tokens   { "label": "alice", "max_uses": 5, "expires_in_hours": 168 }
GET    https://api.stacktr.ee/sites/:idOrSlug/share-tokens
DELETE https://api.stacktr.ee/share-tokens/:tokenId

Returns a URL with ?t=… appended. Bypasses the password gate when valid; revocable per-token; optional max-use counter and expiry.

Feedback

GET    https://api.stacktr.ee/sites/:idOrSlug/feedback
POST   https://api.stacktr.ee/feedback/:id/resolve           { "note": "fixed the header spacing" }
DELETE https://api.stacktr.ee/feedback/:id

Viewer annotations left via the on-page Agentation toolbar (enable with agentation on upload or PATCH). Each item carries the comment plus the annotated element, selected text, intent, and severity. Unresolved first. The loop: read feedback → fix the page with update_site (same URL) → resolve.

Reactions & engagement

GET    https://api.stacktr.ee/sites/:idOrSlug/reactions      { counts, total, reactors, messages }
GET    https://api.stacktr.ee/sites/:idOrSlug/engagement     { sessions, median_active_seconds, avg_scroll, read_to_end_pct, buckets }

How a page landed, read by the owner. Reactions: turn on the on-page reaction bar per site (dashboard Settings) and viewers react with an emoji or leave a short private note, no account. Engagement (Studio and up): aggregate, non-PII read metrics: typical time on page, scroll depth, read-to-end rate, and a 10-bucket attention heatmap of dwell by page depth. No recording, no session replay. Both feed the dashboard activity bell and the optional daily email digest.

API keys

POST   https://api.stacktr.ee/api-keys      { "label": "claude desktop" }
GET    https://api.stacktr.ee/api-keys
DELETE https://api.stacktr.ee/api-keys/:id

Device code — get a key onto an agent with no browser

OAuth 2.0 Device Authorization Grant (RFC 8628). This is what npx stacktree-install runs, and it is callable directly by any agent: the agent prints a URL and a short code, a human approves it on their own device, and the agent polls until a key comes back. Use it when the account already belongs to a person — an agent that has no human to ask should buy its own key over x402 at POST https://api.stacktr.ee/provision instead.

POST https://api.stacktr.ee/api-keys/device-code        { "client_hint": "my-agent" }
  → { device_code, user_code, verification_url, verification_url_complete, interval, expires_in }

# print verification_url_complete for the human, then poll every "interval" seconds:
POST https://api.stacktr.ee/api-keys/device-code/poll   { "device_code": "…" }
  → { "status": "pending" }                     keep polling
  → { "status": "authorized", "api_key": "stk_live_…" }   store it; shown once
  → { "status": "denied" | "expired" }          stop

No authentication on either call. Codes live 10 minutes, the human's approval mints the key against their account, and the key is handed over exactly once — a poll that misses it means re-authorizing. Rate limited per IP. The resulting stk_live_ key works on the REST API and on MCP alike.

MCP server

Streamable HTTP MCP server at https://api.stacktr.ee/mcp (spec 2025-11-25), exposing 41 tools. Two credentials, both accepted on the same endpoint:

• Authorization: Bearer stk_live_… — an API key. No browser, no OAuth dance, nothing to register: the same key that drives the REST API drives MCP. This is the path for an unattended agent, and for any client that can only send a static header. An agent with no key at all can buy one over x402 at POST https://api.stacktr.ee/provision, or attach itself to a human's existing account with the device-code flow below.
• OAuth 2.1 + Dynamic Client Registration — for connectors acting on behalf of a signed-in human (claude.ai, Cursor, and friends). Nothing to pre-register; see OAuth.

Session cookies are deliberately NOT accepted here, so a browser cannot be made to drive MCP cross-site. Send exactly one credential.

curl -X POST https://api.stacktr.ee/mcp \
  -H "Authorization: Bearer stk_live_..." \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Tools (41)

Privacy-first MCP defaults

WebMCP (in-browser)

The dashboard registers the same verbs on document.modelContext where the browser supports it (Chrome origin trial), so an in-browser agent helping a signed-in human can call them without an API key. How and why.

Want the same pattern in your own app? The palette and WebMCP registration are built on agentk, our open-source cmdk extension: define tools once as JSON Schema, humans get generated forms, agents get the schemas.

Agent payments

An agent pays with no human and no account, two ways: per publish, or with a persistent key bought once. Pay-per-publish accepts x402 (USDC on Base or Solana) and MPP (USDC.e on Tempo at the front-door, the evm method on Base); the persistent key is x402 (USDC on Base or Solana) or MPP on Base. Gasless for the payer either way. Read the accepts array from the 402 rather than hardcoding a rail. Machine-readable version: x402.md.

Pay per publish (no key)

The simplest path, when there is no key and no human to make one. POST your HTML to api.stacktr.ee/publish or to the front-door at agents.stacktr.ee/api/publish, get a 402, pay $0.50 over x402 (USDC on Base or Solana) or MPP, and the page publishes to a private link with the URL in the response. No provisioning step. Read the accepts array from the 402 rather than hardcoding a rail: Base is always the first entry, and the requirement differs per network. Free revisions afterwards are keyless for an EVM payer (the wallet that paid signs for them) and claim-token based for a Solana payer. The endpoints are listed on x402scan and mppscan; specs at api.stacktr.ee/openapi.json and agents.stacktr.ee/openapi.json, with a free proof-of-service record at api.stacktr.ee/.well-known/x402-service.

Persistent key: provision once, then pay as you go

Paying above the price in a pay session (up to $20) leaves a prepaid balance on the key that later paid actions draw from silently. Balances never expire and are refundable on request.

Claim what an agent published

The wallet that pays at the front-door is recorded with each page, so it doubles as a claim ticket. A human can link that wallet from the dashboard (generate a code, the agent signs it), or the agent can self-link with the link_wallet MCP tool. Every page the wallet published then becomes owned and manageable.

Update with the page's own claim token (no key, any chain)

Every unclaimed page carries a claim_token, returned in its publish response. Until the page is claimed, that token is the page's update credential: PUT /sites/:id with Authorization: Claim <claim_token> and a JSON body {"html": "…"} (multipart works too). Same URL, free revisions, no account, no wallet and no signature, so it is the path for a Solana payer and for a free anonymous publish alike. It covers exactly that page's content: not claiming, not deletion, not settings, not any other page. Claiming rotates the token into the account and the header stops working; it is also refused once the page expires. Treat the token as being as sensitive as the page: whoever holds it can replace the content behind a link you already sent.

Keep an anonymous page: the keep link, or email

An anonymous page belongs to nobody until it is claimed, and most of them are published by an agent whose human never sees the response. Every anonymous publish response carries keep_url: hand it to the person you published for. It opens a page that says when the page stops working and offers both ways to keep it, with no sign-in needed to read it, and it marks that browser so the page itself shows them, and only them, a Keep button until it expires. It carries the claim token, so share url, never keep_url.

Or email it: POST /sites/:id/keep with {"claim_token": "…", "email": "…", "consent": true} sends that address the claim link and the page's deadline, and one reminder as the page runs out. Ask the person first and send consent: true only when they said yes. No account and no key: the claim_token is the credential. The address is stored on the page, used for those two emails only, and cleared by the claim; one page can send at most three keep emails. A claim keeps working for the 30 days an expired page is held, and claiming an expired page brings it back at the same address, so a page that ran out at 24 hours is not lost until the hold ends.

Update with the wallet itself (no key)

The paying wallet is also the page's update credential — no claim, no account, no API key. POST /wallet-auth/challenge with {"wallet":"0x…"}, personal_sign the returned message, then PUT /sites/:id with Authorization: Wallet challenge=…,sig=0x… and the JSON body. Same URL, free revisions; challenges are single-use with a 5-minute TTL. EVM EOA wallets only for now (no smart-contract wallets).

Everything one wallet has paid for

A publish paid from a wallet returns next.receipt_url, a stable link to a page listing every page that wallet has paid for: title, URL, date, the settlement on-chain, whether the claim token is still live, the exact request that revises each one, and a button to move them all into an account. The link is the credential and the payer address is never accepted in its place: addresses are public on-chain, so an address-keyed page would make every x402 customer's private page titles enumerable from a block explorer. It is not returned by POST /wallet-auth/challenge for the same reason, and it is deliberately absent from the 402 challenge, which indexes crawl and republish.

Custom domains

Paid plans (Solo 1 domain, Studio 10, Firm 25), or the custom_domain x402 unlock. Bring your own hostname (docs.acme.com et al), point a CNAME at our Cloudflare for SaaS fallback origin, prove ownership via a TXT record, and traffic to that hostname serves your site over HTTPS.

curl -X POST https://api.stacktr.ee/custom-domains \
     -H "Authorization: Bearer stk_live_..." \
     -H "Content-Type: application/json" \
     -d '{"hostname":"docs.acme.com","site_id":"abc123"}'

Response includes a verify_token and the DNS records you still need to add. Two for a fresh hostname; if a verified parent-domain claim already covers it, instructions is null (subdomain: the wildcard CNAME does the routing) or CNAME-only (the claimed name itself, whose ownership is already proven):

{
  "hostname": "docs.acme.com",
  "site_id": "abc123",
  "verified": false,
  "instructions": {
    "cname": { "name": "docs.acme.com", "value": "proxy.stacktr.ee", "type": "CNAME" },
    "txt":   { "name": "_stacktree-verify.docs.acme.com", "value": "verify_", "type": "TXT" }
  }
}

After adding the DNS records, call verify. We DNS-lookup the TXT record; on match we register the hostname with CF for SaaS and SSL provisioning begins (~60 s).

curl -X POST https://api.stacktr.ee/custom-domains/docs.acme.com/verify \
     -H "Authorization: Bearer stk_live_..."

Re-bind or delete

PATCH  https://api.stacktr.ee/custom-domains/:hostname    # { "site_id": "..." }  — re-bind
DELETE https://api.stacktr.ee/custom-domains/:hostname    # unregister + drop row

List your domains with GET https://api.stacktr.ee/custom-domains. Unverified rows are auto-pruned after 7 days.

OAuth (custom connector authors)

For MCP host implementers — if you're using a maintained client (Claude.ai, Cursor, etc.) skip this section.

Discovery

GET https://api.stacktr.ee/.well-known/oauth-authorization-server
GET https://api.stacktr.ee/.well-known/oauth-protected-resource

Both return standard RFC 8414 / RFC 9728 metadata documents.

Flow

OAuth 2.1 with PKCE (S256 required) and Dynamic Client Registration (RFC 7591). Endpoints:

Callback for hosted Claude surfaces: https://claude.ai/api/mcp/auth_callback.

Limits

Every number below is enforced server-side from one table. GET /me returns the caller's own limits object; read it from there rather than hard-coding a cap in a client.

The client-spaces row counts ACTIVATED spaces, meaning ones with a hostname bound or a portal enabled. Filing pages under a client is free on every plan, Free included: the paid unit is the address, not the label. Archiving a space frees the slot, and a space hostname does not consume a custom-domain slot.

Free counts publishes, not live pages. The 3 is lifetime_publishes, a counter that only goes up: deleting a page or letting it expire does not give the slot back. Solo's 25 is the other model: active pages, freed by deleting. Every free page expires 7 days after it is published, and passing expires_in_hours: "never" is refused rather than quietly landing on the ceiling: an agent that gets a 201 tells its user the link is permanent, so the answer has to be an error it cannot mistake for success. accept_clamp publishes it with the 7 days.

DCR rate limit: 10 client registrations / IP / hour. An expired page stops serving within the hour and the URL then says the link expired, exactly as before; what changed is what happens next. The content is kept for 30 days rather than destroyed at that moment, so POST /sites/:idOrSlug/restore can put it back at the same URL, and only then is it purged from R2 and D1 for good.

Enterprise is custom and annual (self-hosting, SLA, data residency). A standard DPA is available on request on any plan from security@stacktr.ee. Ask at gm@stacktr.ee. Accounts on the older Pro and Agent plans keep the limits they signed up on; neither is sold any more.

No plan? The higher_limits unlock ($25 / 30 days over x402) lifts a free identity to fleet limits: 1 GB per site, unlimited daily publishes, no page cap, and pages that do not expire. make_permanent ($5, one page) cancels the expiry on a single page instead.

Plan errors

Each carries a stable error code, the caller's plan, a human message, and where relevant a limit. Surface them as an upgrade prompt, not a raw string:

Expiry is half an exception. A page lifetime longer than the plan ceiling is clamped rather than refused: it comes back shortened in expires_at, with expiry_clamped: true and no error. Asking for a page that never expires on a capped plan is refused instead, 409 expiry_clamped, because that is the one case where the difference gets repeated to a person as "this link is permanent". accept_clamp takes the ceiling in one field.

Every response that carries a page carries its deadline six ways: expires_at (unix seconds, unchanged), expires_at_iso (RFC 3339 UTC, the one to show a human), ttl_seconds (never negative), expiry_clamped, expiry_ceiling_hours (24 anonymous, 168 Free, null on plans with no ceiling) and expiry_source (request, plan_ceiling, plan_default or stored).