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

> ## Agent Instructions
> These docs describe the Ancha CLI, npm package @ancha-labs/cli, and the hosted workspace at app.ancha.io. Coding agents should start at https://docs.ancha.io/coding-agents. Run the CLI as `ancha` after `npm install -g @ancha-labs/cli`, or as `npx -y @ancha-labs/cli` without installing. Pass --json for machine-readable output, or set ANCHA_JSON=1. Every command ends with a `next:` line naming the next command. Exit codes: 0 pass, 1 a check failed or a comparison regressed, 2 usage, config or authentication error, 3 infrastructure error, 4 unimplemented endpoint with --strict.

# Zendesk

> Test support tickets, replies, users, organizations, groups, macros and views with Zendesk Support API v2.

The Zendesk tool covers 21 endpoints of Support API v2. Its key is `zendesk`. Replies are recorded in the world and never emailed.

## Connect

| Variable | Value |
| - | - |
| `ZENDESK_API_URL` | Base URL, ending in `/api/v2`. Append paths such as `/tickets.json`. |
| `ZENDESK_EMAIL` | Email of the agent account. Append `/token` for the HTTP Basic username. |
| `ZENDESK_API_TOKEN` | Fake API token. Use it as the HTTP Basic password. |

```js Node theme={null}
const auth = 'Basic ' + Buffer.from(`${process.env.ZENDESK_EMAIL}/token:${process.env.ZENDESK_API_TOKEN}`).toString('base64');
const res = await fetch(`${process.env.ZENDESK_API_URL}/search.json?query=${encodeURIComponent('type:ticket status<solved')}`, { headers: { authorization: auth } });
const { results } = await res.json();
```

This is what `ancha connect zendesk --lang ts` prints. Paths accept an optional `.json` suffix.

## Endpoints

All 21 endpoints are partial. `ancha twins coverage zendesk` prints the same paths and their limits.

| Method | Path | Support |
| - | - | - |
| `GET` | `/api/v2/tickets` | partial: offset (page, per\_page) or cursor (page\[size], page\[after]) pagination; sort\_by/sort\_order or sort; include=users,groups,organizations,comment\_count; external\_id |
| `POST` | `/api/v2/tickets` | partial: a requester by id or by name and email (new end users are created); status, priority, type, tags, assignee and group; returns the audit |
| `GET` | `/api/v2/tickets/{id}` | partial |
| `PUT` | `/api/v2/tickets/{id}` | partial: public replies and internal notes, status rules (new opens, solved assigns, closed is final), tags, additional\_tags, remove\_tags, safe\_update |
| `DELETE` | `/api/v2/tickets/{id}` | partial |
| `GET` | `/api/v2/tickets/{id}/comments` | partial: include=users |
| `GET` | `/api/v2/tickets/{id}/macros/{macro_id}/apply` | partial: the changes and comment a macro would make; nothing is saved |
| `GET` | `/api/v2/search` | partial: type, status, priority, ticket\_type, assignee, requester, organization, group, tags, subject, description, comment, created/updated/solved, negation and plain words |
| `GET` | `/api/v2/users` | partial: role and role\[] filters; offset (page, per\_page) or cursor (page\[size], page\[after]) pagination |
| `POST` | `/api/v2/users` | partial: end users by any agent, agents and admins by admins |
| `GET` | `/api/v2/users/me` | partial |
| `GET` | `/api/v2/users/search` | partial: query (email or name) or external\_id |
| `GET` | `/api/v2/users/{id}` | partial |
| `GET` | `/api/v2/users/{id}/tickets/requested` | partial |
| `GET` | `/api/v2/organizations` | partial |
| `GET` | `/api/v2/organizations/{id}` | partial |
| `GET` | `/api/v2/organizations/{id}/tickets` | partial |
| `GET` | `/api/v2/groups` | partial |
| `GET` | `/api/v2/macros` | partial: active filter |
| `GET` | `/api/v2/views` | partial |
| `GET` | `/api/v2/views/{id}/tickets` | partial: status, assignee (none or current user) and group conditions |

Applying a macro returns the changes and comment it would make. Send those changes in a ticket update to save them. Unknown routes return HTTP 404 with Zendesk's error shape and `x-ancha-gap: 1`.

## Starter data

The starter data is the Acme account. Your agent acts as Ancha Assistant, `ancha@acme.example`, with the `agent` role.

| Record | Detail |
| - | - |
| Staff | Ancha Assistant, Mike Turner (admin), Laura Kim, Anna Fischer and Iris Cole (suspended). |
| Customers | Eight end users across Ridgeway Robotics, Kestrel Credit Union, Pinecrest Health, Bluefield Logistics, Summit Freight and Helix Manufacturing. |
| Groups | Support and Billing. The agent belongs to both. |
| Tickets | Nine: two closed reports about a duplicate charge and an earlier dashboard bug; pending SAML login and seat-change requests; an SSO/SCIM question on hold; open dashboard and CSV-export questions; a new billing-address request; and a solved training-recording request. |
| Macros | Exports: where to find them; Billing: hand to finance; Close: resolved. |
| Views | Unassigned tickets, Your unsolved tickets, Pending tickets and Billing queue. |

Run `ancha twins seed zendesk --full` to print every ticket, comment and scene seed field.

## Checks

Zendesk has no state checks. Use [trace checks](https://docs.ancha.io/concepts/checks.md#trace-patterns), for example `{ called: "PUT /api/v2/tickets/*" }` or `{ not_called: "DELETE /api/v2/tickets/*" }`.

## Limits

* Replies stay in the world. Triggers, automations, SLAs, custom fields, attachments and Help Center are gaps.
* Search covers the common ticket, user and organization properties. Other properties return coverage gaps.
* Ticket status rules apply: an updated new ticket opens, solving assigns it, and a closed ticket is final.
* Any agent can create an end user. Only admins can create agents or admins.


## Related topics

- [Tools](https://docs.ancha.io/tools/overview.md)
- [Introduction](https://docs.ancha.io/index.md)
- [Environment variables](https://docs.ancha.io/reference/environment-variables.md)
- [Changelog](https://docs.ancha.io/changelog.md)
- [ancha connect](https://docs.ancha.io/cli/connect.md)


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