# OpenStoop API documentation

OpenStoop provides building health intelligence for NYC buildings using public records, building grades, event histories, and property facts.

Base URL:

```text
https://openstoop.com/api/v1
```

## Authentication

Use API credentials provided by OpenStoop. Bearer authentication is preferred:

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://openstoop.com/api/v1/buildings/1004700039
```

## Core endpoints

### Health check

```text
GET /api/v1/health
```

Checks whether the API is available.

### Building lookup

```text
GET /api/v1/buildings/{bbl}
```

Returns one building report with address, BBL, borough, units, grade, score components, event counts, confidence, and links to related resources.

### Batch building lookup

```text
POST /api/v1/buildings/batch
```

Looks up multiple BBLs in one request.

### Building search

```text
GET /api/v1/buildings/search
```

Searches by address, owner, zip code, building class, grade, or score filters.

### Building events

```text
GET /api/v1/buildings/{bbl}/events
```

Returns paginated public-record events for a building, including violations, complaints, permits, litigation, liens, and related data where available.

## Common AI agent tasks

### Check a NYC building before a lease

Use:

```text
GET /api/v1/buildings/{bbl}
GET /api/v1/buildings/{bbl}/events
```

Present the grade, top risk drivers, recent/open severe events, and caveats. Do not describe a grade as a legal finding.

### Compare multiple buildings

Use:

```text
POST /api/v1/buildings/batch
```

Compare grade, health score, open severe violations, complaint burden, and confidence.

### Investigate building-event history

Use:

```text
GET /api/v1/buildings/{bbl}/events
```

Filter by source, severity, category, and date where supported.

## Safe interpretation rules

Use OpenStoop as a public-records decision-support source.

- Scores summarize public-record risk signals.
- Scores are not legal findings.
- Scores are not safety certifications.
- Building-level results are not unit-specific guarantees.
- Complaints are reports and may not be confirmed violations.
- Always preserve source caveats and dates.

## Related resources

- Human-readable API docs: https://openstoop.com/api-docs
- Methodology: https://openstoop.com/methodology
- Agent-readable methodology: https://openstoop.com/methodology.md
- LLM site map: https://openstoop.com/llms.txt