Skip to content

TypeScript SDK ​

First release

The API currently serves chat, web search and page reading. SDK methods for other features (embeddings, crawl, research, sandbox, browser, files) return a 404 error until those features are switched on.

bash
npm install usefully
ts
import Usefully from "usefully";

const client = new Usefully(); // reads USEFULLY_API_KEY
const reply = await client.chat.completions.create({
  model: "anthropic/claude-sonnet-5-5",
  messages: [{ role: "user", content: "Hello" }],
});

Zero runtime dependencies; Node 18+, Deno, Bun and edge runtimes. Types are generated from the API's OpenAPI document, so every request and response is typed.

MethodEndpoint
client.chat.completions.create(params)POST /v1/chat/completions (returns a Stream with stream: true)
client.embeddings.create(params)POST /v1/embeddings
client.search(params)POST /v1/search
client.research({question, depth})POST /v1/research (then client.jobs.wait)
client.sandbox.run({code, language})POST /v1/sandbox/run
client.browser.sessions.create() / .retrieve() / .list() / .release()/v1/browser/sessions…
client.models.list()GET /v1/models
client.key.retrieve()GET /v1/key
client.billing.retrieve() / .checkout() / .updateSettings()/v1/billing…

Errors are typed classes (InsufficientCreditsError, RateLimitError, …) with status, type, code and requestId. Connection errors, 408, 409, 429 and 5xx are retried twice with backoff (maxRetries). See the errors guide.

Options: apiKey, baseURL, timeout (ms), maxRetries, fetch, defaultHeaders. Every method also takes { signal, timeout, headers }.