# ServiceGraph

> Structured catalog of 100k+ US professional-services firms (law, marketing, consulting, accounting, IT services, architecture, engineering, HR, PR, design). Pluggable into AI agents as a one-line skill install or callable directly over HTTP.

ServiceGraph helps AI agents answer requests like "find me three boutique IP law firms in California" or "build a longlist of 50 mid-size US consulting firms with both strategy and operations practices" by driving a structured catalog with a filter DSL — no web scraping, no fuzzy matching.

## For AI-agent owners

- [Install as a Claude Code skill](https://github.com/nostrband/servicegraph): `npx skills add https://github.com/nostrband/servicegraph --skill find-service-providers`
- [Skill source code](https://github.com/nostrband/servicegraph)
- [Sample prompts (eval set)](https://github.com/nostrband/servicegraph/blob/main/eval/find-service-providers/queries.json)

## API

- API base: https://api.servicegraph.co
- [OpenAPI 3.1 spec](https://api.servicegraph.co/openapi.json)
- [Field catalog (DSL fields, kinds, values)](https://api.servicegraph.co/v1/tags)
- [Console & full docs](https://docs.servicegraph.co)

## Endpoints (summary)

- `GET /v1/tags` — public; describes every filterable field, its kind, allowed operators, and (optionally) values
- `GET /v1/check?filter=...` — public; validates a filter string without executing it
- `GET /v1/explore?filter=...` — public; counts and sub-tag breakdowns under a filter, suppressed below k=20
- `POST /v1/auth/request-otp` + `POST /v1/auth/verify-otp` — public; email + 6-digit code → 90-day bearer token
- `GET /v1/search?filter=...` — bearer; brief firm cards (no apex/url/contact); 200 unique-firm-views/month free
- `GET /v1/get/:id` — bearer; full bundle (url, phone, email, social, legal name, address); 50/month free; firm_id = sha256(apex.lower().rstrip('.')).hexdigest()[:12]

## Filter DSL (one query parameter)

GitHub-search-style. AND binds tighter than OR; `-x` or `NOT x` for negation; `tag@evidence` qualifier for the service_provided field. Any bareword (a word or number with no operator) becomes a free-text keyword search across firm name, brand, title, meta description, and legal name.

Examples:

- `industry:legal state:CA,NY -company_size_signal:solo`
- `industry:management_consulting service_provided:strategy-consulting@high`
- `dental industry:marketing_agency`
- `rating>=4 review_count_total>=20 has:clutch`
- `(web3 OR blockchain) state:CA`

## Optional

- [Site](https://servicegraph.co)
- Contact: artur@servicegraph.co