# Netstate API

Base URL: `https://netstate.co/v1`

Read endpoints are open — no key, no registration. Responses mirror the public
profiles one-to-one: your systems fetch the records; your people review them
and make the decisions.

## Endpoints

| Method | Path | Description | Auth |
| --- | --- | --- | --- |
| GET | `/v1/search?q=&state=&status=&type=&naics=&year=&has=&sort=` | Company search by name, officer or director, phone, email or website — same filters and facet counts as the website | none |
| GET | `/v1/people?q=` | People search — officers and directors grouped by name across the state registers, each with the companies that filed them | none |
| GET | `/v1/meta?country=&region=` | Taxonomy for building queries: countries, regions, cities, industries, statuses | none |
| POST | `/v1/watchlists/{id}/entities` | Follow an entity; changes arrive by webhook or daily digest | Enterprise plan key |

Discovery document: `GET https://netstate.co/v1` returns this list as JSON.

## Examples

Search by company name, officer or director name, or an exact phone number,
email or website — contact-shaped queries resolve through the official records
carrying that value, and the response's `matched_by` field says which channel
matched (`name|phone|email|website`). Filters optional. `state` is a jurisdiction slug ("us-" or
"ca-" plus the two-letter code), `naics` a two-digit sector, `year` a
formation decade (`2020s` … `pre-1980`), `has` a CSV of data-presence
toggles (`officers,ein,naics,phone,revenue`), `sort` one of
`relevance|newest|oldest|name`. Facet counts in the response describe every
name match — not just the filtered set — so they show what widening a filter
would return:

```sh
curl 'https://netstate.co/v1/search?q=summit&state=us-de&status=active&sort=newest'
```

Search hits carry a `profile` link to the company's HTML profile.

Jurisdiction and industry slugs for building queries come from `/v1/meta`:

```sh
curl 'https://netstate.co/v1/meta?country=united-states&region=pennsylvania'
```

## Errors

Errors use one envelope; the message says how to fix the request:

```json
{ "error": { "code": "missing_query", "message": "..." } }
```

## MCP

An MCP server (Streamable HTTP, stateless, no auth) exposes the same data as
tools — `https://netstate.co/mcp`:

```sh
curl -X POST 'https://netstate.co/mcp' -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

## Fair use & restrictions

Read endpoints are rate-limited at the edge; be a good citizen and cache what
you fetch. Watchlists and higher limits ship with the Enterprise plan — contact
hello@netstate.co.

No. Netstate is not a consumer reporting agency, and its data may not be used for any purpose covered by the FCRA — decisions about credit, insurance, employment or housing. It is built for research and business due diligence, where your team reviews the records and makes the call.