Public Share API

Overview

The Public Share API is the machine-readable side of Alistia's public shares.

An Alistia user can publish a list — or, later, a saved view — as a public share. Publishing produces a random token. Anyone holding the token can read a cleaned snapshot of the shared data. The same snapshot powers both the human-facing web page (https://alistia.app/s/{token}) and this JSON API.

Only whitelisted fields are exposed. Profiles, members, circles, sync operations, conflicts and private media URLs are never included. Shares are revocable and can carry an expiry date.

Base URL

All endpoints live under /v1:

https://link.alistia.app/v1

Responses are JSON. This is version v1; changes within v1 are additive only.

Authentication

There is no API key. The token in the URL is the credential — anyone holding a share link can read its data, which is exactly the point of a public share.

Tokens are random and stored server-side only as a SHA-256 hash, so the raw token never rests in the database. A share can be disabled or given an expiry date at any time from the Alistia app; the API then stops returning data.

Errors

Failed requests return a consistent shape with the matching HTTP status:

{
  "error": {
    "code": "expired",
    "message": "This share link has expired."
  }
}

code is a stable, machine-readable reason; message is a human-friendly explanation and may change.

Endpoints

# request
curl https://link.alistia.app/v1/views/AbCdEfGh12345678.json

# 200
{
  "list": { "name": "Mallorca Trip", "description": "Everything for the holiday" },
  "generatedAt": "2026-07-22T12:00:00.000Z",
  "fields": [
    { "key": "aufgabe", "name": "Aufgabe", "type": "text" },
    { "key": "datum", "name": "Datum", "type": "date" }
  ],
  "entries": [
    { "id": "entry_1", "values": { "aufgabe": "Mietwagen buchen", "datum": "2026-08-01" } }
  ]
}

Response schema (.json)

The machine-readable .json view is lean — one canonical, typed value per field, keyed by the stable field key:

fields[].key is a stable slug of the field name (e.g. "Länge (Min)" → laenge_min) and doesn't change when the label is renamed. Values are typed (dates YYYY-MM-DD, numbers as numbers, …). No internal ids are exposed. Use the same key when writing.

Write tokens

The write API lets external systems create, update and delete entries in a list. It uses a separate write token (not the read share token), created in the Alistia app under list → Write-API. A token is scoped to one list and to the operations you allow (create / update / delete).

Authorization: Bearer <write-token>

Base URL for writing:

https://write.alistia.app/v1

Values are keyed by the same stable field key you get from the read data link (fields[].key), and given as natural values — the API coerces them into storage format. Writes run in the name of the list owner and produce the same side effects as the app (ordering, collaborator notifications). Bulk writes send a single coalesced notification, not one per entry.

# single
curl -X POST https://write.alistia.app/v1/entries \
  -H "Authorization: Bearer <write-token>" \
  -H "content-type: application/json" \
  -d '{"values":{"aufgabe":"Mietwagen buchen","datum":"2026-08-01"}}'

# bulk
{ "entries": [ { "values": { … } }, { "values": { … } } ] }

# 201
{ "ok": true, "created": [ { "id": "…", "revision": 1 } ], "count": 1 }

PATCH → { "ok": true, "id": "…", "revision": 2 }
DELETE → { "ok": true, "id": "…", "deleted": true }

Outbound webhooks

Instead of polling, let Alistia push to you. Configure a webhook for a list in the app (list → Webhooks) with a target URL and the events you care about. When an entry in that list is created, updated or deleted, Alistia POSTs a compact JSON payload to your URL. No field values or secrets are sent — fetch the data link if you need the details.

# POST to your target URL
{
  "app": "alistia",
  "event": "entry.created",
  "listId": "66f8...f01",
  "entryId": "66f8...a12",
  "occurredAt": "2026-07-22T12:18:36.498Z"
}

Events

Headers on every delivery: x-alistia-event (the event name) and, when a secret is set, x-alistia-signature. Deliveries are retried once on failure; after repeated failures the webhook is automatically disabled.

Signature verification

If you set a secret, Alistia signs the exact request body and sends it as an HMAC-SHA256 header. Verify it to be sure a request really came from Alistia:

x-alistia-signature: sha256=<hex>
x-alistia-event: entry.created

// Node.js
const expected = 'sha256=' +
  crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(header));

Sign over the raw request body bytes, not a re-serialized object.

Automations & n8n

There is a dedicated n8n community node. Install @pandee-de/n8n-nodes-alistia from Settings → Community Nodes. It wraps this whole API — read, write and real-time — so you rarely need a raw HTTP node.

There is also an Alistia Trigger (polling) for setups without inbound webhooks, and any plain HTTP client still works — a shell script, a Home Assistant REST sensor, Make or Zapier — against the endpoints above.

OpenAPI spec

The full API is described as an OpenAPI 3.1 document. Import it into Postman, Insomnia, or n8n's HTTP Request node, or generate a client:

Download openapi.yaml