@floats/sdk

Typed client + AI-agent tools for Floats — the visual knowledge canvas. Read canvases, write floats (cards, text boxes, quotes, code, section breaks, margin notes on anything — images included), add page breaks, search the workspace knowledge base, and run spaced-repetition flashcards.

npm install @floats/sdk

Get an API key in your Floats dashboard → API keys.

Client

import { FloatsClient } from '@floats/sdk';

const floats = new FloatsClient({ apiKey: process.env.FLOATS_API_KEY! });

const canvases = await floats.listCanvases();
const canvas = await floats.getCanvas(canvases[0].id);

// Write a small cluster: two cards, an arrow, and a margin note — live on the canvas.
await floats.addFloats(canvas.id, [
  { kind: 'card', ref: 'a', title: 'Attention', body: 'Q·K similarity decides what V to blend.' },
  { kind: 'card', ref: 'b', title: 'Softmax', body: 'Turns scores into a probability mix.' },
  { kind: 'margin', anchorId: 'a', text: 'the “river bank” example lives here' },
], [{ from: 'a', to: 'b' }]);

// Page break, then flashcards into the review rotation.
await floats.addPage(canvas.id);
await floats.createFlashcards(canvas.id, [{ front: 'What does softmax do?', back: 'Scores → probabilities.' }]);

// Semantic search across every canvas (images included via OCR).
const hits = await floats.search('how attention weighs values');

// Run a review session.
const { due } = await floats.dueFlashcards();
await floats.gradeFlashcard(due[0].canvasId, due[0].floatId, 'knew_it');

Agent tools (Vercel AI SDK — any model)

import { generateText } from 'ai';
import { FloatsClient } from '@floats/sdk';
import { floatsTools } from '@floats/sdk/ai';

const floats = new FloatsClient({ apiKey: process.env.FLOATS_API_KEY! });

await generateText({
  model,                             // Claude, GPT, Gemini, Llama — anything the AI SDK runs
  tools: { ...floatsTools(floats) },
  prompt: 'Summarize my “Transformers” canvas and add flashcards for anything I have no cards for.',
});

MCP instead?

• Remote (claude.ai, Claude Code, ChatGPT, Cursor…): https://thefloats.app/api/mcp with your key as a bearer token.
• Local stdio: npx @floats/mcp.

Float kinds you can create

| kind | on the canvas | | --- | --- | | card | bordered knowledge card (title + body) | | image | picture float — pass a url (http(s)/data URI) or base64 data; re-hosted into Floats storage, optional description caption | | textbox / sticky | the rail's cream free-text box | | quote | borderless pull-quote | | link | favicon + title chip | | section | ink section-break rule with a heading | | code | code block (language-aware) | | margin | handwritten margin note with a leader arrow, anchored to any float |

Everything lands in the app's own shapes — agent-written floats are indistinguishable from hand-made ones, and connected margin notes travel with their anchor.

MIT © Floats