Summary

Follow-up to #2758 — extends the snapshot-only sandbox surface so callers can boot from a snapshot name (not just an ID) and so listSnapshots supports server-side filtering and pagination.

Sibling to the Python SDK change: #2769.

Stacked on #2758. GitHub will auto-retarget the base to main once that PR merges.

createSandbox — accept snapshotName

snapshotId becomes optional (positional) and a new snapshotName field is added to CreateSandboxOptions. Exactly one must be provided. To avoid confusion, snapshotId is intentionally not duplicated on the options object.

// By ID (unchanged):
const sandbox = await client.createSandbox(snapshot.id);

// By name — server resolves the snapshot against the caller's tenant:
const sandbox = await client.createSandbox(undefined, {
  snapshotName: "my-snap",
});

Validation throws a LangSmithValidationError if neither (or both) is provided.

listSnapshots — add ListSnapshotsOptions

const all = await client.listSnapshots();
const page = await client.listSnapshots({
  nameContains: "python",
  limit: 10,
  offset: 20,
});

All three options are optional and independent. Omitting them keeps today's zero-arg behavior — the request URL has no query string. The new type is re-exported from the sandbox public index.

Tests (src/tests/sandbox.test.ts)

• createSandbox: new `snapshot_name` payload test + zero-identifier and both-identifier rejection tests.
• listSnapshots: existing zero-arg test extended to assert an empty query string; new test asserts `name_contains`, `limit`, `offset` appear on the request URL.

All 80 sandbox tests pass locally.

README

• Added a `snapshotName` example in the Snapshots section alongside the existing `snapshotId` example.
• Added a `listSnapshots({ nameContains, limit, offset })` example.
• Updated the API Reference rows for `createSandbox` and `listSnapshots`.
• Added a `snapshotName` row to the `CreateSandboxOptions` table.
• Added a new `ListSnapshotsOptions` table.

Breaking changes

None. `createSandbox(snapshotId)` calls keep working unchanged; the positional arg is now optional, but the payload behavior is identical when it is provided.

Made with Cursor