# AI agents & escalation

> Every investigation, draft, tracker-filing, and helpdesk-connection query and mutation.

Product: Clad API
Source: https://docs.useclad.ai/api/reference-ai-agents

---

Run investigations, work AI-suggested reply drafts (with grounding sources), file engineering-tracker tickets, and read the helpdesk connection.

### Queries

#### `helpdeskConnections`

```graphql
helpdeskConnections: [HelpdeskConnection!]
```

Connected external helpdesks (Pylon/Zendesk) with status and operating mode. Empty when none.

#### `investigation`

```graphql
investigation(id: ID!): Investigation
```

One investigation run by id (null when unknown).

| Argument | Type | Description |
| --- | --- | --- |
| `id` | `ID!` | Required. |

#### `investigations`

```graphql
investigations(issueId: ID!): [Investigation!]
```

Investigation runs for an issue, newest first (latest 20).

| Argument | Type | Description |
| --- | --- | --- |
| `issueId` | `ID!` | Required. |

#### `latestDraft`

```graphql
latestDraft(issueId: ID!): Draft
```

The most recent AI draft attempt for an issue, any status — lets a caller distinguish generating / pending / discarded / approved in one read.

| Argument | Type | Description |
| --- | --- | --- |
| `issueId` | `ID!` | Required. |

#### `linkedTickets`

```graphql
linkedTickets(issueId: ID!): [TrackerTicket!]
```

Engineering-tracker tickets linked to an issue, with live state and comments.

| Argument | Type | Description |
| --- | --- | --- |
| `issueId` | `ID!` | Required. |

### Mutations

#### `approveDraft`

```graphql
approveDraft(input: ApproveDraftInput!): DraftResult
```

Approve a pending draft and deliver it to the customer. Requires a human-authorized credential (OAuth) — the send is attributed to the approving person. v1 delivers on helpdesk-mirrored issues (Pylon/Zendesk); the helpdesk operating mode is enforced (FORBIDDEN in Observe).

| Argument | Type | Description |
| --- | --- | --- |
| `input` | `ApproveDraftInput!` | Required. |

#### `commentOnLinkedTicket`

```graphql
commentOnLinkedTicket(input: CommentOnLinkedTicketInput!): TrackerTicketCommentResult
```

Post a comment on a tracker ticket linked to an issue. Only tickets linked to the issue are reachable.

| Argument | Type | Description |
| --- | --- | --- |
| `input` | `CommentOnLinkedTicketInput!` | Required. |

#### `denyDraft`

```graphql
denyDraft(input: DenyDraftInput!): DraftResult
```

Reject a pending draft with an optional reason.

| Argument | Type | Description |
| --- | --- | --- |
| `input` | `DenyDraftInput!` | Required. |

#### `fileTrackerTicket`

```graphql
fileTrackerTicket(input: FileTrackerTicketInput!): TrackerTicketResult
```

File an engineering-tracker ticket (Linear) from an issue and link it. The Clad issue moves to On hold; a back-link comment is posted on the tracker ticket. Check linkedTickets first to avoid duplicates.

| Argument | Type | Description |
| --- | --- | --- |
| `input` | `FileTrackerTicketInput!` | Required. |

#### `generateDraft`

```graphql
generateDraft(input: GenerateDraftInput!): GenerateDraftResult
```

Generate a KB-grounded suggested reply through the same gated pipeline as automatic drafts. A declined gate returns withheld=true, not an error. CONFLICT when a pending draft already exists.

| Argument | Type | Description |
| --- | --- | --- |
| `input` | `GenerateDraftInput!` | Required. |

#### `generateDraftFromInvestigation`

```graphql
generateDraftFromInvestigation(investigationId: ID!): DraftResult
```

Turn a completed investigation's findings into a pending customer-reply draft. CONFLICT when the run is incomplete or reported no deliverable answer.

| Argument | Type | Description |
| --- | --- | --- |
| `investigationId` | `ID!` | Required. |

#### `startInvestigation`

```graphql
startInvestigation(input: StartInvestigationInput!): InvestigationResult
```

Start an asynchronous code or billing investigation for an issue. Per-org in-flight and daily caps apply (RATE_LIMITED when hit). Poll the investigation query for completion.

| Argument | Type | Description |
| --- | --- | --- |
| `input` | `StartInvestigationInput!` | Required. |