Onlist JavaScript/TypeScript SDK

The official JavaScript/TypeScript SDK for Onlist, the AI API marketplace. Access 200+ AI models through a unified, OpenAI-compatible API with intelligent provider routing and competitive pricing.

Installation

npm install @onlist/sdk

Quick Start

import { Onlist } from "@onlist/sdk";

const client = new Onlist({ apiKey: "sk-..." });

const response = await client.chat.completions.create({
  model: "anthropic/claude-sonnet-4",
  messages: [{ role: "user", content: "Hello!" }],
});

console.log(response.choices[0].message.content);

Authentication

The SDK looks for API keys in this order:

1. apiKey constructor parameter
2. ONLIST_API_KEY environment variable
3. OPENAI_API_KEY environment variable (OpenAI SDK fallback)

// Explicit key
const client = new Onlist({ apiKey: "sk-..." });

// From ONLIST_API_KEY
// export ONLIST_API_KEY=sk-...
const client = new Onlist();

// Falls back to OPENAI_API_KEY if ONLIST_API_KEY is not set
// export OPENAI_API_KEY=sk-...
const client = new Onlist();

Provider Routing

Route requests to specific providers on the Onlist marketplace:

// Pin to a specific provider
const response = await client.chat.completions.create({
  model: "anthropic/claude-sonnet-4",
  messages: [{ role: "user", content: "Hello!" }],
  provider: { only: ["alice-shop"] },
});

// Sort by price
const response = await client.chat.completions.create({
  model: "openai/gpt-4o",
  messages: [{ role: "user", content: "Hello!" }],
  provider: { sort: "price" },
});

// Prioritize specific providers with fallback
const response = await client.chat.completions.create({
  model: "openai/gpt-4o",
  messages: [{ role: "user", content: "Hello!" }],
  provider: {
    order: ["alice-shop", "bob-ai"],
    allow_fallbacks: true,
  },
});

Streaming

const stream = await client.chat.completions.create({
  model: "anthropic/claude-sonnet-4",
  messages: [{ role: "user", content: "Tell me a story" }],
  stream: true,
});

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

Marketplace API

Browse models and providers on the Onlist marketplace:

// List models with pricing
const models = await client.marketplace.models.list({ limit: 10 });
console.log(`Found ${models.total} models`);
for (const model of models.data) {
  console.log(`${model.id}: $${model.pricing?.prompt}/M tokens`);
}

// Search models
const results = await client.marketplace.models.list({ q: "claude" });

// Get detailed model info with all provider offers
const detail = await client.marketplace.models.get("anthropic/claude-sonnet-4");
for (const offer of detail.providers) {
  console.log(`${offer.name}: $${offer.price_input_usd}/M input`);
}

// List providers
const providers = await client.marketplace.providers.list();
for (const provider of providers.items) {
  console.log(`${provider.name} (${provider.listing_count} models)`);
}

// Get provider profile
const profile = await client.marketplace.providers.get("alice-shop");

Rankings API

Access model and app usage rankings:

// Model usage leaderboard
const rankings = await client.marketplace.rankings.models({
  sort: "popular",
  window: "week",
});
for (const entry of rankings.leaderboard) {
  console.log(`#${entry.rank} ${entry.model_name} (${entry.total_requests} requests)`);
}

// Trending models
const trending = await client.marketplace.rankings.models({
  sort: "trending",
  window: "month",
});

// App rankings
const apps = await client.marketplace.rankings.apps({
  sort: "popular",
  window: "month",
  limit: 10,
});
for (const app of apps.apps) {
  console.log(`#${app.rank} ${app.title} (${app.domain})`);
}

Error Handling

OpenAI-compatible calls (chat.completions, embeddings, etc.) throw standard openai errors. Marketplace calls throw onlist errors:

import OpenAI from "openai";
import { AuthenticationError, NotFoundError } from "@onlist/sdk";

// OpenAI-compatible endpoints throw openai errors
try {
  await client.chat.completions.create({ model: "gpt-4o", messages: [] });
} catch (e) {
  if (e instanceof OpenAI.AuthenticationError) {
    console.log("Invalid API key");
  }
}

// Marketplace endpoints throw onlist errors
try {
  await client.marketplace.models.get("nonexistent/model");
} catch (e) {
  if (e instanceof NotFoundError) {
    console.log("Model not found");
  }
  if (e instanceof AuthenticationError) {
    console.log("Invalid API key for marketplace");
  }
}

Retry Configuration

Marketplace API calls automatically retry on transient failures (408, 429, 5xx) with exponential backoff:

const client = new Onlist({
  apiKey: "sk-...",
  maxRetries: 3, // default: 2
});

Migration from OpenAI

Replace the openai import with onlist:

- import OpenAI from "openai";
+ import { Onlist } from "@onlist/sdk";

- const client = new OpenAI({ apiKey: "sk-..." });
+ const client = new Onlist({ apiKey: "sk-..." });

// All existing code works unchanged
const response = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Hello!" }],
});

Migration from OpenRouter

- import OpenAI from "openai";
+ import { Onlist } from "@onlist/sdk";

- const client = new OpenAI({
-   baseURL: "https://openrouter.ai/api/v1",
-   apiKey: process.env.OPENROUTER_API_KEY,
- });
+ const client = new Onlist();

// Provider routing syntax is compatible
const response = await client.chat.completions.create({
  model: "anthropic/claude-sonnet-4",
  messages: [{ role: "user", content: "Hello!" }],
});

TypeScript

The SDK is written in TypeScript and ships with full type definitions. All marketplace response types are exported:

import type {
  Model,
  Provider,
  ProviderRouting,
  ModelRankingsResponse,
  AppRankingsResponse,
} from "@onlist/sdk";

Links

• Website
• Documentation
• Model Catalog
• Provider Directory
• API Reference
• GitHub
• Python SDK

License

MIT