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

# Generate a TypeScript client

> Use the Atlas OpenAPI contract to generate typed TypeScript functions for integrations.

## Overview

Atlas does not need a separate hand-written SDK to be useful from TypeScript.
The source of truth is the OpenAPI contract, which also powers the generated
Scalar reference.

Use this page when you want typed functions in a TypeScript project and you are
comfortable generating a client from the Atlas repo.

<Note>
  The generated client is built with Orval from `openapi/atlas.openapi.json`. It
  is repo-local output, not a separately versioned npm package.
</Note>

## When to generate a client

Generate a TypeScript client when:

* You are building inside the Atlas app.
* You want compile-time help for request and response shapes.
* You need to keep a branch aligned with the current OpenAPI contract.

For one-off scripts, direct `fetch` calls may be clearer. For exact function
names and types, inspect the generated file after generation.

## Generate the client

```bash theme={null}
git clone https://github.com/RebuildingAmerica/atlas.git
cd atlas/app
pnpm install
pnpm api-client
```

The generated output lives at:

```text theme={null}
app/src/lib/generated/atlas.ts
```

## Use it safely

Import only the functions your workflow needs, and keep source evidence attached
to any records you export.

```typescript theme={null}
import { listPlaceEntities, listEntitySources } from "./lib/generated/atlas";

const result = await listPlaceEntities("kansas-city,missouri", {
  issue_area: ["housing_affordability"],
});

for (const actor of result.data) {
  const sources = await listEntitySources(actor.id);
  console.log(
    actor.name,
    sources.data.map((source) => source.url),
  );
}
```

If you need an API key, pass headers through the generated function options:

```typescript theme={null}
await listPlaceEntities(
  "kansas-city,missouri",
  { issue_area: ["housing_affordability"] },
  { headers: { "X-API-Key": process.env.ATLAS_API_KEY ?? "" } },
);
```

Do not ship API keys in browser bundles.

## Keep generated code in sync

When backend API behavior changes, regenerate from the backend, then regenerate
the app client:

```bash theme={null}
pnpm run openapi
cd app
pnpm api-client
```

OpenAPI JSON files are generated artifacts. Do not hand-edit them to make a
TypeScript compile error disappear.

## Related docs

<CardGroup cols={2}>
  <Card title="API reference" icon="code" href="/docs/api/reference">
    Inspect exact endpoint and schema names.
  </Card>

  <Card title="Authentication" icon="key" href="/docs/api/authentication">
    Decide how the generated client should authenticate.
  </Card>

  <Card title="API quickstart" icon="rocket" href="/docs/api/quickstart">
    Try the underlying requests before wrapping them in a generated client.
  </Card>

  <Card title="Find source-backed actors" icon="users" href="/docs/api/guides/entities">
    Keep source evidence attached when using generated functions.
  </Card>
</CardGroup>