Skip to main content

Projects

Projects are isolated workspaces. Each project has its own provider allow-list, routing rules, budgets, environments, and API keys. Use them to separate dev/staging/production or different products.

Managing projects​

// List
const { projects } = await client.projects.list();

// Create
const project = await client.projects.create({
  name:        'My App',
  slug:        'my-app',        // optional URL-safe identifier
  description: 'Production AI', // optional
});

// Update
await client.projects.update(project.id, { name: 'My App v2' });

// Delete
await client.projects.delete(project.id);

Project-scoped sub-client​

Once you have a project ID, use client.project(id) to get a sub-client for all project-level operations:

const proj = client.project('proj_abc123');

Connections (project provider allow-list)​

Project connections restrict which providers this project's requests may use. There's no API key here, just a providerId and an optional allowedModels narrowing. This is a different concept from the org-level client.providers namespace (see Providers), which is where you actually connect your own key (BYOK); a project's allow-list applies on top of whatever providers your org already has access to, whether that's a platform-connected provider or one you've connected yourself with your own key. If a project sets an explicit allow-list, any provider not on it, including a BYOK provider, is excluded from that project's requests.

// Restrict this project to a platform-connected provider (+ optionally a model subset)
await proj.connections.add({
  providerId:    'openai',
  enabled:       true,
  allowedModels: ['gpt-4o-mini'],   // omit to allow all of the provider's models
});

// List this project's allow-list
const { providers } = await proj.connections.list();

// Toggle
await proj.connections.disable('openai');
await proj.connections.enable('openai');

// Remove the restriction (falls back to the org-wide catalog for this provider)
await proj.connections.remove('openai');

Project routing​

Each project can override the org-level routing strategy. Project-level config only covers strategy, provider order/affinity, aliases, and regions. The governance policy block (blocked providers, cost/latency ceilings, fallbackBehavior, etc.) is org-level only and has no project override today:

await proj.routing.setConfig({
  strategy: 'cheapest',
});

// Per-project model aliases
await proj.routing.setAliases({ smart: 'gpt-4o-mini' });
await proj.routing.deleteAlias('smart');

Policy​

const policy = await proj.policy.get();

await proj.policy.set({
  maxTokensPerRequest: 4096,
  allowedModels:       ['gpt-4o', 'gpt-4o-mini'],
});

Budget​

await proj.budget.set({
  monthlyUsd: 500,      // hard monthly cap
  alertPct:   80,       // alert at 80% of cap
  hardLimit:  true,     // reject requests when cap is hit
});

const budget = await proj.budget.get();
console.log(budget.spentUsd, budget.monthlyUsd);

Environments​

const { environments } = await proj.environments.list();

const { id } = await proj.environments.create({
  name:         'Staging',
  slug:         'staging',
  isProduction: false,
});

await proj.environments.delete(id);

Project usage​

const overview = await proj.usage.overview(24);   // last 24 h
const series   = await proj.usage.series(168);     // last 7 days
const breakdown = await proj.usage.breakdown(24);