> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qwairy.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a Pitch Audit

> Create a Pitch Audit for a prospect from an agency team and queue prompt preparation, then review the prompts or enable automatic answer collection.

Creates a Pitch Audit for the agency team attached to the API key and queues
prompt preparation. Use the default review flow, or explicitly enable automatic
answer collection.

> [!NOTE]
>
> Requires an agency team on an active Business, Agency Business, or Enterprise
> plan. Existing API keys work without rotation.

**Authorization** `string` *required*

Bearer token. Example: `Bearer qw-api-xxx`

**Idempotency-Key** `string` *required*

Unique key for this audit. Replaying the same request returns the original
response instead of creating another audit.

**url** `string` *required*

Prospect website URL or domain, up to 2048 characters.

**name** `string`

Prospect display name, up to 120 characters. Defaults to the normalized
domain.

**countryCode** `string` (default: US)

Supported two-letter market code. The market controls model availability.

**promptCount** `number` (default: 30)

Number of prompts to prepare, from 20 to 100. With `customPrompts`, omit it or
send the number of imported prompts.

**customPrompts** `array`

From 20 to 100 distinct prompt texts to import instead of generating a prompt set.

**modelIds** `array`

Models to use. Omit to use the Pitch Audit defaults available in the selected
market.

**autoStartResponses** `boolean` (default: false)

Set to `true` to start billable answer collection after prompt preparation.
Keep `false` to review and save the prompts before confirmation.

## Response

Returns `202` with a `Location` header pointing to
`GET /api/v1/pitch-audits/{auditId}`.

**pitchAudit.id** `string`

Opaque Pitch Audit identifier.

**pitchAudit.reportUrl** `string`

URL of the report resource.

**pitchAudit.requiredCredits** `number`

Credits required by the selected prompt and model configuration.

**pitchAudit.availableCredits** `number`

Team balance observed when the audit was accepted.

**pitchAudit.dispatchStatus** `string`

`QUEUED` when dispatch succeeded, or `RECOVERING` when the durable recovery
path will retry it.

## Synthetic request

```bash theme={null}
curl -X POST "https://www.qwairy.co/api/v1/pitch-audits" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN" \
  -H "Idempotency-Key: pitch-northstar-001" \
  -H "Content-Type: application/json" \
  -d '{"url":"northstar.example","name":"Northstar Labs","countryCode":"US","promptCount":20}'
```

## Next step

Poll [Get Pitch Audit](https://docs.qwairy.co/developers/endpoints/pitch-audits/get.md). When it reaches
`AWAITING_PROMPTS`, review the returned prompts and save them with the response
`ETag`, then confirm the audit.

## Errors

| Status | Code | Cause |
| - | - | - |
| `400` | `INVALID_REQUEST` | Invalid domain, market, prompt, or model selection |
| `403` | `INSUFFICIENT_PLAN` | The team is not an agency team on a write-enabled plan |
| `409` | `INSUFFICIENT_CREDITS` | The team balance cannot cover the selected answer collection |
| `409` | `IDEMPOTENCY_CONFLICT` | Key reused with a different body |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.