JavaScript Examples

These examples use the built-in fetch API available in Node.js 18+ and all modern browsers.

Setup

const BASE_URL = "https://api.modelgraph.ai/api/v1";

List all providers

const response = await fetch(`${BASE_URL}/providers`);
const { providers } = await response.json();

for (const provider of providers) {
  console.log(`${provider.name}: ${provider.model_count} models`);
}

Get a model family timeline

const response = await fetch(`${BASE_URL}/families/claude-sonnet`);
const family = await response.json();

console.log(`Family: ${family.name}`);
for (const model of family.models) {
  console.log(`  ${model.display_name} (${model.status}) — ${model.release_date}`);
}

Resolve a model string

async function resolveModel(modelString) {
  const response = await fetch(
    `${BASE_URL}/resolve?q=${encodeURIComponent(modelString)}`
  );

  if (response.status === 404) {
    console.log(`Unknown model: ${modelString}`);
    return null;
  }

  const data = await response.json();

  if (data.is_latest) {
    console.log(`✓ ${modelString} — already latest (${data.matched_model.display_name})`);
  } else {
    const upgradeAlias = data.upgrade_alias.alias;
    console.log(`⬆ ${modelString} → ${upgradeAlias} (${data.upgrade.display_name})`);
  }

  return data;
}

await resolveModel("claude-3-sonnet-20240229");
await resolveModel("anthropic.claude-3-5-sonnet-20241022-v2:0");
await resolveModel("gpt-4o-2024-08-06");

Search for models

const response = await fetch(
  `${BASE_URL}/search?q=${encodeURIComponent("llama 70b")}`
);
const { results } = await response.json();

for (const result of results) {
  console.log(`${result.display_name} (${result.provider.name}) — score: ${result.score}`);
}

Batch-check model strings

const modelStrings = [
  "claude-3-sonnet-20240229",
  "gpt-4-0613",
  "anthropic.claude-3-5-sonnet-20241022-v2:0",
  "mistral-large-2402",
  "claude-sonnet-4-6",
];

console.log("Checking model strings for upgrades...\n");

const results = await Promise.all(
  modelStrings.map(async (modelString) => {
    const response = await fetch(
      `${BASE_URL}/resolve?q=${encodeURIComponent(modelString)}`
    );

    if (response.status === 404) {
      return { modelString, status: "not_found" };
    }

    const data = await response.json();
    return { modelString, ...data };
  })
);

for (const result of results) {
  if (result.status === "not_found") {
    console.log(`  ? ${result.modelString} — not found`);
  } else if (result.is_latest) {
    console.log(`  ✓ ${result.modelString} — up to date`);
  } else {
    console.log(`  ⬆ ${result.modelString} → ${result.upgrade_alias.alias}`);
  }
}

TypeScript types

interface Provider {
  slug: string;
  name: string;
  website_url: string;
  api_models_url: string | null;
  family_count: number;
  model_count: number;
  created_at: string;
  updated_at: string;
}

interface ModelSummary {
  slug: string;
  display_name: string;
  version: string;
  status: "active" | "latest" | "deprecated" | "sunset";
  family: { slug: string; name: string };
  provider: { slug: string; name: string };
  release_date: string | null;
  deprecation_date: string | null;
  sunset_date: string | null;
  parameter_count: number | null;
  parameter_label: string | null;
  input_context_window: number | null;
  output_context_window: number | null;
  is_open_source: boolean;
}

interface ResolveResponse {
  matched_model: {
    slug: string;
    display_name: string;
    status: string;
    family: string;
  };
  matched_alias: {
    alias: string;
    source: string;
  };
  confidence: number;
  is_latest: boolean;
  upgrade: {
    slug: string;
    display_name: string;
    status: string;
  } | null;
  upgrade_alias: {
    alias: string;
    source: string;
  } | null;
}

interface SearchResult {
  slug: string;
  display_name: string;
  version: string;
  status: string;
  family: { slug: string; name: string };
  provider: { slug: string; name: string };
  score: number;
}

Error handling

async function safeResolve(modelString) {
  try {
    const response = await fetch(
      `${BASE_URL}/resolve?q=${encodeURIComponent(modelString)}`,
      { signal: AbortSignal.timeout(10000) }
    );

    if (response.ok) {
      return await response.json();
    }

    if (response.status === 404) {
      return null;
    }

    if (response.status === 429) {
      const resetAt = response.headers.get("X-RateLimit-Reset");
      console.warn(`Rate limited. Resets at ${resetAt}`);
      return null;
    }

    const error = await response.json();
    console.error(`API error: ${error.error?.message ?? "Unknown error"}`);
    return null;
  } catch (err) {
    if (err.name === "TimeoutError") {
      console.error("Request timed out");
    } else {
      console.error(`Request failed: ${err.message}`);
    }
    return null;
  }
}