Skip to main content

​
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
Every request needs: 
Authorization: Bearer aky_<your-token>
Content-Type: application/json     (on writes)

​
1. Verify auth

Set your token: 
export AUDITY_TOKEN="aky_..."
Confirm the API recognizes it: 
curl -s https://app.auditynow.com/api/user/current \
  -H "Authorization: Bearer $AUDITY_TOKEN" | jq
Expected response: 
{
  "success": true,
  "userId": "user_2abc...",
  "userEmail": "you@example.com",
  "authMethod": "pat",
  "authData": {}
}
If you see 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
The credits response includes 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
Response is an array of project summaries with status flags (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
Capture the project ID: 
export PROJECT_ID="<uuid from the response>"

​
5. Trigger the audit analysis

This is the expensive call. For curl and server-side jobs, the direct synthesis endpoint can run 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
Response includes { analysis, requestData, message }. If your project already has current document and interview analysis records, you can use the async endpoint and poll the returned job: 
curl -s -X POST "https://app.auditynow.com/api/agent/projects/$PROJECT_ID/audit-analysis/async" \
  -H "Authorization: Bearer $AUDITY_TOKEN" | jq
Capture the job ID: 
export JOB_ID="<jobId from the response>"

curl -s "https://app.auditynow.com/api/agent/jobs/$JOB_ID" \
  -H "Authorization: Bearer $AUDITY_TOKEN" | jq
Poll until status is "completed" or "failed". To check the synchronous endpoint’s current project-level status: 
curl -s "https://app.auditynow.com/api/projects/$PROJECT_ID/audit-analysis" \
  -H "Authorization: Bearer $AUDITY_TOKEN" | jq '.status'
Returns "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)}'
The response is wrapped in { 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
Response wraps the capture in { "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}'
Each memory carries a confidence score and a source type. Treat detected patterns under 0.8 as hypotheses.

​
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
Re-converting an already-converted lead returns 400 (not 409). Check surveyStatus !== 'converted' before calling.

​
Error handling, in one place

StatusWhat it meansWhat to do
200 / 201 / 204SuccessContinue
400Validation failed; check code (e.g. EMPTY_PATCH, DESCRIPTION_TOO_LONG)Fix the request body
401 PAT_MALFORMEDToken format invalidGenerate a new token
401 (no code)Token doesn’t resolveToken revoked or expired; generate a new one
402Insufficient credits (lead conversion only)Buy credits or wait for monthly reset
403 PAT_SCOPE_INSUFFICIENTWrong scope (write needed)New token with read + write
403 PAT_ROUTE_NOT_ALLOWEDRoute isn’t on the agent allowlistUse the web app for that one
404Resource not found, OR you don’t own it (RLS)Check the ID and your ownership
429Rate limit hitHonor Retry-After, back off
500 / 502 / 503Server side or kill switchRetry with exponential backoff; if persistent, contact support
A full code reference is in Authentication → Error codes.

​
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\"}"
That’s the entire integration. No MCP, no agent, no SDK, just curl and your shell.

​
What’s next