Install and run your first session

Two clients, two first calls. Pick the one that matches where your code runs; the SDK overview explains the difference.

Headless: a call from anywhere

1. 1
   Create an API key in Settings, under API keys, in your dashboard. It looks like dsk_live_... and it is shown once.
2. 2
   Install the SDK: npm install @blankline/dropstone-sdk.
3. 3
   Put the key in the environment, as DROPSTONE_API_KEY. Treat it like a password: never commit it, and never ship it in a browser bundle.
4. Call it. The client reads the environment variable on its own.

import { createDropstoneApi } from "@blankline/dropstone-sdk"

const dropstone = createDropstoneApi()

const resp = await dropstone.chat.completions.create({
  model: "dropstone-fast",
  messages: [{ role: "user", content: "Summarise this changelog entry." }],
})

console.log(resp.choices[0].message.content)

Add stream: true and the same call returns an async iterator of chunks, which is what you want in a UI or a long answer:

const stream = await dropstone.chat.completions.create({
  model: "dropstone-fast",
  stream: true,
  messages: [{ role: "user", content: "Count to five." }],
})

for await (const chunk of stream) {
  process.stdout.write(chunk.choices?.[0]?.delta?.content ?? "")
}

The endpoint is OpenAI-compatible, so an existing client works by pointing at Dropstone:

import OpenAI from "openai"

const openai = new OpenAI({
  baseURL: "https://api.dropstone.io/api/v1",
  apiKey: process.env.DROPSTONE_API_KEY,
})

API-key requests are billed pay-per-use from your credit balance, not from a plan allowance, and a key with an empty balance is refused with a top-up link. See Using the API with your plan.

Local: the agent, in your process

The local client starts a dropstone serve process, hands you a typed client pointed at it, and closes it when you are done. Because it runs as your account, sessions carry your memory.

1. 1
   Install the Dropstone CLI and sign in with dropstone login. The SDK reads the same sign-in.
2. Create a session, then send it a prompt.

import { createDropstone } from "@blankline/dropstone-sdk"

const { client, server } = await createDropstone()

const session = await client.session.create({
  body: { agent: "build", model: { providerID: "dropstone", modelID: "dropstone-pro" } },
})

const reply = await client.session.prompt({
  path: { id: session.data.id },
  body: { parts: [{ type: "text", text: "Hello, who are you?" }] },
})

console.log(reply.data)
await server.close()

If a server is already running, skip the spawn:

import { createDropstoneClient } from "@blankline/dropstone-sdk"

const client = createDropstoneClient({ baseUrl: "http://127.0.0.1:4096" })

Tips

• Pin the version range. The SDK ships on a fast cadence, so depend on a range you have tested rather than the latest tag.
• Use v2 for new code. @blankline/dropstone-sdk/v2 is the surface new endpoints land on; v1 stays for existing integrations.
• Keep a pipeline's learning out of your own memory. A headless call has no memory attached, and a local session uses the account you signed in with. If an integration should have its own memory, give it its own account. See One memory across every surface.

Limitations

• The local client needs the CLI on the same machine; a host without it should use the headless client.
• The headless endpoint is chat completions. The agent loop, file operations and workspace tools are on the local client.