> ## 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.

# API quickstart

> A short tutorial for finding source-backed civic actors with the Atlas API.

## Goal

In this tutorial, you will answer one practical question with the public API:

> Who is working on housing in Kansas City, and what sources back the results?

You do not need an account for this tutorial.

## 1. Check that Atlas is reachable

```bash theme={null}
curl https://atlas.rebuildingus.org/health
```

The health endpoint is outside the `/api` base path. The data endpoints below
use:

```text theme={null}
https://atlas.rebuildingus.org/api
```

## 2. Search from the place

Start with the place because the question is local.

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://atlas.rebuildingus.org/api/places/kansas-city,missouri/entities?issue_area=housing_affordability"
  ```

  ```python Python theme={null}
  import httpx

  response = httpx.get(
      "https://atlas.rebuildingus.org/api/places/kansas-city,missouri/entities",
      params={"issue_area": "housing_affordability"},
  )

  for actor in response.json()["data"]:
      print(actor["name"], actor["type"])
  ```

  ```typescript TypeScript theme={null}
  const params = new URLSearchParams({
    issue_area: "housing_affordability",
  });

  const response = await fetch(
    `https://atlas.rebuildingus.org/api/places/kansas-city,missouri/entities?${params}`,
  );

  const { data } = await response.json();
  for (const actor of data) {
    console.log(actor.name, actor.type);
  }
  ```
</CodeGroup>

Place-first search is usually better than broad keyword search when your user
already knows the city, county, or region they care about.

## 3. Pick one result and inspect its sources

Copy one entity id from the search response, then ask for its sources.

```bash theme={null}
curl "https://atlas.rebuildingus.org/api/entities/{entity_id}/sources"
```

Before you reuse the result, check:

* Does the source actually say what you plan to repeat?
* Is the source recent enough for your use?
* Is the record backed by more than one independent source?
* Is the actor type right for your workflow?

This is the most important habit in Atlas API usage: carry evidence forward
with the record.

## 4. Add place context

Coverage endpoints help you decide whether your result set is broad enough.

```bash theme={null}
curl "https://atlas.rebuildingus.org/api/places/kansas-city,missouri/coverage"
```

Use coverage as context, not a final verdict. Thin coverage may mean Atlas has
not found enough public sources yet, or it may reveal a real local gap.

## 5. Decide whether you need authentication

You can browse public directory data without credentials. You need credentials
when your workflow does one of these:

* Starts or syncs discovery runs.
* Writes, updates, or imports records.
* Uses workspace briefs, lists, watches, private review, or usage proof.
* Needs higher API limits.

For server-side integrations, create an API key. For AI assistants, connect the
MCP server and let the client handle OAuth.

## 6. Keep the generated reference nearby

This tutorial shows the model and the workflow. Use the generated reference for
exact parameters and response shapes.

<CardGroup cols={2}>
  <Card title="API reference" icon="code" href="/docs/api/reference">
    Search exact endpoints, parameters, and schemas.
  </Card>

  <Card title="Authentication" icon="key" href="/docs/api/authentication">
    Choose API keys or OAuth for protected workflows.
  </Card>

  <Card title="Find source-backed actors" icon="users" href="/docs/api/guides/entities">
    Learn the safe search and evidence pattern.
  </Card>

  <Card title="Connect an AI assistant" icon="robot" href="/docs/mcp/overview">
    Use the same data through Claude, Copilot, Gemini, or Codex.
  </Card>
</CardGroup>