Skip to content

How it works

From sign-in to your first click, step by step

Do it in the dashboard, or script it: the dashboard uses the same API shown here. Running linkweave yourself? Getting started sets up the whole stack locally with no real secrets.

  1. Step 1: Sign in

    Sign in with Zitadel. Only the identities on your owner pin get in; anyone else is turned away before any handler runs.

    Prefer the API? Every owner request carries a bearer token from GET /api/session, the header X-Requested-With: linkweave and, for creates and publishes, an Idempotency-Key.

    Shared shell setup for the API examples
    API=http://localhost:4059
    TOKEN=...            # the access token for your signed-in session
    H=(-H "Authorization: Bearer $TOKEN" -H "X-Requested-With: linkweave" -H "Content-Type: application/json")
  2. Step 2: Claim your slug

    Pick 3 to 32 lowercase letters, digits or hyphens. The slug is reserved for you, and route names like features or dashboard can never be claimed.

    Claim a slug
    curl -sS -X POST "$API/api/profile" "${H[@]}" -H "Idempotency-Key: $(uuidgen)" \
      -d '{"slug":"ada","displayName":"Ada Lovelace","timezone":"Europe/London"}'
  3. Step 3: Add your links

    Add a display name and, if you like, a bio, an avatar and a theme. Then add links (a label and an https URL) and social icons (a platform and a handle), in the order you want.

    Each edit sends the draft’s current version, so a stale tab cannot overwrite newer work.

    Add a link to the draft
    curl -sS -X POST "$API/api/links" "${H[@]}" -H "Idempotency-Key: $(uuidgen)" \
      -d '{"kind":"link","label":"My notes","url":"https://example.com/notes","version":1}'
  4. Step 4: Publish

    Press Publish. linkweave snapshots the draft and your page is live at /your-slug, with an Atom feed at /your-slug/feed.xml. Publishing needs a display name and at least one visible link.

    Publish the draft
    curl -sS -X POST "$API/api/profile/publish" "${H[@]}" -H "Idempotency-Key: $(uuidgen)" \
      -d '{"version":2}'
  5. Step 5: Share it

    Put /your-slug in your bio. Visitors get a server-rendered page that works with JavaScript turned off and sets no cookies.

    Every link on it goes through /r/linkId: a 302 to the link’s URL and one counted click.

  6. Step 6: Read your numbers

    Read daily click counts for the last 7 or 30 days, grouped in your time zone, or export them as CSV. Each row is a link, a day, a referrer category and a count, and nothing about who clicked.

    Read the last 30 days of clicks
    curl -sS "$API/api/analytics?range=30" -H "Authorization: Bearer $TOKEN" -H "X-Requested-With: linkweave"

Then automate the rest

Add a signed webhook and every publish can rebuild your site or post an announcement. Unpublish takes the page offline and keeps the snapshot, so republishing is instant.

You will wish you had it yesterday.

Run it locally in five steps, then ship it to your own domain.