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.
When to use this page
If you’re building a custom integration, a scheduled job, or a non-MCP agent, or you just want to confirm your PAT works before pasting it into Claude, this page walks you through the API with curl. Every endpoint shown here is also exposed via MCP if you’d rather work that way; see the Quickstart for that path.
The base URL is:
https://app.auditynow.com
Authorization: Bearer aky_<your-token>
Content-Type: application/json (on writes)
1. Verify auth
Set your token:
export AUDITY_TOKEN="aky_..."
curl -s https://app.auditynow.com/api/user/current \
-H "Authorization: Bearer $AUDITY_TOKEN" | jq
{
"success": true,
"userId": "user_2abc...",
"userEmail": "you@example.com",
"authMethod": "pat",
"authData": {}
}
401 PAT_MALFORMED, the token format is wrong. If you see a 401 with no code, the token is correctly shaped but doesn’t resolve to an active key. Either way, generate a fresh one in Settings → API Tokens.
2. Check your tier and credits
Tier and credits gate write operations. Always check before a batch:
curl -s https://app.auditynow.com/api/user/tier \
-H "Authorization: Bearer $AUDITY_TOKEN" | jq
curl -s https://app.auditynow.com/api/user/credits \
-H "Authorization: Bearer $AUDITY_TOKEN" | jq
canCreateProject, projectsRemaining, and nextReset so you can plan around your monthly allocation.
3. List your projects
curl -s https://app.auditynow.com/api/projects \
-H "Authorization: Bearer $AUDITY_TOKEN" | jq
hasAuditAnalysis, hasDeliverables) and counts so you can see workflow progress at a glance.
4. Create a project
Costs 1,000 credits. Returns 201 with the new project.
curl -s -X POST https://app.auditynow.com/api/projects \
-H "Authorization: Bearer $AUDITY_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"clientName": "Globex Industries",
"industry": "Manufacturing",
"companySize": "200-500",
"currency": "USD"
}' | jq
export PROJECT_ID="<uuid from the response>"
5. Trigger the audit analysis
This is the expensive call. The synthesis pipeline runs synchronously for 60–300 seconds, so set a generous timeout:
curl -s --max-time 360 \
-X POST "https://app.auditynow.com/api/projects/$PROJECT_ID/audit-analysis" \
-H "Authorization: Bearer $AUDITY_TOKEN" | jq
{ analysis, requestData, message }. If your client can’t wait that long, kick the request from a background worker and poll:
curl -s "https://app.auditynow.com/api/projects/$PROJECT_ID/audit-analysis" \
-H "Authorization: Bearer $AUDITY_TOKEN" | jq '.status'
"running" while in flight, the full payload when complete.
6. Read the deliverables
After analysis completes:
curl -s "https://app.auditynow.com/api/projects/$PROJECT_ID/deliverables" \
-H "Authorization: Bearer $AUDITY_TOKEN" | jq '.data | {executiveSummary, opportunities: (.opportunities | length), risks: (.risks | length)}'
{ success: true, data: ... }. The data object contains the executive summary, opportunity matrix, risk assessment, and stakeholder memos.
For just the opportunities (most common agent query):
curl -s "https://app.auditynow.com/api/projects/$PROJECT_ID/opportunities?category=quick_wins" \
-H "Authorization: Bearer $AUDITY_TOKEN" | jq
7. Capture a note into Nucleus
Nucleus ingests text from outside sources via captures. After a client call, post the transcript:
curl -s -X POST https://app.auditynow.com/api/nucleus/capture/note \
-H "Authorization: Bearer $AUDITY_TOKEN" \
-H "Content-Type: application/json" \
-d "{
\"content\": \"Met with the CTO. Decided to defer SOC2 to Q3. Action item: send revised roadmap by Friday.\",
\"projectId\": \"$PROJECT_ID\"
}" | jq
{ "capture": { ... } } with status: "pending". Extraction runs async (~15–60s), poll the capture detail to see structured items appear:
export CAPTURE_ID="<id from the response>"
curl -s "https://app.auditynow.com/api/nucleus/captures/$CAPTURE_ID" \
-H "Authorization: Bearer $AUDITY_TOKEN" | jq '{status: .capture.status, items: (.items | length)}'
status: "processed" and a non-zero items count means extraction finished.
8. Search Nucleus memories
curl -s "https://app.auditynow.com/api/nucleus/memories?type=client&projectId=$PROJECT_ID" \
-H "Authorization: Bearer $AUDITY_TOKEN" | jq '.memories[] | {subject, confidence, sourceType}'
9. Convert a lead
If you have inbound leads from a ReadyLink survey, list and convert them:
# List active leads, top of pipeline first
curl -s "https://app.auditynow.com/api/lead-generation/leads?status=active&sortBy=ai_readiness_score&sortOrder=desc&limit=10" \
-H "Authorization: Bearer $AUDITY_TOKEN" | jq '.data[] | {id, businessName, aiReadinessScore, surveyStatus}'
# Convert one (creates a project, deducts 1,000 credits)
export LEAD_ID="<uuid>"
curl -s -X POST "https://app.auditynow.com/api/lead-generation/leads/$LEAD_ID/convert" \
-H "Authorization: Bearer $AUDITY_TOKEN" | jq
400 (not 409). Check surveyStatus !== 'converted' before calling.
Error handling, in one place
| Status | What it means | What to do |
|---|
| 200 / 201 / 204 | Success | Continue |
| 400 | Validation failed; check code (e.g. EMPTY_PATCH, DESCRIPTION_TOO_LONG) | Fix the request body |
401 PAT_MALFORMED | Token format invalid | Generate a new token |
| 401 (no code) | Token doesn’t resolve | Token revoked or expired; generate a new one |
| 402 | Insufficient credits (lead conversion only) | Buy credits or wait for monthly reset |
403 PAT_SCOPE_INSUFFICIENT | Wrong scope (write needed) | New token with read + write |
403 PAT_ROUTE_NOT_ALLOWED | Route isn’t on the agent allowlist | Use the web app for that one |
| 404 | Resource not found, OR you don’t own it (RLS) | Check the ID and your ownership |
| 429 | Rate limit hit | Honor Retry-After, back off |
| 500 / 502 / 503 | Server side or kill switch | Retry with exponential backoff; if persistent, contact support |
Putting it together: a 5-line cron
A daily Slack brief in pure shell + curl + jq:
#!/bin/bash
INSIGHTS=$(curl -s "https://app.auditynow.com/api/nucleus/insights?unreadOnly=true&limit=10" \
-H "Authorization: Bearer $AUDITY_TOKEN" | jq -r '.[] | "- [\(.type)] \(.title)"')
curl -s -X POST "$SLACK_WEBHOOK" \
-H "Content-Type: application/json" \
-d "{\"text\":\"*Audity insights for today*\n$INSIGHTS\"}"
What’s next
