Projects & Teams

A project is the workspace boundary for an Olyx integration. It groups the API keys, model registry entries, routing settings, alert webhooks, traces, and cost history for one environment or product surface.

During closed beta, the simplest setup is one project for staging and one project for production. That keeps test traffic away from production traces, production spend, and production routing decisions.

Data Hierarchy

Projects sit under an organization. API keys, models, alerts, and traces belong to a project.

flowchart TD ORG[ORGANIZATION] PROD[PRODUCTION PROJECT] STAGE[STAGING PROJECT] KEYS[API KEYS] MODELS[MODEL REGISTRY] ROUTING[ROUTING SETTINGS] TRACES[TRACES] ALERTS[ALERT WEBHOOKS] ORG --> PROD ORG --> STAGE PROD --> KEYS PROD --> MODELS PROD --> ROUTING PROD --> TRACES PROD --> ALERTS

The boundary matters because a project-scoped key should only create and read traces for its own project. Use that constraint deliberately: staging keys for staging traffic, production keys for production traffic.

What a Project Gives You

A project is the smallest useful unit for operating Olyx.

Capability	Why it matters
Trace isolation	Keeps staging, production, and experimental traffic separate.
Model registry	Defines which model endpoints this project can use.
API keys	Lets each service authenticate with a project-scoped identity.
Routing settings	Maps simple, medium, complex, and selected private paths to registered models.
Alert webhooks	Sends selected beta alert events to your own endpoint.
Cost history	Makes spend and optimization reports meaningful per environment.

Creating a Project

Create projects from the dashboard during normal setup. Use the API reference only when you are building internal provisioning scripts or CI automation.

Project records have a small shape.

Field	Description
`id`	Numeric project ID used by control-plane APIs.
`name`	Display name shown in the dashboard and docs examples.
`description`	Optional human description for team context.
`status`	`active` or `archived`. Archived projects are retained for history and should be kept out of live service configuration.
`settings`	Routing, grading, and beta operating settings.
`total_monthly_spend`	Current calendar-month spend attributed to the project.

Use names your team will recognize in incidents: production, staging, ci, or the product name.

Project-Scoped SDK Usage

The SDK does not need a project_id on every call when the API key is already scoped to the project. Configure the service with the correct key for its environment, then create traces normally.

import Olyx from "@olyx-labs/olyx";

const client = new Olyx({
  apiKey: process.env.OLYX_PRODUCTION_API_KEY!,
});

const trace = await client.traces.create({
  metadata: { service: "billing-api", environment: "production" },
});

import os
import olyx

client = olyx.Olyx(
    api_key=os.environ["OLYX_PRODUCTION_API_KEY"],
    mock=False,
)

trace = client.traces.create(
    metadata={"service": "billing-api", "environment": "production"}
)

client = Olyx.new(
  api_key: ENV.fetch("OLYX_PRODUCTION_API_KEY")
)

trace = client.traces.create(
  metadata: { service: "billing-api", environment: "production" }
)

Keep the environment in metadata even when the key is already environment-specific. It makes trace search and incident review easier.

Archiving a Project

Archive a project when an environment or experiment is no longer active. Treat archiving as the last step after moving services away from that project’s keys and routing settings.

State	Meaning
`active`	Project can accept keys, model settings, and traces.
`archived`	Project remains visible for history after active services have moved away from it.

Before archiving, rotate services away from that project’s keys. After archiving, keep the project around long enough for your team to review traces, costs, and postmortem notes.

Multiple Projects

Most beta teams should start with environment-based projects.

Project	Purpose
`production`	Live traffic, tighter spend caps, real incident review.
`staging`	Release validation, SDK upgrades, provider configuration tests.
`ci`	Automated integration checks with small spend caps.
`experiments`	Model comparison and routing trials isolated from production history.

Create product-line projects only when each product has different models, teams, budgets, or retention needs. Too many projects too early makes beta operations harder to read.

Project Settings

Project settings are where you connect concept-level behavior to the registered models and limits for that project. Keep the first configuration small and observable.

Setting	Start with
Routing tiers	One simple model and one stronger fallback model. Add private routes only when needed.
Grading baseline	Rough cost and latency expectations until real trace history exists.
Alert thresholds	A small number of actionable webhooks, not every possible signal.
Spend caps	Per-key caps for production and tighter caps for staging or CI.

Routing tiers must reference identifiers that already exist in the Model Registry. Cost and grade behavior is covered in Cost Intelligence.

Roles & Permissions

Roles control what a human can do in the dashboard and control-plane APIs. API keys are different: they are system identities scoped to project configuration, not human users.

Role	Typical responsibility
Owner	Organization administration, billing setup, and final project control.
Admin	Project configuration, keys, model registry, and team operations.
Member	Trace review, stats, and day-to-day debugging.

Use the least powerful role that fits the job. A developer who only needs to inspect traces does not need owner access.