Generate a TypeScript client

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.

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

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

git clone https://github.com/RebuildingAmerica/atlas.git
cd atlas/app
pnpm install
pnpm api-client

The generated output lives at:

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.

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:

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:

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.

API reference

Inspect exact endpoint and schema names.

Authentication

Decide how the generated client should authenticate.

API quickstart

Try the underlying requests before wrapping them in a generated client.

Find source-backed actors

Keep source evidence attached when using generated functions.

API

MCP and agents

Workspace access

Tutorials

Open source

Generate a TypeScript client

Overview

When to generate a client

Generate the client

Use it safely

Keep generated code in sync

API reference

Authentication

API quickstart

Find source-backed actors

​Overview

​When to generate a client

​Generate the client

​Use it safely

​Keep generated code in sync

​Related docs

API reference

Authentication

API quickstart

Find source-backed actors

Overview

When to generate a client

Generate the client

Use it safely

Keep generated code in sync

Related docs