> ## Documentation Index
> Fetch the complete documentation index at: https://docs.auditynow.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Running an Audit End-to-End
> The full agent recipe for taking a client from intake to deliverables, in one prompt.
## The shape of an Audity audit
Every audit follows the same arc:
1. **Create the project** with client info
2. **Add documents and intake context** (skipped if you only have a client name)
3. **Trigger the audit analysis**, this is the expensive AI synthesis pipeline
4. **Fetch the deliverables**, opportunities, risks, stakeholder memos, executive summary
An agent can drive all four steps in a single conversation.
## The minimum viable audit
For a fast read on a client when you only have basic info:
```text theme={null}
Start an Audity project for {client_name}, {industry}, {company_size}.
Then run the audit analysis. When it's done, summarize the top 5 opportunities
ranked by impact, and flag any high-severity risks.
```
What the agent actually does:
```json theme={null}
{
"clientName": "Acme Corp",
"industry": "Manufacturing",
"companySize": "200-500",
"currency": "USD"
}
```
Returns `{id, status: "setup"}`. Deducts 1,000 credits.
For curl or server-side clients, `POST /api/projects/{id}/audit-analysis` runs the synthesis pipeline **synchronously**. The HTTP request blocks for 60-300 seconds, so set client timeouts to at least 360s.
For projects that already have current document and interview analysis records, short-timeout clients can use `POST /api/agent/projects/{id}/audit-analysis/async`, then poll `GET /api/agent/jobs/{jobId}` until the job is `completed` or `failed`.
Returns `{ opportunities: [...] }` (wrapped). Each opportunity has `impactScore` (1-10),
`effortScore` (1-10), `category`, `roiPotential`, `implementationTimeline`. The agent ranks/summarizes.
Returns `{ success: true, data: DashboardData }`. The full deliverable view including
executive summary, opportunity matrix, and risk assessment.
## With supporting documents
If the consultant has uploaded documents through the web app first, the agent can run a deeper analysis:
```text theme={null}
Run a fresh audit analysis for the {project} project. The new SOC2 audit
report and Q3 financials were just added. Once it's done, give me a brief
on what changed compared to the prior analysis and three new opportunities
that emerged from the financial data.
```
The agent will:
1. Fetch project detail to confirm documents are present
2. Trigger `POST /api/projects/{id}/audit-analysis`, or use the async `/api/agent/projects/{id}/audit-analysis/async` endpoint if the project already has current document and interview analyses
3. Compare against the prior analysis (`GET .../audit-analysis` returns the most recent; multiple versions are stored)
4. Synthesize the diff
## Generating client-ready deliverables
After analysis, the agent can pull the deliverable dashboard and reformat any of its sections:
```text theme={null}
Pull the deliverables for the {project} project. Format the executive
summary as a client-ready brief I can paste into an email, then list the
stakeholder memos verbatim under each stakeholder name.
```
Behind the scenes:
* `GET /api/projects/{id}/deliverables`, returns the full deliverable dashboard (executive summary, opportunities, risks, stakeholder memos)
* The agent extracts and reformats from the response
Deliverable document **regeneration** (e.g. creating a new stakeholder memo PDF on demand) is a web-app-only operation in v1. The synthesis pipeline already produces these once `audit-analysis` runs, so agents should pull from `/deliverables` rather than triggering regeneration.
## Lead-to-audit flow
If your project starts as an Audity ReadyLink lead:
```text theme={null}
Look at my Audity leads from the last 7 days. Pick the top 3 by readiness
score. For each one, convert it into a full audit project and trigger the
analysis. Report back with project IDs and ETAs.
```
What runs:
1. `GET /api/lead-generation/leads?status=active&sortBy=ai_readiness_score&sortOrder=desc&limit=50` (response is wrapped: `{ data, pagination, filters }`)
2. Agent filters client-side by `createdAt >= 7 days ago` and ranks by `aiReadinessScore`
3. For each pick: `POST /api/lead-generation/leads/{id}/convert` (creates project, returns 400 if already converted, 402 on insufficient credits, 1,000 credits each)
4. For each: trigger audit analysis. If the converted project already has the prerequisite document and interview analyses, prefer the async endpoint for batches so the agent can poll job status instead of holding multiple long HTTP requests open.
This is one of the highest-value agent workflows. A consultant who used to manually triage leads in the dashboard can now do it from Claude in 30 seconds.
## Common patterns and pitfalls
`POST /api/projects/{id}/audit-analysis` is **synchronous** and blocks 60-300 seconds. Set client HTTP timeout to at least 360s. If your agent platform caps requests at 60s, use the async endpoint only when the project already has current document and interview analyses; otherwise verify with `GET .../audit-analysis` before retrying.
Each `POST /api/projects` deducts 1,000 credits. For batch operations, have the agent check `GET /api/user/credits` first and abort if there's not enough headroom.
Always have the agent cite the opportunity by ID when summarizing: *"Top opportunity is opp\_xyz: implement RPA for invoice processing"*. The IDs come back in the response.
No. Every PAT resolves to your Clerk user ID, and Supabase RLS enforces that you can only see your own rows. Even if the agent tries to GET a project ID belonging to another user, the response is 404.
## What's next
* [Working with Nucleus →](/guides/working-with-nucleus)
* [Lead conversion playbook →](/guides/lead-conversion)
* [Full API reference →](/api-reference/openapi.json)