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

# Client

> The generated TypeScript client for the Worlds Data API.

The Worlds Data API client (`@worlds/client`) is a typed HTTP client generated
from the canonical
[Worlds Data API OpenAPI document](https://worlds-api.wazoo.dev/openapi.json).
It mirrors the management-plane client pattern: `@wazoo/client` talks to the
platform API, `@worlds/client` talks to the data plane.

Use it for remote data-plane operations: world lifecycle, import, export,
search, SPARQL, and reindexing against `worlds-api.wazoo.dev`.

For an embeddable, provider-swappable interface over the same operations, use
the [Worlds SDK](/platform/typescript-sdk) instead.

## Install

```sh theme={null}
npx jsr add @worlds/client
```

## Create a client

Data-plane requests authenticate with a `wzw_` world token:

```ts theme={null}
import { createClient, listWorlds } from "@worlds/client";

const client = createClient({
  baseUrl: "https://worlds-api.wazoo.dev",
  auth: process.env.WORLDS_TOKEN,
});
```

## List worlds

```ts theme={null}
const response = await listWorlds({ client });

for (const world of response.data?.worlds ?? []) {
  console.log(world.uid, world.displayName);
}
```

## Search

The data-plane search endpoint performs hybrid retrieval across a world:

```ts theme={null}
import { searchWorld } from "@worlds/client";

const response = await searchWorld({
  client,
  path: { id: "w_<uuid>" },
  body: { query: "Ethan's manager", limit: 5 },
});

for (const result of response.data?.results ?? []) {
  console.log(result.subject, result.content);
}
```

Results return the matching subject and predicate IRIs plus the literal
`content`, so an agent can bind the exact entity before running
[SPARQL](/worlds/query).

## Import data

```ts theme={null}
import { importWorld } from "@worlds/client";

const response = await importWorld({
  client,
  path: { id: "w_<uuid>" },
  body: {
    data: '(<urn:subject> <urn:predicate> "object") .',
    contentType: "text/turtle",
  },
});
```

## SPARQL

```ts theme={null}
import { sparqlWorld } from "@worlds/client";

const response = await sparqlWorld({
  client,
  path: { id: "w_<uuid>" },
  body: { query: 'SELECT ?s WHERE { ?s <urn:predicate> "object" }' },
});
```

## Export and reindex

```ts theme={null}
import { exportWorld, reindexWorld } from "@worlds/client";

const exported = await exportWorld({ client, path: { id: "w_<uuid>" } });
const reindexed = await reindexWorld({ client, path: { id: "w_<uuid>" } });
```

## Self-hosting

Point the client at a self-hosted Worlds Data API instance by overriding
`baseUrl`:

```ts theme={null}
const client = createClient({
  baseUrl: "https://worlds.example.com",
  auth: process.env.WORLDS_TOKEN,
});
```

## Generated code

The package is generated with `@hey-api/openapi-ts` from a committed OpenAPI
snapshot in the
[`wazootech/worlds-client-ts`](https://github.com/wazootech/worlds-client-ts)
repository. Run `deno task sync:openapi` to refresh the snapshot, and
`deno task generate` to regenerate `src/generated/`. CI fails if the checked-in
snapshot drifts from the canonical document.