https://api.poddata.ai/v1 and the MCP tool that does the same. The examples use a made-up dental group, Northwind Dental, whose id is northwind-dental.
Send the key on every call as Authorization: Bearer $PODDATA_API_KEY, as Keys and limits says. A person confirms each link and each rival: you propose, show, and ask.
1. Take the company
Find it first, so you take the company PodData holds rather than making a second of the same name.company id if PodData holds it, or by its name and its own website’s domain if not. A company that files with the SEC can be added by its ticker instead, and PodData reads its filings.
201 is a new target; 200 means it was one already. Tools: find_company, add_target, and list_targets for the team’s targets.
2. Its links
PodData reads a company only through its links: its domain, its places on Google, its listings on review sites and marketplaces, its accounts, its numbers at registries.POST /targets/{company}/find reads the company’s own site and proposes each account its pages link to, and lists the addresses on its location pages.
GET /companies/{id}/links lists every link, each proposed, confirmed or struck, with the page that shows it’s theirs. Propose one PodData missed, such as a Google place you matched to an address, with POST /companies/{id}/links:
find_links, company_links, propose_link.
3. Its rivals
POST /targets/{company}/rivals/find tests candidates like for like: from a list the person gives, from what PodData holds, and from stories that name the target. It reads each candidate’s own site, and two models of different families each say what it sells, to whom and where. Only a rival both agree on is proposed; every other candidate comes back in left_out with why.
verdict, the words of its own page that show it (shows), and overlap: the codes, towns and words the two firms share that no model said. supported: false marks a rival only the models’ reading backs: say so to the person. GET /companies/{id}/rivals lists them; propose one the person names with POST /companies/{id}/rivals. Tools: find_rivals, company_rivals, propose_rival.
If it’s refused with a 400 asking for about, the target’s own site couldn’t be read: ask the person what the company sells, to whom and where, and send it as about.
4. A person says yes to each
Show the person each proposed link and rival, with its page and why, and ask. Only on their yes, confirm it; on their no, strike it withwhy. Never confirm one on your own.
/companies/bluebird-dental/links, or propose them from its site with POST /targets/{company}/find and {"rival": "bluebird-dental"}. Links and rivals already confirmed stay confirmed: ask only about what’s still proposed.
A 409 on a confirm means the value is confirmed for another company already. Show the person the message: if the two are the same company, it says how to take that one.
5. The read
Each source reads on its own cadence, a day or a week for most. Ask PodData to read the target and its confirmed rivals now:202 lists the sources queued for the target and for each rival, and those waiting on a kind of link no one has confirmed. Each queued source takes it first on its next run, within the quarter hour. 200 with nothing queued means no source here can read it yet: confirm more links.
Then GET /targets/{company}/coverage says, source by source, where each stands (read, due, waiting and the rest), what it holds and over which days, and the same for each confirmed rival:
read says where the read you asked for stands, for the target and, under rivals, for each rival:
going: sources still to run.leftlists each, with why.done: every source it queued has run since you asked. Go on.held: each source still to run is stopped at its cap for the day.leftgivesopens, when each starts again, at midnight UTC: come back then, or go on with what’s held.
read.why says all of it in a sentence. To wait, ask coverage again every five minutes or so, never faster. Tools: read_target, target_coverage.
A 403 with the code plan means the team’s reads for the day are used up: tell the person, and work with what’s held.
6. The report
A report has an overview and five pages: customer, competitive, news, trends and expert. Make one:dlr_…) and its version (rev). Then write it yourself, by the diligence skill:
- Plan two questions a page, as a buyer would ask them.
- Ask a number tool for each figure, such as
GET /companies/{id}/numbers/rating-rivals. Never add up rows yourself. See Number tools. - Save each page with
PUT /diligence-reports/{id}/pages/{page}, its copy citing each figure in braces,{customer-1.average}, from an exhibit that saves the tool’s question. See A diligence report. - Check it with
POST /diligence-reports/{id}/check, and fix what it refuses, until it refuses nothing. - Read it with every figure filled with
GET /diligence-reports/{id}, or download it as Markdown with?format=md, or as a zip of its pages, each exhibit’s rows as CSV and its evidence with?format=zip.
start_report, save_report_page, check_report, get_report, list_reports.
Or have PodData’s own agent write it. PodData pays for its turns, so ask the person first:
202 with the run, which goes on in the background: an agent a page, one for the overview, then the check. Read it with GET /diligence-runs/{id} every minute or so until its status is done, stopped, capped, refused or failed, then read the report. With message, a run makes that one change and leaves the rest. One run of a report at a time: a second is a 409 that names the first. A plan sets how many runs a key starts a UTC day, and past them it’s a 429 with Retry-After. Tools: start_report_run, get_report_run, list_report_runs.
7. Save everything
GET /targets/{company}/folder is the index of everything held for the target, each confirmed rival, and its parent and comparables: for each source and kind, how many rows, their days, a CSV address (file) and a JSON address (rows), and why a file is held back where one is. ?format=zip is the folder’s files in one zip. See A target’s folder.
The skill’s puller does it all in one command, with Node 18 or later and the key in PODDATA_API_KEY:
northwind-dental/, with target/, rivals/<id>/, parent/<id>/ and comparables/<id>/, each with its records, signals, documents, site and ads, then the quotes, the team’s licensed figures, each report as JSON, index.json, coverage.csv, a manifest.json of every file and a README.md of what’s there and what was left out and why. It keeps under the key’s limits, can be run again and fetches only what changed, and never prints or saves the key.