Appearance
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 usefullyts
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.
| Method | Endpoint |
|---|---|
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 }.