API Quickstart (curl)

Verify your token and run a real audit, end to end, from a terminal.

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": "[e-mail]",
  "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. The direct synthesis endpoint runs synchronously for ~10-15 minutes, most clients should use the async endpoint + polling instead (see below). If you do call it directly, set a very generous timeout and know that a timed-out request may still have completed server-side:

curl -s --max-time 1200 \
  -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

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

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

• Run a full audit workflow →
• Lead conversion playbook →
• Working with Nucleus →
• Browse the full spec →