Product APIs

The platform hosts a set of products — Marozzo, Kvark, and others — and some of them expose their own public API surface on top of the shared platform primitives (entities, notifications, analytics). This page groups those product-specific endpoints in one place. Each section is self-contained; follow its reference link for the complete parameter list.

Marozzo assistant chat

Marozzo's AI assistant answers questions about Marozzo's own content using retrieval-augmented generation — it refuses questions outside that scope, and cites the source pages it used. Chat requires a user-bound personal access token; a service credential is rejected.

curl -sf -X POST "https://api.falcata.io/api/v1/marozzo/chat" \
  -H "Authorization: Bearer $FURNACE_PAT" \
  -H "Content-Type: application/json" \
  -d '{"message":"What is the half-sword technique?"}' \
  | jq '{threadId: .data.threadId, reply: .data.message}'

Omit threadId to start a new thread, or pass one back to continue it. Threads have no delete endpoint and persist until backend cleanup; the assistant titles them automatically from the first message.

Reference: full reference.

Historical dictionaries (Florio 1611 / Crusca)

Search John Florio's 1611 English–Italian dictionary and the Vocabolario degli Accademici della Crusca, plus a set of Bolognese HEMA treatises (Manciolino, Opera Nova, dall'Agocchie). This surface is public reference material — no permission beyond a valid token is required.

curl -sf "https://api.falcata.io/api/v1/dictionaries/search?q=spada&source=florio&limit=5" \
  -H "Authorization: Bearer $FURNACE_TOKEN" | jq '.data[] | {headword, definition}'

source defaults to all (both dictionaries); pass florio or crusca to narrow it. Treatise search is a separate endpoint (/dictionaries/treatises/search) — searching dictionaries never returns treatise text.

Reference: full reference.

Kvark tasks and boards

Kvark is the canonical task and board system — items, tags, moves, and Board placements, all backed by a concrete per-item owner. A service token is refused for the same reason as /me/*: every item needs someone to own it.

curl -sf -X POST "https://api.falcata.io/api/v1/kvark/tasks" \
  -H "Authorization: Bearer $FURNACE_PAT" \
  -H "Content-Type: application/json" \
  -d '{"title":"Investigate deploy","body":"Check runner logs","tags":["ops"]}'

Pass visibility: "zero-knowledge" on create to keep an item's body private — automation can still manage its title, tags, scheduling, and Board placement, but can never read or write the encrypted body.

Reference: full reference.

Notes

Notes are per-user and end-to-end encrypted: the server stores encryptedContent, iv, and salt as opaque blobs and never decrypts them. If you lose the client-side key, the note is unrecoverable — there is no server-side plaintext to fall back to.

curl -sf -X POST "https://api.falcata.io/api/v1/notes" \
  -H "Authorization: Bearer $FURNACE_PAT" \
  -H "Content-Type: application/json" \
  -d '{"title":"Meeting notes","encryptedContent":"<base64>","iv":"<base64>","salt":"<base64>"}' \
  | jq '.data.id'

Use ?titles=1 when listing notes for a picker UI — it skips downloading ciphertext you don't need yet.

Reference: full reference.

Hero promos

Namespace-scoped promotional banners with manual on/off and a scheduled visibility window, rendered as an ordered carousel.

curl -sf -X POST "https://api.falcata.io/api/v1/marozzo/hero-promos" \
  -H "Authorization: Bearer $FURNACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "badge":"New",
    "message":"Summer course now available",
    "ctaLabel":"Enroll",
    "ctaHref":"https://example.com/courses/summer",
    "enabled":true,
    "startsAt":null,
    "endsAt":null
  }' | jq '.data.id'

PATCH on a promo is a full replace — send all seven fields even if only one changed.

Reference: full reference.