> ## 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.

# 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](/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:

```bash theme={null}
export AUDITY_TOKEN="aky_..."
```

Confirm the API recognizes it:

```bash theme={null}
curl -s https://app.auditynow.com/api/user/current \
  -H "Authorization: Bearer $AUDITY_TOKEN" | jq
```

Expected response:

```json theme={null}
{
  "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:

```bash theme={null}
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

```bash theme={null}
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.

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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):

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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

```bash theme={null}
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:

```bash theme={null}
# 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](/authentication#error-codes).

## Putting it together: a 5-line cron

A daily Slack brief in pure shell + curl + jq:

```bash theme={null}
#!/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 →](/guides/running-an-audit)
* [Lead conversion playbook →](/guides/lead-conversion)
* [Working with Nucleus →](/guides/working-with-nucleus)
* [Browse the full spec →](/api-reference/openapi.json)