> ## Documentation Index
> Fetch the complete documentation index at: https://docs.surfacearea.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Worlds

> Resolve a world to a pinned version from Node, read its scenarios, dispatch a hosted run of a run config, and wait for the graded result.

`@withgateway/sdk/worlds` is how a Node process names a [world](/worlds) and runs against it. A world resolves to one pinned version, that version has a task list, and a run of it comes back graded.

Every function on this page takes an optional `WorldsClientOptions` object (`{ host, publicKey, secretKey }`) as its last argument. Omit it and the three environment variables are used.

## Resolve a world to a pinned version

`openWorld(slugRef, options?)` takes a slug or a `slug@ref`, where the ref is a branch, tag, semantic version or content hash. It returns a `WorldSet` without downloading the bundle, because the task list comes from the version's file manifest.

```typescript theme={null}
import { openWorld } from "@withgateway/sdk/worlds";

const world = await openWorld("acme-billing@main");

console.log(world.slug);                      // "acme-billing"
console.log(world.ref);                       // "main"
console.log(world.version.versionId);         // the pinned version
console.log(world.version.semanticVersion);   // "1.4.0" or null
console.log(world.version.contentHash);       // what the version is, exactly
console.log(world.tasks.map((t) => t.name));  // every scenario in it
```

`world.version` is a `ResolvedWorldVersion`: `versionId`, `semanticVersion`, `contentHash` and `state`. Pin runs to `versionId` whenever a suite must not split across two versions mid-flight.

### Find one scenario

`world.tasks` holds a `WorldTask` per scenario, each with a `name` and a `variant` parsed from the name. `world.task(variant)` returns the first task whose variant matches, or whose name contains the string, and throws with the known names when nothing matches.

```typescript theme={null}
const task = world.task("mara");
console.log(task.name, task.variant);
```

<Info>
  A `WorldSet` is identity and data only. To execute anything, either open a live session (`world.open`, see [World sessions](/sdk-ts/sessions)) or dispatch a hosted run (`world.dispatch`, below).
</Info>

## Run configs name what a run executes

A run config is a saved selection: which models to run, how much parallelism, and which scenarios or stored tasks to work through. Continuous integration resolves a config by name and dispatches it by id.

```typescript theme={null}
import { listRunConfigs, upsertRunConfig } from "@withgateway/sdk/worlds";

const configs = await listRunConfigs();
for (const config of configs) {
  console.log(config.id, config.name, config.models, config.parallelism);
}
```

`upsertRunConfig(input, options?)` creates a config, or updates the one named by `input.id`.

```typescript theme={null}
const config = await upsertRunConfig({
  name: "pr-gate",
  models: ["claude-sonnet-4-5"],
  parallelism: 4,
  taskNames: ["refund-double-charge", "close-stale-invoice"],
  autoRunOnPush: false,
});
```

| Field | Type | What it selects |
| - | - | - |
| `name` | `string` | The stable handle CI configures, required |
| `models` | `string[]` | One run is filed per model |
| `parallelism` | `number` | Containers the runner works through at once |
| `numExamples`, `rolloutsPerExample` | `number` | How many scenarios, and how many attempts each |
| `timeoutMinutes` | `number` | Budget for the whole run |
| `agent` | `string` | The agent the platform runs inside the container |
| `taskNames` | `string[]` | Scenarios from the world's own bundle |
| `taskSetDatasetId` | `string \| null` | A scenario set instead of bundled names |
| `worldTasks` | `WorldTaskIdRef[]` | Stored tasks, for API worlds |
| `autoRunOnPush` | `boolean` | Run this config automatically on every push |

A config runs either the bundle's own scenarios or the project's stored tasks, never both.

`parseWorldTaskRefs(spec)` turns `id` or `id@version` items, comma-separated or as an array, into the `worldTasks` shape. A ref without a version runs the task's current version at dispatch time.

```typescript theme={null}
import { parseWorldTaskRefs } from "@withgateway/sdk/worlds";

const refs = parseWorldTaskRefs("wt_abc,wt_def@2");
// [{ id: "wt_abc" }, { id: "wt_def", version: 2 }]
```

## Dispatch a hosted run

`world.dispatch(runConfigId, opts?)` starts the run on the platform. The platform executes the world in parallel containers and files one graded run per model.

```typescript theme={null}
const { versionLabel, runs } = await world.dispatch(config.id);

for (const run of runs) {
  console.log(run.model, run.runId, run.ok, run.error);
}
```

`opts` accepts `containerId`, `versionId` to pin a version other than the world's own, and `provenance` to override what was detected.

### Provenance is detected, not configured

Every dispatch carries the branch, commit, repository and actor it came from. `detectProvenance()` reads the GitHub Actions environment first, then falls back to the local git checkout.

```typescript theme={null}
import { detectProvenance } from "@withgateway/sdk/worlds";

console.log(detectProvenance());
// { branch: "fix/refunds", commit: "9f3c...", repoUrl: "...", actor: { ... } }
```

Outside git and outside CI the object comes back empty and the dispatch still goes through.

## Read the verdict

`getRun(runId, options?)` returns a `RunReport` in one request. `waitForRun(runId, opts?)` polls until the run is terminal.

```typescript theme={null}
import { waitForRun } from "@withgateway/sdk/worlds";

const report = await waitForRun(runs[0].runId, {
  timeoutMinutes: 45,
  intervalSeconds: 20,
  onTick: (run) => console.log(run.status, run.shardsCompleted, "/", run.parallelism),
});

console.log(report.status, report.score, report.url);
```

`waitForRun` polls every 20 seconds for up to 45 minutes by default, and throws when the run is still running past the deadline.

### The RunReport shape

| Field | Type | What it is |
| - | - | - |
| `id` | `string` | The run id |
| `status` | `string` | `COMPLETED`, `FAILED`, and the states before them |
| `terminal` | `boolean` | Whether the run has stopped moving |
| `score` | `number \| null` | The run's score, or null when it was not scored |
| `summary` | `string \| null` | The platform's one-line summary |
| `model` | `string \| null` | The model this run used |
| `versionLabel` | `string \| null` | The world version that ran |
| `parallelism` | `number` | Containers used |
| `shardsCompleted` | `number \| null` | Progress while the run is live |
| `url` | `string \| null` | The run's page, which is what a pull request comment should link |
| `evaluations` | `{ id, status, avgReward, url }[]` | One entry per shard |
| `samples` | `{ task, reward, rewards, sessionId }[]` | Per-scenario rewards |

<Info>
  A `score` of `null` means the run was not scored. Treat it as a failure of a score gate rather than as a zero, which is what [`validateWorld`](/sdk-ts/ci) does.
</Info>

## Set a world's secrets

A world that calls a real service holds its credentials on the platform, never in the bundle. The three helpers are write-only: no endpoint returns a secret's value.

```typescript theme={null}
import {
  setEnvSecret,
  listEnvSecretKeys,
  deleteEnvSecret,
} from "@withgateway/sdk/worlds";

await setEnvSecret("acme-billing", "STRIPE_API_KEY", process.env.STRIPE_API_KEY!);

for (const secret of await listEnvSecretKeys("acme-billing")) {
  console.log(secret.key, secret.updatedAt);
}

await deleteEnvSecret("acme-billing", "STRIPE_API_KEY");
```

## Call any public endpoint

`apiRequest(options, method, path, body?)` is the authenticated request the worlds helpers are built on. Use it to call any [REST API](/rest-api) route directly.

```typescript theme={null}
import { apiRequest } from "@withgateway/sdk/worlds";

const projects = await apiRequest<{ data: { id: string; name: string }[] }>(
  {},
  "GET",
  "/api/public/projects",
);
```

The first argument is the same `{ host, publicKey, secretKey }` object every other function takes. Pass `{}` to use the environment.

[Describe a world](/sdk-ts/describe) covers reading what a world holds and finding a redacted
row from the plaintext you know.

## Where to go next

* [World sessions](/sdk-ts/sessions) to drive one task interactively instead of dispatching a run.
* [Run a task suite](/sdk-ts/run-sessions) to run every scenario against your own agent.
* [Gate a pull request](/sdk-ts/ci) to push, dispatch and gate in one call.
* [What a world is](/worlds) for what versions and refs mean.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.