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

# Connect ChatGPT

> Use Audity from ChatGPT via a Custom GPT with Actions.

## Requirements

* ChatGPT account on Plus, Team, or Enterprise (Custom GPTs require a paid plan)
* An Audity Personal Access Token (`aky_...`), see [Authentication](/authentication)

## Setup

The agent surface is exposed as an OpenAPI spec. ChatGPT imports the spec and generates one Action per endpoint.

<Steps>
  <Step title="Create a Custom GPT">
    ChatGPT → sidebar → **Explore GPTs** → **Create**.
  </Step>

  <Step title="Configure the basics">
    Give it a name (`Audity`), a one-sentence description, and a short instruction telling it what Audity is and when to use it.

    Sample instruction:

    > You have access to Audity, a B2B SaaS platform for AI consultants. Use it whenever the user asks about audits, audit projects, AI readiness scores, leads from ReadyLinks, or their Nucleus memory layer. Ask the user before triggering audit analysis (it costs 1,000 credits) or converting batches of leads.
  </Step>

  <Step title="Add the Action">
    Configure → **Actions** → **Create new action**.
  </Step>

  <Step title="Import the OpenAPI spec">
    In the **Schema** field, click **Import from URL** and paste:

    ```
    https://docs.auditynow.com/api-reference/openapi.json
    ```

    ChatGPT will fetch and parse it. You should see the Audity operations listed as Actions.

    <Note>
      If the import fails due to CORS, download the JSON locally and paste it directly into the schema field.
    </Note>
  </Step>

  <Step title="Set authentication">
    Authentication type: **API Key**

    API key: paste your `aky_...` token (just the token, no `Bearer` prefix, ChatGPT prepends it automatically based on the auth type).

    Auth Type: **Bearer**

    Custom Header Name: leave blank (defaults to `Authorization`).
  </Step>

  <Step title="Set the privacy policy URL">
    Required by ChatGPT before you can save: `https://auditynow.com/privacy`
  </Step>

  <Step title="Test in the preview">
    In the right-hand preview pane, ask:

    > List my Audity projects.

    ChatGPT will pick the `listProjects` action, call the API, and return your real projects. If you see "Allow" prompts, approve them, Custom GPTs ask for confirmation on every Action call until you check "Always allow."
  </Step>
</Steps>

## Authentication, more detail

Custom GPT Actions handle the `Authorization: Bearer <token>` header for you when:

1. Auth type is **API Key**
2. Auth Type subselect is **Bearer**
3. You paste the raw token (no `Bearer` prefix yourself)

If you paste `Bearer aky_...` instead of just `aky_...`, ChatGPT will send `Authorization: Bearer Bearer aky_...`, every request returns `401 PAT_MALFORMED`. This is the most common ChatGPT setup failure.

## Common prompts

Same prompt menu as Claude, both are reading the same spec.

```text theme={null}
What's the status of my latest Audity audit?
```

```text theme={null}
Pull the deliverables for project {id}. Format the executive summary as a
client-ready email.
```

```text theme={null}
Search my Audity Nucleus memories for {topic}.
```

```text theme={null}
Show me my unread Audity insights, grouped by type.
```

## Limits ChatGPT imposes

A few things to know before you scale this:

* **One Custom GPT, one OpenAPI spec.** No multi-spec composition.
* **GPTs ask for permission on every Action call** unless you explicitly mark a domain as "always allow." For workflows that chain 5+ calls, that's a lot of clicks. Use Claude or Cursor for chained workflows.
* **No streaming responses from Actions.** Audity's responses are JSON, so this doesn't matter for our endpoints.
* **Long-running actions can time out.** For projects that already have current document and interview analyses, prefer the async audit endpoint (`triggerAsyncAuditAnalysis`) and poll the job status rather than calling the synchronous audit endpoint from ChatGPT.
* **Schema URL is fetched at import time, not at runtime.** If you update Audity's spec, you'll need to re-import. Until we ship a webhook for spec changes, treat the import as a frozen snapshot.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Action import fails or times out">
    If the import fails due to CORS, download the spec locally:

    ```bash theme={null}
    curl https://docs.auditynow.com/api-reference/openapi.json -o audity-spec.json
    ```

    Then paste the JSON contents into the schema field instead of the URL.
  </Accordion>

  <Accordion title="Every call returns 401 PAT_MALFORMED">
    You probably included `Bearer ` in the API key field. Edit the Action's auth, paste just `aky_<32-chars>` with no prefix.
  </Accordion>

  <Accordion title="Every call returns 403 PAT_SCOPE_INSUFFICIENT">
    Your token lacks the `write` scope. Generate a new token with both `read` and `write`, then update the Custom GPT's API key.
  </Accordion>

  <Accordion title="GPT can't find the right tool / picks the wrong one">
    Custom GPTs can be conservative about external Actions. Make sure your prompt mentions "Audity" by name. Tighten the GPT's system instruction with examples of when to call which Action.
  </Accordion>

  <Accordion title="429 rate limited mid-batch">
    See [Authentication → Rate limits](/authentication#rate-limits). Write limits are the most common ceiling for ChatGPT batch workflows.
  </Accordion>

  <Accordion title="Audit analysis times out (504 / hang)">
    `POST /api/projects/{id}/audit-analysis` can run 60–300 seconds. ChatGPT Actions have a hard timeout that's shorter than that, sometimes the call succeeds server-side but ChatGPT reports a failure. If the project already has current document and interview analyses, prefer `POST /api/agent/projects/{id}/audit-analysis/async`, then poll `GET /api/agent/jobs/{jobId}`. If you already called the synchronous endpoint, verify with `GET /api/projects/{id}/audit-analysis` after a minute or two before re-triggering.
  </Accordion>
</AccordionGroup>

## What's next

* [Run a full audit workflow →](/guides/running-an-audit)
* [Lead conversion playbook →](/guides/lead-conversion)
* [Authentication deep dive →](/authentication)