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

# Build with the Atlas API

> How the Atlas API fits into civic research workflows, and when to use the generated endpoint reference.

## Overview

Use the Atlas API when source-backed civic data needs to move into another
workflow: a newsroom research notebook, a nonprofit CRM, a local directory, a
coverage dashboard, or an agent that needs structured context.

Start with these guides when you need the model, workflow shape, and evidence
patterns. Use the generated reference for exact parameters, request bodies,
response schemas, and status codes.

<Card title="REST API reference" icon="code" href="/docs/api/reference">
  Search endpoints, schemas, authentication requirements, and request examples.
</Card>

## The API in one picture

Atlas has four API surfaces that fit together:

| Surface              | Use it for                                                                                      | Start here                                    |
| -------------------- | ----------------------------------------------------------------------------------------------- | --------------------------------------------- |
| Public directory     | Search people, organizations, initiatives, campaigns, events, places, sources, and issue areas. | [Find actors](/docs/api/guides/entities)           |
| Workspace workflows  | Build briefs, lists, watches, usage proof, private review, and Scout sync handoffs.             | [Workspace visibility](/docs/api/guides/workspace) |
| Firehose             | Query, probe, or observe source-backed civic signals through snapshots, SSE, and WebSockets.    | [Firehose protocol](/docs/api/guides/firehose)     |
| Discovery and agents | Start hosted discovery runs, run Scout locally, or use MCP through an assistant.                | [Discovery and Scout](/docs/api/guides/discovery)  |

If you only need exact field names, open the generated reference. If you need to
understand what the data means and how to use it without stripping evidence,
start with the guides.

## The core model

Atlas records are not just rows. A useful API response usually contains three
ideas:

* **Actors** — people, organizations, initiatives, campaigns, and events.
* **Context** — places, issue areas, source types, source freshness, and related actors.
* **Evidence** — source URLs, publications, dates, and extraction context that explain why Atlas knows something.

The evidence is not decoration. If you export a record, brief a team, feed an
agent, or import a contact into another system, preserve the source trail that
supports the claim you plan to use.

## Choose the right starting point

Use **place-first search** when the question starts with a community:

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

Use **entity search** when the question starts with a name, type, keyword, or
broader geography:

```bash theme={null}
curl "https://atlas.rebuildingus.org/api/entities?query=tenant%20union&state=MO"
```

Use **sources** before reuse:

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

Use **workspace APIs** only when private team context, lists, briefs, watches, or
review states are part of the workflow.

## Authentication model

Many read-only directory endpoints are public. API keys and OAuth are for higher
volume access, discovery runs, writes, workspace data, and MCP clients.

For most scripts and server-side integrations, use an API key. For compliant MCP
clients and assistant workflows, use the OAuth flow the client starts from the
MCP server URL.

Read [authentication](/docs/api/authentication) before building anything that writes
data, starts discovery, or accesses a workspace.

## What not to copy into your integration

* Do not treat a matching record as a verified recommendation without reading sources.
* Do not drop source URLs or extraction context when exporting records.
* Do not publish private workspace notes as public evidence.
* Do not assume a discovery run result is ready for outreach just because the run completed.
* Do not duplicate the generated reference in your own docs; link to it for exact shapes.

## Next steps

<CardGroup cols={2}>
  <Card title="Tutorial: make your first call" icon="rocket" href="/docs/api/quickstart">
    Follow a short place-first workflow from search to source review.
  </Card>

  <Card title="Find source-backed actors" icon="users" href="/docs/api/guides/entities">
    Search entities and preserve evidence in downstream tools.
  </Card>

  <Card title="Understand place data" icon="map" href="/docs/api/guides/places">
    Use profiles, coverage, signals, and source lists together.
  </Card>

  <Card title="Observe civic signals" icon="radio" href="/docs/api/guides/firehose">
    Query snapshots, open streams, and keep protocol contracts in sync.
  </Card>

  <Card title="Generated reference" icon="code" href="/docs/api/reference">
    Check exact endpoint parameters and response schemas.
  </Card>
</CardGroup>