Kapable Artifacts · onboarding brief

Publish your first artifact.

Kapable Artifacts turns one self-contained HTML file into a durable, designed document at a permanent URL — org-private by default, shared outward only by explicit, revocable link. This is the five-minute setup: one token, one command, one rule.

  1. Put your token in the shell

    You'll receive an sk_org_… API key separately (never in this document — it's publicly shared). The key identifies both you and the org; you never pass an org id.

    export KAPABLE_ORG_KEY=sk_org_…        # add to ~/.zshrc to keep it

  2. Prove it works

    curl -sS -o /dev/null -w "%{http_code}\n" \
  https://api.kapable.ai/v1/artifacts \
  -H "x-api-key: $KAPABLE_ORG_KEY"

    200 means you're in. 401 means the token didn't paste cleanly — re-check it before anything else.

  3. Publish

    Write hello.html — a fragment with a <title>, a <style> block, and your content. Everything inline; the platform wraps it in the org chrome. Then (needs jq):

    Your first publish — terminal

    $ curl -sS -X POST https://api.kapable.ai/v1/artifacts \
    -H "x-api-key: $KAPABLE_ORG_KEY" \
    -H "content-type: application/json" \
    -d @- <<JSON
  {
    "slug": "hello-hardy", "title": "Hello, Artifacts", "kind": "brief",
    "summary": "First publish.", "favicon": "👋",
    "html": $(jq -Rs . < hello.html)
  }
  JSON
  → 201 Created
  { "artifact_id": "…", "version": 1,
    "url": "https://kapable.kapable.ai/artifacts/hello-hardy", "sha256": "…" }

    Same slug again later → version 2. Versions are immutable; v1 stays reachable forever.

  4. See it, share it, discuss it

    Your document is live at the returned URL — org members see it in the gallery at kapable.kapable.ai/artifacts/. To share with someone outside the org, mint a revocable public link:

    curl -sS -X POST https://api.kapable.ai/v1/artifacts/hello-hardy/shares \
  -H "x-api-key: $KAPABLE_ORG_KEY" -H "content-type: application/json" -d '{}'
# → { "id": "…", "token": "…", "public_url": "https://kapable.ai/a/…" }
# revoke later: curl -X DELETE …/shares/{id}   → link dies within one request

    Inside the org viewer, every document carries a margin: highlight any passage, attach a comment, and use Copy prompt to carry the question into a Claude Code session — the agent answers in the margin, or republishes the document and resolves the thread pointing at the new version.

  5. Optional — let the agent design it

    If you use Claude Code, copy the skill folder .claude/skills/kapable-artifact-publish/ from the platform repo into your own ~/.claude/skills/, then just ask: "publish an artifact about …". The skill carries the design doctrine, validates locally, and publishes with your KAPABLE_ORG_KEY — so what lands in the gallery is designed, not dumped.

The rules that bite

  • Self-contained or rejected. No external scripts, stylesheets, fonts, or images — the server refuses the publish and names the exact offending construct. Inline everything; data: URIs are fine; plain <a href> links out are fine.
  • 2 MiB cap per version, measured on the serialized HTML.
  • Nothing is edited in place. Fixing a document means publishing the next version — the history is the feature, not a bug.

kapable artifacts · onboarding brief · published from session quick-otter · 2026-07-03