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:

   ( 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' )
   

2. 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."

3. 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.
2. User picks N to fully enrich. POST /unlocks with all of them = 10×N credits, atomic, detail returned.
3. Re-runs within 30-day TTL are free.

Gotchas

• Pin service_provided:public-relations, not industry:pr_comms. The industry value is empty in the live catalog; PR firms sit under adjacent industries. Without the service pin, "tech PR" / "crisis" / "investor relations" keywords leak into general marketing.
• Defer to find-marketing-agency for full-service marketing. When PR is one of several service lines (PR + content + paid + social), the marketing-agency skill is the right fire.
• Sub-types are keyword-only. Multi-word sub-types split into ANDed barewords unless quoted (investor relations → investor AND relations; "investor relations" → one phrase).
• "Write me a press release" / "draft talking points" is do-the-work. Refuse and offer to find a firm if the user wants to engage one.
• Influencer marketing is NOT PR. Influencer marketplaces (Aspire, Grin) and influencer outreach are paid-media work; defer to find-marketing-agency or refuse for marketplace product questions.
• PR-software comparisons (Cision, Muck Rack, Prowly) are NOT procurement.
• Briefs DO include apex, name, location, ratings. They DON'T include url, phone_primary, email_primary, legal_name, address_full, full platforms — those require an unlock.
• not_found / not_in_dataset 404 = not in pro_services. Not charged. Skip.
• Unlock is atomic. 5 apexes either all charge (up to 50 credits) or none charge on 402.
• Within-TTL re-views are free (was_cached:true).

Errors

JSON envelope: {"error": {"code": "...", "message": "..."}}.

Status	Code	What to do
400	filter_parse_error	position included; fix and re-validate with /check.
400	kind_in_filter	Strip any kind: from filter — URL is authoritative.
400	field_not_in_dataset	Drop the disallowed field.
400	invalid_apex	Re-normalize to apex domain.
401	unauthorized / invalid_audience	Re-prompt for fresh vk_….
402	insufficient_credits	needed and balance in payload; nothing charged.
404	not_found / not_in_dataset	Skip; not charged.
429	rate_limited	Honor Retry-After.

End-to-end example

User: "Three tech PR agencies in NY for a Series-B announcement, ideally with 4-star ratings and Fortune 500 client experience."

GET /v1/datasets/pro_services/fields?include_values=1
GET /v1/datasets/pro_services/check?filter=service_provided:public-relations+tech+state:NY+rating>=4
GET /v1/datasets/pro_services/search?filter=...&limit=10
# Present briefs. "Unlocking 3 = 30 credits, 30-day TTL."
POST /v1/datasets/pro_services/unlocks
  { "apexes": ["firm-a.com", "firm-b.com", "firm-c.com"] }
GET /v1/me/credits