> ## Documentation Index
> Fetch the complete documentation index at: https://docs.poddata.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# A diligence report

> A report's shape, how a figure and an exhibit work, what the check refuses, and how a report is read and shared.

A diligence report answers what a buyer would ask about a company, page by page, each figure from what PodData read and each page saying how it was built. Your own assistant writes it a page at a time, or PodData's agent does.

## Its shape

A report has a `title`, an `overview` and five `pages`, in this order:

| Page | Id |
| - | - |
| Customer analysis | `customer` |
| Competitive analysis | `competitive` |
| Strategic news | `news` |
| Industry trends | `trends` |
| Expert insights | `expert` |

The overview has a `bottom_line`, three stat `cards` and the `first_question` to ask. Each page has:

* `state`: `empty`, `written`, or `waits` when it can't be written yet and its method says why
* `headline`, which states the finding, and a `lede`
* `read`: what was read, as figures, such as reviews read
* `questions`: two, each with its `ask`, its `answer` in a line and up to three stat `cards`
* `exhibits`: up to 12, each a saved question to a number tool
* `quotes`: up to 30 quotes, reviews, passages or records it cites, by id
* `method`: what was read, over which window (`from`, `to`), and what was left out and why
* `names`: the companies, brands, places and sources it names, which the check reads as words

## A figure and an exhibit

Copy never holds a typed number. It cites a figure in braces, `{exhibit.figure}`, and the figure comes from an exhibit on the page:

```json theme={null}
{
  "id": "customer-1",
  "numbers": "rating_rivals",
  "company": "northwind-dental",
  "params": { "source": "google-maps", "from": "2025-11-14", "to": "2026-11-14" },
  "show": "bars",
  "title": "Google rating, against its confirmed rival",
  "point": "Northwind trails Bluebird by three tenths of a star.",
  "caveat": null
}
```

`numbers` is a number tool, `company` the target or a confirmed rival, and `params` the tool's own arguments. Each time the report is read, PodData asks the tool again and puts its figure in place of the braces, so `"Patients rate Northwind {customer-1.average} stars"` reads `"Patients rate Northwind 4.3 stars"`. See [Number tools](https://docs.poddata.ai/number-tools.md) for each tool's figures.

## Write it

1. `POST /diligence-reports` with `company` makes one, with five empty pages. The answer gives its `id` and `rev`.
2. `PUT /diligence-reports/{id}/pages/{page}` saves one page, with `rev` and `page`; for the overview, `overview` is the page and the field. A page is saved whenever it fits the shape, whatever the check says, and the answer is the report filled, with what the check finds now.
3. A `409` on a save means someone saved over the version you read. Read the report again with `GET /diligence-reports/{id}`, and change only what you were asked.
4. `POST /diligence-reports/{id}/check` runs the check and marks the report `checked` when it refuses nothing.

Tools: `start_report`, `save_report_page`, `check_report`, `get_report`. `get_report` with `page` gives one page as saved, in JSON, to change only what you're asked and keep the rest.

## What the check refuses

The check refuses a report that would say more than PodData read. Among what it refuses:

* a figure in braces that no number tool gave, or braces that don't hold one
* an exhibit with no evidence, or whose evidence comes through a link no one confirmed
* a company compared that isn't the target or a rival a person confirmed
* a page that doesn't say what was read and over which window, or that waits without saying why
* an empty page, a page without its two questions, an overview without its three cards

It advises, without refusing, on an exhibit with no caveat when its tool's answer gives one. Each problem comes with where it is (`pages.0.exhibits.1`) and why.

## Read it

```bash theme={null}
curl -s https://api.poddata.ai/v1/diligence-reports/dlr_01JD9K4M5N6P00000000000000 -H "Authorization: Bearer $PODDATA_API_KEY"
```

The answer is one JSON object: the report as stored (`report`), the same with each figure in its place (`filled`), each exhibit's number tool asked now (`answers`), each item a page cites looked up by its id, at most 80 words (`cited`), and what the check says (`check`). Since each read asks every tool again, a saved copy is that moment's.

### As files

`format` downloads the report as files, every figure filled as it reads now:

* `?format=md`: one Markdown document, the overview and then each page, with its exhibits as tables, its quotes and how it was built.
* `?format=zip`: `poddata-report-<company>-<day>.zip`, holding `report.json`, `report.md`, a Markdown file a page under `pages/`, each exhibit's rows and its figures as CSV and its answer as JSON under `exhibits/`, `evidence.csv`, `cited.csv`, and a `README.txt` of what each file is.

```bash theme={null}
curl -s 'https://api.poddata.ai/v1/diligence-reports/dlr_01JD9K4M5N6P00000000000000?format=zip' \
  -H "Authorization: Bearer $PODDATA_API_KEY" -o northwind-dental-report.zip
```

A draft downloads too, marked a draft with how many things the check refuses. In a file, a figure read through your team's own licence is left out with why, and a source's words stay at most 80 in a row. Each download is one call. No MCP tool hands over a file: `get_report` answers the report as JSON.

`GET /diligence-reports` lists the team's reports, newest change first, each with its status and where each page stands.

## PodData's agent

PodData's own agent writes a first draft, or with `message` makes a change a person asks for: `POST /diligence-reports/{id}/runs`, from a key, an assistant signed in, or the workspace. PodData pays for its turns, up to the run's cap (`cap_usd`), so an assistant asks the person before it starts one. `GET /diligence-reports/{id}/runs` lists a report's runs, and `GET /diligence-runs/{id}` gives one with each agent's turns and what it cost. Tools: `start_report_run`, `list_report_runs`, `get_report_run`. A run ends `done`, `stopped`, `capped` when it reached its cap with pages left, `refused` or `failed`.

## Share it

A person signed in to the workspace can make a private link to a checked report, for someone outside the team, and turn it off. A key can't: the link's address is shown only once, in the workspace. A figure read through your team's own licence never goes out by a link.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.