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:

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:

1. POST /api/projects

   {
     "clientName": "Acme Corp",
     "industry": "Manufacturing",
     "companySize": "200-500",
     "currency": "USD"
   }
   

   Returns {id, status: "setup"}. Deducts 1,000 credits.

2. Trigger audit analysis

   POST /api/projects/{id}/audit-analysis runs the synthesis pipeline synchronously and typically takes ~10-15 minutes, long enough that most clients and platform gateways will cut the request with no indication whether the work completed. Avoid it.

   Instead, once the project has current document and interview analysis records, use POST /api/agent/projects/{id}/audit-analysis/async, then poll GET /api/agent/jobs/{jobId} until the job is completed or failed.

3. GET /api/projects/{id}/opportunities

   Returns { opportunities: [...] } (wrapped). Each opportunity has impactScore (1-10), effortScore (1-10), category, roiPotential, implementationTimeline. The agent ranks/summarizes.

4. GET /api/projects/{id}/deliverables

   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:

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:

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:

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

The agent times out waiting for analysis

POST /api/projects/{id}/audit-analysis is synchronous and blocks ~10-15 minutes, longer than essentially any client or gateway timeout allows. Use the async endpoint + job polling once the project has current document and interview analyses. If a sync call did time out, verify with GET .../audit-analysis before retrying, the work may have completed server-side.

The agent runs out of credits mid-batch

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.

The agent hallucinates an opportunity that isn't in the data

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.

Multi-tenant safety, can the agent see other users' projects?

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 →
• Lead conversion playbook →
• Full API reference →