> **Building with AI coding agents?** If you're using an AI coding agent, install the official Scalekit plugin. It gives your agent full awareness of the Scalekit API — reducing hallucinations and enabling faster, more accurate code generation. > > - **Claude Code**: `claude plugin marketplace add scalekit-inc/claude-code-authstack && claude plugin install @scalekit-auth-stack` > - **GitHub Copilot CLI**: `copilot plugin marketplace add scalekit-inc/github-copilot-authstack` then `copilot plugin install @scalekit-auth-stack` > - **Codex**: run the bash installer, restart, then open Plugin Directory and enable `` > - **Skills CLI** (Windsurf, Cline, 40+ agents): `npx skills add scalekit-inc/skills --list` then `--skill ` > > `` / ``: `agentkit`, `full-stack-auth`, `mcp-auth`, `modular-sso`, `modular-scim` — [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/) --- # Zendesk connector Connect to Zendesk. Manage customer support tickets, users, organizations, and help desk operations **Authentication:** API KEY **Categories:** Customer Support, Communication 1. ### Install the SDK ### Node.js ```bash frame="terminal" npm install @scalekit-sdk/node ``` ### Python ```bash frame="terminal" pip install scalekit ``` Full SDK reference: [Node.js](/agentkit/sdks/node/) | [Python](/agentkit/sdks/python/) 2. ### Set your credentials Add your Scalekit credentials to your `.env` file. Find values in **[app.scalekit.com](https://app.scalekit.com)** > **Developers** > **API Credentials**. ```sh showLineNumbers=false title=".env" SCALEKIT_ENVIRONMENT_URL= SCALEKIT_CLIENT_ID= SCALEKIT_CLIENT_SECRET= ``` 3. ### Set up the connector Register your Zendesk credentials with Scalekit so it can authenticate requests on your behalf. You do this once per environment. ## Dashboard setup steps Register your Zendesk API credentials with Scalekit so it can authenticate requests on your behalf. You'll need your Zendesk subdomain, email address, and an API token from your Zendesk Admin Center. 1. ### Generate an API token - In your Zendesk Admin Center, go to **Apps and integrations** → **APIs** → **Zendesk API**. - Under **Settings**, enable **Token access**. > Image: Zendesk API configuration page with Allow API token access enabled - Click **Add API token**, enter a description, and click **Create**. - Copy the token — it is only shown once. 2. ### Create a connection In [Scalekit dashboard](https://app.scalekit.com), go to **AgentKit** > **Connections** > **Create Connection**. Find **Zendesk** and click **Create**. 3. ### Create a connected account Go to **Connected Accounts** for your Zendesk connection and click **Add account**. Fill in the required fields: - **Your User's ID** — a unique identifier for the user in your system - **Zendesk Domain** — your full Zendesk domain (e.g., `yourcompany.zendesk.com`) - **Email Address** — the Zendesk account email address - **API Token** — the token you copied in step 1 - Click **Save**. > Image: Add connected account form for Zendesk in Scalekit dashboard ## What you can do Connect this agent connector to let your agent: - **Create help center section, help center article, help center article comment** — Create a section under a Help Center category - **Update help center article translation, help center article, ticket** — Update a Help Center article translation's title, body, draft status, or outdated flag for a given locale - **List help center labels, help center article labels, help center sections** — List all Help Center labels in the account - **Search guide, help center articles, tickets** — Search across Help Center articles, community posts, and external records in a single query - **Get help center section, help center category, help center article** — Retrieve a single Help Center section by its ID - **Archive help center article** — Archive (delete) a Help Center article by ID ## Common workflows export const sectionTitle = 'Common workflows' ## Proxy API call **Don't worry about your Zendesk domain in the path.** Scalekit automatically resolves `{{domain}}` from the connected account's configuration. For example, a request with `path="/v2/users/me"` will be sent to `https://mycompany.zendesk.com/api/v2/users/me` automatically. ### Node.js ```typescript const result = await actions.request({ connectionName: 'zendesk', identifier: 'user_123', path: '/v2/users/me', method: 'GET', }); console.log(result); ``` ### Python ```python result = actions.request( connection_name='zendesk', identifier='user_123', path="/v2/users/me", method="GET" ) print(result) ``` ## Execute a tool ### Node.js ```typescript const result = await actions.executeTool({ connector: 'zendesk', identifier: 'user_123', toolName: 'zendesk_groups_list', toolInput: {}, }); console.log(result); ``` ### Python ```python result = actions.execute_tool( tool_input={}, tool_name='zendesk_groups_list', connection_name='zendesk', identifier='user_123', ) print(result) ``` ## Tool list Use the exact tool names from the **Tool list** below when you call `execute_tool`. If you're not sure which name to use, list the tools available for the current user first. ## Tool list ### `zendesk_groups_list` List all groups in Zendesk. Groups are used to organize agents and route tickets. Parameters: - `page` (`number`, optional): Page number for pagination - `per_page` (`number`, optional): Number of groups per page (max 100) ### `zendesk_guide_search` Search across Help Center articles, community posts, and external records in a single query. Requires authentication. The filter[locales] parameter is mandatory. Parameters: - `filter_locales` (`string`, required): Comma-separated locales to scope the search. At least one valid locale is required. - `filter_brand_ids` (`string`, optional): Comma-separated brand IDs to limit search scope. Returns results across all brands if omitted. - `filter_category_ids` (`string`, optional): Comma-separated category IDs to limit search to specific Help Center categories. - `filter_content_types` (`string`, optional): Comma-separated content types to limit results to: ARTICLE or POST. External records cannot be specified here; use filter_external_source_ids instead. - `filter_external_source_ids` (`string`, optional): Comma-separated external source IDs to scope results to specific external sources. - `filter_section_ids` (`string`, optional): Comma-separated section IDs to limit search to specific Help Center sections. - `filter_topic_ids` (`string`, optional): Comma-separated topic IDs to limit search to specific community topics. - `page_after` (`string`, optional): Cursor string from the previous response to fetch the next page. - `page_size` (`integer`, optional): Maximum number of results per page. Default is 10, maximum is 50. - `query` (`string`, optional): The search text to match. If omitted, results are sorted by internal ordering instead of relevance. ### `zendesk_help_center_article_archive` Archive (delete) a Help Center article by ID. The article can be restored from the Zendesk Help Center UI. Parameters: - `article_id` (`number`, required): The ID of the article to archive. ### `zendesk_help_center_article_comment_create` Add a comment to a Help Center article. Requires article ID, comment body, and locale. Parameters: - `article_id` (`number`, required): The ID of the article to comment on. - `body` (`string`, required): HTML body of the comment. - `locale` (`string`, required): Locale for the comment (e.g., en-us). - `author_id` (`number`, optional): User ID of the comment author (Help Center managers only). - `notify_subscribers` (`boolean`, optional): Whether to notify article subscribers of the new comment. Default: true. ### `zendesk_help_center_article_comments_list` List all comments on a Help Center article. Parameters: - `article_id` (`number`, required): The ID of the article whose comments to list. - `include` (`string`, optional): Comma-separated sideloads: users (authors), articles. - `page` (`integer`, optional): Page number for offset pagination. - `per_page` (`integer`, optional): Number of results per page (max 100). - `sort_order` (`string`, optional): Sort direction: asc or desc. Default: desc. ### `zendesk_help_center_article_create` Create a new Help Center article in a section. Requires a title, locale, and section ID. Parameters: - `locale` (`string`, required): Locale for the article (e.g., en-us). - `section_id` (`number`, required): The ID of the section to create the article in. - `title` (`string`, required): The title of the article. - `author_id` (`number`, optional): User ID of the article author. - `body` (`string`, optional): HTML body content of the article. - `comments_disabled` (`boolean`, optional): Whether to disable comments on this article. - `content_tag_ids` (`array`, optional): IDs of existing content tags to attach to the article. - `draft` (`boolean`, optional): If true, the article is saved as a draft and not published. - `notify_subscribers` (`boolean`, optional): Set to false to suppress email notifications to article subscribers on creation. Default: true. - `permission_group_id` (`number`, optional): The permission group that determines who can view this article. - `promoted` (`boolean`, optional): Whether to pin this article to the top of its section. - `user_segment_id` (`number`, optional): The user segment that can view this article. Omit for a public article. ### `zendesk_help_center_article_get` Retrieve a single Help Center article by its ID. Parameters: - `article_id` (`number`, required): The ID of the article to retrieve. - `include` (`string`, optional): Comma-separated sideloads: users, sections, categories, translations. ### `zendesk_help_center_article_labels_list` List all labels attached to a specific Help Center article. Parameters: - `article_id` (`string`, required): The ID of the article to retrieve labels for. - `page` (`integer`, optional): Page number for offset pagination. - `per_page` (`integer`, optional): Number of results per page (max 100). ### `zendesk_help_center_article_translation_update` Update a Help Center article translation's title, body, draft status, or outdated flag for a given locale. This is the only way to edit article content — the article-level update endpoint does not accept title or body. Parameters: - `article_id` (`number`, required): The unique ID of the article whose translation to update. - `locale` (`string`, required): The locale of the translation to update. - `body` (`string`, optional): New HTML body content for the translation. - `draft` (`boolean`, optional): If true, saves the translation as a draft and unpublishes it. - `outdated` (`boolean`, optional): If true, marks the translation as outdated. - `title` (`string`, optional): New title for the translation. ### `zendesk_help_center_article_update` Update article-level metadata: promoted status, position, comments setting, labels, and content tags. Does not update title or body — use the Translations API for those. Parameters: - `article_id` (`number`, required): The ID of the article to update. - `comments_disabled` (`boolean`, optional): Whether to disable comments on this article. - `content_tag_ids` (`array`, optional): IDs of content tags to attach to the article. - `label_names` (`array`, optional): Labels to assign to the article. - `position` (`integer`, optional): Position of the article within its section. - `promoted` (`boolean`, optional): Whether to pin this article to the top of its section. ### `zendesk_help_center_articles_list` List Help Center articles. Filter by section or category, sort, and paginate results. Parameters: - `include` (`string`, optional): Comma-separated sideloads: users, sections, categories, translations. - `label_names` (`string`, optional): Comma-separated list of labels to filter articles by. - `page` (`integer`, optional): Page number for offset pagination. - `per_page` (`integer`, optional): Number of results per page (max 100). - `sort_by` (`string`, optional): Field to sort by: position, title, created_at, updated_at, or edited_at. - `sort_order` (`string`, optional): Sort direction: asc or desc. - `start_time` (`integer`, optional): Unix epoch timestamp to fetch only articles updated after this time (for incremental sync). ### `zendesk_help_center_articles_search` Search Help Center articles by keyword. Filter by category, section, locale, labels, and date range. Parameters: - `brand_id` (`integer`, optional): Scope the search to a specific brand ID. - `category` (`number`, optional): Filter results to a specific category ID. - `created_after` (`string`, optional): Limit results to articles created after this date (YYYY-MM-DD). - `created_at` (`string`, optional): Limit results to articles created on this date (YYYY-MM-DD). - `created_before` (`string`, optional): Limit results to articles created before this date (YYYY-MM-DD). - `label_names` (`string`, optional): Comma-separated list of labels to filter by. - `locale` (`string`, optional): Filter results to a specific locale. - `multibrand` (`boolean`, optional): Search across all brands when true. Defaults to false. - `page` (`integer`, optional): Page number for offset pagination. - `per_page` (`integer`, optional): Number of results per page (max 100). - `query` (`string`, optional): Full-text search query. - `section` (`number`, optional): Filter results to a specific section ID. - `sort_by` (`string`, optional): Sort by relevance, created_at, or updated_at. - `sort_order` (`string`, optional): Sort direction: asc or desc. - `updated_after` (`string`, optional): Limit results to articles updated after this date (YYYY-MM-DD). - `updated_at` (`string`, optional): Limit results to articles updated on this date (YYYY-MM-DD). - `updated_before` (`string`, optional): Limit results to articles updated before this date (YYYY-MM-DD). ### `zendesk_help_center_categories_list` List all Help Center categories in your Zendesk account. Returns categories with IDs, names, and positions. Parameters: - `include` (`string`, optional): Sideload related data. Use 'translations' to include category translations. - `page` (`integer`, optional): Page number for offset pagination. - `per_page` (`integer`, optional): Number of results per page (max 100). - `sort_by` (`string`, optional): Field to sort by: position, created_at, or updated_at. - `sort_order` (`string`, optional): Sort direction: asc or desc. ### `zendesk_help_center_category_get` Retrieve a single Help Center category by its ID. Parameters: - `category_id` (`number`, required): The ID of the category to retrieve. - `include` (`string`, optional): Sideload related data. Use 'translations' to include category translations. ### `zendesk_help_center_labels_list` List all Help Center labels in the account. Returns label names and article counts. Supports pagination. Parameters: - `page` (`integer`, optional): Page number for offset pagination. - `per_page` (`integer`, optional): Number of results per page (max 100). ### `zendesk_help_center_section_create` Create a section under a Help Center category. Supply name and locale for a single-locale section, or a translations array for multi-locale (the two patterns are mutually exclusive). Nesting under parent_section_id requires a Guide plan that supports nested sections. Parameters: - `category_id` (`number`, required): The unique ID of the category to create the section in. - `description` (`string`, optional): An optional description of the section. - `locale` (`string`, optional): The locale for the section. Required when not using translations. - `manageable_by` (`string`, optional): Who can manage this section. - `name` (`string`, optional): The name of the section. Required when not using translations. - `parent_section_id` (`number`, optional): ID of a parent section to nest this section under. Requires a Guide plan that supports nested sections. - `position` (`integer`, optional): Position of the section within its category for manual ordering. - `sorting` (`string`, optional): Sort order for articles within this section. - `theme_template` (`string`, optional): The template this section uses in the Help Center theme. - `translations` (`array`, optional): Additional locale translations for the section. Each item must have a locale, title, and optional body. - `user_segment_id` (`number`, optional): The user segment that can view this section. Omit for a public section. ### `zendesk_help_center_section_get` Retrieve a single Help Center section by its ID. Parameters: - `section_id` (`number`, required): The ID of the section to retrieve. - `include` (`string`, optional): Comma-separated sideloads: 'categories' to include the parent category, 'translations' to include translations. ### `zendesk_help_center_sections_list` List all Help Center sections. Filter by category to narrow results. Parameters: - `include` (`string`, optional): Comma-separated sideloads: 'categories' to include the parent category, 'translations' to include translations. - `page` (`integer`, optional): Page number for offset pagination. - `per_page` (`integer`, optional): Number of results per page (max 100). - `sort_by` (`string`, optional): Field to sort by: position, created_at, or updated_at. - `sort_order` (`string`, optional): Sort direction: asc or desc. ### `zendesk_organization_get` Retrieve details of a specific Zendesk organization by ID. Returns organization name, domain names, tags, notes, shared ticket settings, and custom fields. Parameters: - `organization_id` (`number`, required): The ID of the organization to retrieve - `include` (`string`, optional): Additional related data to include (e.g., lookup_relationship_fields) ### `zendesk_organizations_list` List all organizations in Zendesk with pagination support. Parameters: - `page` (`number`, optional): Page number for pagination - `per_page` (`number`, optional): Number of organizations per page (max 100) ### `zendesk_search_tickets` Search Zendesk tickets using a query string. Supports Zendesk's search syntax (e.g., 'type:ticket status:open'). Zendesk limits search results to 1,000 total — the maximum valid page is floor(1000 / per_page) (e.g., per_page=100 → max page 10, per_page=25 → max page 40). Stop paginating when next_page is null or you reach the max page; requesting beyond the limit returns a 400 error. Parameters: - `query` (`string`, required): Search query string using Zendesk search syntax (e.g., 'type:ticket status:open assignee:me') - `include` (`string`, optional): Comma-separated list of additional data to sideload with results. Supported values: users, groups, organizations, tickets. - `page` (`number`, optional): Page number for pagination. Max valid page = floor(1000 / per_page). Do not exceed this — Zendesk returns a 400 error beyond the 1,000 result limit. - `per_page` (`number`, optional): Number of results per page (max 100). Determines the max page ceiling: floor(1000 / per_page). Higher values mean fewer pages but a lower max page number. - `sort_by` (`string`, optional): Field to sort results by (updated_at, created_at, priority, status, ticket_type) - `sort_order` (`string`, optional): Sort direction: asc or desc (default: desc) ### `zendesk_side_conversation_get` Retrieve a specific side conversation on a Zendesk ticket by its ID. Returns the side conversation's state, subject, participants, preview text, and timestamps. Requires the Collaboration add-on. Parameters: - `side_conversation_id` (`string`, required): The ID of the side conversation to retrieve - `ticket_id` (`number`, required): The ID of the parent ticket - `include` (`string`, optional): Sideloads to include alongside the response. Use 'side_conversation_events' to include the full event history of the side conversation. ### `zendesk_side_conversations_list` List all side conversations on a Zendesk ticket. Returns side conversations including their state, subject, participants, and preview text. Requires the Collaboration add-on. Parameters: - `ticket_id` (`number`, required): The ID of the ticket whose side conversations to list - `include` (`string`, optional): Sideloads to include alongside the response. Use 'side_conversation_events' to include the full event history for each side conversation. ### `zendesk_ticket_comments_list` Retrieve all comments (public replies and internal notes) for a specific Zendesk ticket. Returns comment body, author, timestamps, and attachments. Parameters: - `ticket_id` (`number`, required): The ID of the ticket whose comments to list - `include` (`string`, optional): Sideloads to include. Accepts 'users' to list email CCs. - `include_inline_images` (`boolean`, optional): When true, inline images are listed as attachments (default: false) - `sort_order` (`string`, optional): Sort direction for comments: asc or desc (default: asc) ### `zendesk_ticket_create` Create a new support ticket in Zendesk. Requires a comment/description and optionally a subject, priority, assignee, and tags. Parameters: - `comment_body` (`string`, required): The description or first comment of the ticket - `assignee_email` (`string`, optional): Email of the agent to assign the ticket to - `priority` (`string`, optional): Ticket priority: urgent, high, normal, or low - `status` (`string`, optional): Ticket status: new, open, pending, hold, solved, or closed - `subject` (`string`, optional): The subject/title of the ticket - `tags` (`array`, optional): List of tags to apply to the ticket - `type` (`string`, optional): Ticket type: problem, incident, question, or task ### `zendesk_ticket_get` Retrieve details of a specific Zendesk ticket by ID. Returns ticket properties including status, priority, subject, requester, assignee, and timestamps. Parameters: - `ticket_id` (`number`, required): The ID of the ticket to retrieve - `include` (`string`, optional): Comma-separated list of sideloads to include (e.g., users, groups, organizations) ### `zendesk_ticket_reply` Add a public reply or internal note to a Zendesk ticket. Set public to false for internal notes visible only to agents. Parameters: - `body` (`string`, required): The reply message content (plain text, markdown supported) - `ticket_id` (`number`, required): The ID of the ticket to reply to - `public` (`boolean`, optional): Whether the comment is public (true) or an internal note (false). Defaults to true. ### `zendesk_ticket_update` Update an existing Zendesk ticket. Change status, priority, assignee, subject, tags, or any other writable ticket field. Parameters: - `ticket_id` (`number`, required): The ID of the ticket to update - `assignee_email` (`string`, optional): Email of the agent to assign the ticket to - `assignee_id` (`number`, optional): ID of the agent to assign the ticket to - `group_id` (`number`, optional): ID of the group to assign the ticket to - `priority` (`string`, optional): Ticket priority: urgent, high, normal, or low - `status` (`string`, optional): Ticket status: new, open, pending, hold, solved, or closed - `subject` (`string`, optional): New subject/title for the ticket - `tags` (`array`, optional): List of tags to set on the ticket (replaces existing tags) - `type` (`string`, optional): Ticket type: problem, incident, question, or task ### `zendesk_tickets_list` List tickets in Zendesk with sorting and pagination. Returns tickets for the authenticated agent's account. Parameters: - `page` (`number`, optional): Page number for pagination - `per_page` (`number`, optional): Number of tickets per page (max 100) - `sort_by` (`string`, optional): Field to sort by: created_at, updated_at, priority, status, ticket_type - `sort_order` (`string`, optional): Sort direction: asc or desc (default: desc) ### `zendesk_user_create` Create a new user in Zendesk. Can create end-users (customers), agents, or admins. Email is required for end-users. Parameters: - `name` (`string`, required): Full name of the user - `email` (`string`, optional): Primary email address of the user - `organization_id` (`number`, optional): ID of the organization to associate the user with - `phone` (`string`, optional): Primary phone number (E.164 format, e.g. +15551234567) - `role` (`string`, optional): User role: end-user, agent, or admin. Defaults to end-user. - `verified` (`boolean`, optional): Whether the user's identity is verified. Defaults to false. ### `zendesk_user_get` Retrieve details of a specific Zendesk user by ID. Returns user profile including name, email, role, organization, and account status. Parameters: - `user_id` (`number`, required): The ID of the user to retrieve - `include` (`string`, optional): Comma-separated list of sideloads to include ### `zendesk_users_list` List users in Zendesk. Filter by role (end-user, agent, admin) with pagination support. Parameters: - `page` (`number`, optional): Page number for pagination - `per_page` (`number`, optional): Number of users per page (max 100) - `role` (`string`, optional): Filter by role: end-user, agent, or admin - `sort` (`string`, optional): Field to sort by. Prefix with - for descending (e.g. -created_at) ### `zendesk_views_list` List ticket views in Zendesk. Views are saved filters for organizing tickets by status, assignee, tags, and more. Parameters: - `access` (`string`, optional): Filter by access level: personal, shared, or account - `page` (`number`, optional): Page number for pagination - `per_page` (`number`, optional): Number of views per page (max 100) - `sort_by` (`string`, optional): Field to sort by: title, updated_at, created_at, or position - `sort_order` (`string`, optional): Sort direction: asc or desc --- ## More Scalekit documentation | Resource | What it contains | When to use it | |----------|-----------------|----------------| | [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content | | [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas | | [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |