> ## 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.
# Audity for Agents
> Drive your Audity workspace from any HTTP client, automation tool, or AI assistant.
## What Audity is, briefly
Audity is a B2B SaaS platform for AI consultants. It runs structured audits of a client's business, surfaces opportunities and risks via AI synthesis, manages an inbox of inbound leads from public ReadyLink surveys, and remembers everything across engagements via a layer called Nucleus.
If you're a consultant inside the app, you upload documents, click "run audit," review the output, ship deliverables. If you're outside the app, you do the same things from your AI assistant.
This site documents the **agent API**, the surface that lets external AI agents act on a consultant's Audity workspace.
## What the agent API is for
Three concrete outcomes a consultant gets when they wire an AI agent up to Audity:
1. **Run an audit without leaving your chat window.** "Start an Audity project for {client}, {industry}, {size}. Run the analysis. Summarize the top three opportunities." Three real API calls, one prompt, one paragraph back.
2. **Triage your lead inbox in 30 seconds.** "Pull my Audity leads from this week scored above 70. Convert the top three into projects. Trigger analysis on each." A workflow that used to be 15 minutes of dashboard clicking, done from Claude Desktop.
3. **Query your accumulated client knowledge from anywhere.** "What do I remember about Acme's stakeholder concerns? Are there patterns I've seen across other healthcare clients?" Nucleus, your persistent memory layer, becomes searchable from any AI assistant.
If those sound useful, start with the [API Quickstart (curl)](/api-quickstart) if you want direct REST access, or the [Agent Quickstart](/quickstart) if you're wiring up Claude, ChatGPT, or Cursor. If you want to know what's under the hood first, keep reading.
## How it works
```
┌──────────────────────────────────────────────────────────────────┐
│ Your code, agent, or automation (curl, Python, n8n, Zapier...) │
└────────────────────────┬─────────────────────────────────────────┘
│ HTTPS + Bearer PAT
▼
┌──────────────────────────────────────────────────────────────────┐
│ Audity REST API (app.auditynow.com) │
│ OpenAPI 3.1, every endpoint documented in the API Reference │
└────────────────────────┬─────────────────────────────────────────┘
│
│ PAT resolves to your Clerk identity
│ → tier + RLS gates apply
▼
┌──────────────────────────────────────────────────────────────────┐
│ Your workspace data: projects, Nucleus, leads, contacts │
└──────────────────────────────────────────────────────────────────┘
```
Every agent call goes through the same permission stack that protects the web app:
* Your **PAT** proves you are you (issued from your settings page; bcrypt-hashed at rest)
* Your **subscription tier** gates which features are callable
* **Supabase Row-Level Security** ensures the agent only sees data you own
* **Credit deductions** apply normally, creating a project costs credits whether it's clicked from the dashboard or invoked from Claude
## Ways to use the API
**Direct HTTP (scripts, automations, custom integrations).** Call any endpoint with `Authorization: Bearer aky_...` from curl, Python, JavaScript, n8n HTTP nodes, Zapier, Make, or any HTTP client. The full spec is at [/api-reference/openapi.json](/api-reference/openapi.json) and there's a complete curl walkthrough at [API Quickstart](/api-quickstart).
**Through an AI agent (Claude, ChatGPT, Cursor, n8n).** Run `npx @auditynow/connect` to auto-configure the Audity MCP server (`https://app.auditynow.com/api/mcp`) in Claude Desktop, Claude Code, and Cursor. ChatGPT and n8n get manual setup instructions. Every endpoint becomes a callable tool. See [Connect with one command](/guides/connect-cli) and [Connect Your Agent](/quickstart).
**Guided Audit Conductor.** For end-to-end audit workflows, Claude Code's optional `/audit` skill auto-orchestrates the pipeline, previews cost before spend, polls jobs correctly, and flags confidence thresholds. No glue code needed. See [Guided Audit Conductor](/guides/audit-conductor).
## What you can do today
| Capability | Endpoints |
| ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
| List, fetch, create, and patch projects | `GET/POST /api/projects`, `GET/PATCH /api/projects/{id}` |
| Trigger audit synthesis (the AI pipeline) | `POST /api/projects/{id}/audit-analysis`, `POST /api/agent/projects/{id}/audit-analysis/async` |
| Read AI-generated opportunities and full deliverables | `GET .../opportunities`, `GET .../deliverables` |
| List leads from your ReadyLinks and convert them | `GET /api/lead-generation/leads`, `POST .../convert` |
| Manage ReadyLinks and assessment templates | `GET/POST/PATCH/DELETE /api/agent/readylinks`, `GET/POST/PATCH/DELETE /api/agent/assessment-configs` |
| Search and create Nucleus memories | `GET /api/nucleus/memories`, `POST /api/nucleus/memories` |
| Submit text captures (transcripts, notes) and read extracted items | `POST /api/nucleus/capture/note`, `GET /api/nucleus/captures/{id}` |
| Read proactive insights generated by background jobs | `GET /api/nucleus/insights` |
| Manage the lightweight contact CRM | `GET/POST/PATCH/DELETE /api/nucleus/contacts` |
| Check your tier, credits, and current identity | `GET /api/user/{current,tier,credits}` |
The full path list and request/response shapes are in the [API Reference](/api-reference/openapi.json).
Audit synthesis runs \~10-15 minutes. Use the async endpoint + job polling; the synchronous endpoint blocks that whole time and risks gateway timeouts with no indication whether the work completed. The async endpoint expects current document and interview analyses, for a brand-new project, add source material and run those analyses first (MCP-connected agents can do this directly via `audity_upload_document` and the `audity_enqueue_*` tools).
## REST vs MCP: know your surface
The MCP surface (via `npx @auditynow/connect`) is a superset of the REST API. Some capabilities are **MCP-only**, with no REST endpoint:
* **Document upload** (`audity_upload_document`, plus chunked variants for large files)
* **Interview-session creation** (`audity_create_interview_session`)
* **PDF-generation status polling** (`audity_get_pdf_status`)
* **Deliverable generation** (`audity_enqueue_pdf_generation`, `audity_enqueue_gamma_deck`, `audity_enqueue_stakeholder_memos`) and **web research** (`audity_enqueue_web_research`)
A REST-only client (curl, plain HTTP nodes) cannot perform these today; use an MCP-connected agent or the web app.
Two things stay out of scope on both surfaces:
* **Streaming responses.** Audity returns structured JSON, not chat tokens. Stream prose with your own LLM; use Audity for synthesis, memory, project state.
* **PAT management via PAT.** Tokens are created and revoked from a browser session, not via the API itself.
If a workflow you need crosses one of these lines, [tell us](mailto:support@auditynow.com).
## Start here
Verify your token and run a real audit end to end from a terminal. No agent required.
Token format, scopes, rotation, error codes, and what gets logged.
Add Audity as a connector inside Claude Desktop or claude.ai (MCP).
MCP via one `claude mcp add` command, or call the REST API directly via CLAUDE.md.
MCP via a Developer Mode connector, or a Custom GPT with OpenAPI Actions.
Drop the MCP server into Cursor's tool palette.
Use the MCP Client node, or call endpoints from HTTP Request nodes.
## What's under the hood
If you're building an integration:
* The REST API is documented as **OpenAPI 3.1** at [/api-reference/openapi.json](/api-reference/openapi.json)
* The MCP server (`https://app.auditynow.com/api/mcp`) is **its own, larger surface**: 100+ hand-built `audity_*` tools, including capabilities with no REST equivalent (see REST vs MCP above)
* Auth is **Bearer token** (`aky_<32 chars>`) issued from your Audity settings page
* The token resolver runs in middleware; tier and RLS enforcement happens in route handlers
* Last verified against the live MCP tool surface and OpenAPI spec: July 14, 2026.
Ready? [Start with the quickstart →](/quickstart)