find-pr-agency

find-pr-agency

Drive the ServiceGraph API (https://api.servicegraph.co) to find, shortlist, and enrich US PR and communications agencies via the pro_services dataset.

Always pin service_provided:public-relations. Note: the catalog's nominal industry:pr_comms value returns zero firms in the live release — PR/comms firms are tagged with service_provided:public-relations instead, typically under adjacent industries (marketing_agency, other_pro_services). Pin the service tag, not the industry. Sub-types (media relations, crisis, IR, public affairs, healthcare PR, tech PR, B2B PR, internal comms, brand reputation) are NOT separate tags — sub-type specialization is a keyword substring search on firm text.

Any HTTP client works (curl, fetch, requests). Examples below use curl.

Sibling skills — defer when scope is broader

If the user wants a multi-service marketing engagement (PR plus content plus paid plus social), defer to find-marketing-agency — that skill covers full-service shops where PR is one of several service lines.

This skill is correct when PR/comms is the primary deliverable — launches, media relations, crisis, IR, public affairs.

When NOT to use this skill

• "Write me a press release / draft these talking points" → DIY work.
• In-house comms/PR hires (Head of Comms, PR Manager).
• PR-software comparisons (Cision, Muck Rack, Prowly).
• Influencer-marketplace asks — that's paid media; defer to find-marketing-agency or refuse for marketplace product questions.
• "Explain how earned media works" → knowledge question.
• Non-US firms.
• Individual freelance PR people / publicists.

MCP server (preferred for authed calls)

If your harness has the ServiceGraph MCP server loaded (tools containing servicegraph in the name), prefer those — credentials stay in the harness's OAuth 2.1 + PKCE sandbox and no token enters LLM context. Otherwise use the REST flow below.

API surface (dataset id: pro_services)

Every endpoint requires the bearer (Authorization: Bearer vk_…). No anonymous tier.

| Endpoint | Cost | Use it for | |---|---|---| | GET /v1/datasets/pro_services/fields[?include_values=1] | free | Confirm public-relations is in the service_provided value list. | | GET /v1/datasets/pro_services/check?filter=… | free | Validate filter. | | POST /v1/datasets/pro_services/translate-intent | free | {intent} → LLM-generated DSL filter + sanity count. | | GET /v1/datasets/pro_services/search?filter=…&limit= | free | Brief firm cards + per-row unlock hint + total. | | GET /v1/datasets/pro_services/:apex | free | One row brief; detail only if unlocked. | | POST /v1/datasets/pro_services/unlocks | 10 credits / firm | {apexes:[...]} ≤100; atomic; 30-day TTL on detail. | | GET /v1/me/credits | free | Balance. |

Cost model. Discovery / validation / search / brief reads are free. Detail (url, phone, email, social, address, full platforms map) costs 10 credits per firm and lasts 30 days.

Auth

Tokens are vk_* API keys minted in the dashboard. Keep the token out of the LLM context — never read .env* files; dispatch every authed call through a shell wrapper.

1. Try the call first through a shell wrapper that sources

.env.local:

``bash ( set -a; [ -f .env.local ] && . ./.env.local; set +a; curl -sS -H "Authorization: Bearer $SERVICEGRAPH_API_KEY" \ 'https://api.servicegraph.co/v1/datasets/pro_services/fields' ) ``

1. On 401 unauthorized, prompt the user:

> "Open https://servicegraph.co/profile/api-keys, create a > key, and add SERVICEGRAPH_API_KEY=vk_… to .env.local here > (or export it in your shell). Tell me when done. Please don't > paste the key into chat."

1. Retry after the user signals ready.

Filter DSL

GitHub-search-style.

filter   := orExpr
orExpr   := andExpr ("OR" andExpr)*
andExpr  := notExpr (("AND")? notExpr)*    # whitespace = implicit AND
notExpr  := ("NOT" | "-") notExpr | atom
atom     := "(" filter ")" | predicate
predicate:= IDENT op valueOrList | bareword
op       := ":" | "=" | ">=" | "<=" | ">" | "<"
valueOrList := value ("," value)*
value    := IDENT | NUMBER | tagAtEvidence
tagAtEvidence := IDENT "@" ("low"|"medium"|"high")
bareword := IDENT | NUMBER          # → keyword:<bareword>

Four rules that bite: AND binds tighter than OR (use parens); comma list = OR within one predicate; negation is -x or NOT x (no negative literals inside comma lists); bareword = keyword search (multi-word phrases must be quoted or split).

PR-flavored examples (validate yours with /check):

service_provided:public-relations tech state:NY
service_provided:public-relations healthcare
service_provided:public-relations b2b saas
service_provided:public-relations crisis
service_provided:public-relations "investor relations"
service_provided:public-relations ipo state:NY,CA
service_provided:public-relations "public affairs" state:DC
service_provided:public-relations rating>=4 has:clutch

Sub-type / vertical → keyword mapping:

| User asks for | Add as keyword(s) | |---|---| | Tech / startup PR | tech, startup, saas | | Healthcare / pharma PR | healthcare, pharma, biotech | | Crisis comms | crisis | | Investor relations / IR | "investor relations", ir, ipo | | B2B PR | b2b | | Public affairs | "public affairs" | | Brand reputation | "brand reputation", reputation | | Internal communications | "internal communications", "internal comms" | | Earned media / media relations | "earned media", "media relations" |

Identifying firms — apex

Firms are identified by their apex domain (edelman.com, not www.edelman.com/about).

Recipes

A. Tech PR for a Series-B announcement

User: "Tech PR agency in NY for our Series-B announcement."

GET /v1/datasets/pro_services/search?filter=service_provided:public-relations+tech+state:NY&limit=10
# → 10 brief cards + total + per-row unlock.status

# Present, get pick of 3. "Unlocking 3 = 30 credits, 30-day TTL."
POST /v1/datasets/pro_services/unlocks
  { "apexes": ["firm-a.com", "firm-b.com", "firm-c.com"] }

B. IR firms for an IPO

User: "Three IR firms for our upcoming IPO roadshow."

GET /v1/datasets/pro_services/search?filter=service_provided:public-relations+("investor relations" OR ir)+ipo&limit=10

C. Crisis comms (urgent)

User: "Crisis comms help — brand reputation issue blowing up online."

GET /v1/datasets/pro_services/search?filter=service_provided:public-relations+crisis&limit=10

Skip the validation hop and present briefs immediately given the urgency.

D. Healthcare / regulatory PR

User: "Healthcare PR agency familiar with FDA regulatory comms."

GET /v1/datasets/pro_services/search?filter=service_provided:public-relations+healthcare+(fda OR regulatory)&limit=10

E. Indirect intent — "we need press"

User: "We need press for our Series-B — get us into TechCrunch, WSJ, and the trade press."

That's product-launch / tech PR. Either translate by hand:

GET /v1/datasets/pro_services/search?filter=service_provided:public-relations+(tech OR startup)+(launch OR series-b)&limit=10

…or hand the intent off:

POST /v1/datasets/pro_services/translate-intent
  { "intent": "PR agency to get our Series-B into TechCrunch and trade press" }

If thin, drop the launch/series-b keyword — most tech PR firms run launches as a default deliverable.

F. Public affairs (state government)

User: "Public affairs firms with state-government experience in California."

GET /v1/datasets/pro_services/search?filter=service_provided:public-relations+"public affairs"+state:CA&limit=10

G. BYO apex list — enrich domains

User pastes 8–20 PR-firm domains:

1. GET /v1/datasets/pro_services/:apex per domain — free brief

(404 = not in catalog, no charge). Flag misses.

1. User picks N to fully enric