VX Agents

API directory · Customer Support

Gorgias Helpdesk Tickets & Customers

v1.0.0 · 11 endpoints · 0 connections · shared by vx.ai

For e-commerce support teams on Gorgias: work the ticket queue from a saved view, read the full conversation, reply on the ticket's own channel, tag and close tickets, and pull up the shopper's customer profile and your team's macros.

Connect this API to an AI agent Browse all specs

What you can do with Gorgias Helpdesk Tickets & Customers via MCP

Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.

MethodPathOperationDescription
GET /api/tickets listTickets List tickets, optionally from a saved view or for one customer
GET /api/tickets/{id} getTicket Get a ticket with status, assignee, tags and messages
PUT /api/tickets/{id} updateTicket Change a ticket's status, assignee, priority or subject
GET /api/messages listMessages List messages, e.g. all messages of one ticket
POST /api/tickets/{ticket_id}/messages createTicketMessage Reply to a ticket or add an internal note
POST /api/tickets/{ticket_id}/tags addTicketTags Add tags to a ticket
GET /api/customers listCustomers Find customers by email or name
GET /api/customers/{id} getCustomer Get a customer's profile, channels and integration data
GET /api/macros listMacros List or search saved reply macros
GET /api/macros/{id} getMacro Get a macro's reply text and actions
GET /api/tags listTags List the account's ticket tags

Authentication

basicAuth

HTTP Basic

HTTP basic auth: your Gorgias login email as the username and a REST API key as the password.

How to get a credential

  1. In Gorgias, open Settings > REST API (https://<your-domain>.gorgias.com/app/settings/api).
  2. Copy the Username (your account email) and click Create API Key (or copy the existing key).
  3. Note your Base API URL subdomain (<your-domain>.gorgias.com); it is the server variable for this spec.

Permissions used

API keys act as the user who created them, so the user's role decides access.

Role needed Operations
Any agent (read) listTickets, getTicket, listMessages, listCustomers, getCustomer, listMacros, getMacro, listTags
Agent with ticket access updateTicket, createTicketMessage, addTicketTags

Common errors

  • 401 Unauthorized: wrong email/API key pair, or the key was deleted. Recreate the key in Settings > REST API.
  • 403 Forbidden: the user's role cannot see that ticket or view; use an admin or lead agent account.
  • 400 Bad Request: invalid body, e.g. a message without channel, via, source or sender, or an unknown status.
  • 429 Too Many Requests: Gorgias allows about 40 requests per 20 seconds per key; wait for Retry-After and retry.

Store the email and key as a VX Agents credential so they are never pasted into chat.

Usage guide

Setup

  • Add a Basic credential: username = your Gorgias login email, password = a REST API key (Settings > REST API).
  • Set the domain server variable to your subdomain (acme for acme.gorgias.com). Every call goes to that tenant.
  • Worth pinning: the view_id of the queue you work (open the view in Gorgias; the id is in the URL).

Work a ticket

  1. listTickets with view_id (a saved view such as "Unassigned") or customer_id, order_by=updated_datetime:desc, trashed=false.
  2. getTicket for status, assignee, tags, channel and the customer.
  3. listMessages with ticket_id to read the conversation in order (order_by=created_datetime:asc).
  4. getCustomer for the shopper's channels and data from connected apps such as Shopify; listCustomers with email finds a customer by address.
  5. listMacros with search to find a saved reply, then getMacro to read its text.
  6. Draft the reply, show it to the user and wait for confirmation, then createTicketMessage with channel (same as the ticket, e.g. email, chat), from_agent: true, via: "api", body_text/body_html, sender: {"email": "<agent email>"} and source: {"type": "<channel>", "from": {...}, "to": [{...}]}. For an internal note use channel: "internal-note", source.type: "internal-note", public: false.
  7. addTicketTags with names (e.g. ["refund"]), then updateTicket with status: "closed" or an assignee_user: {"id": ...}; confirm with the user first.

Good to know

  • Replies on email, chat or social channels are sent to the customer immediately; there is no undo.
  • Ids are integers. Times are ISO 8601 UTC (2026-10-21T09:00:00Z).
  • Lists use cursor pagination: pass meta.next_cursor from the previous response as cursor; limit max 100.
  • listTickets returns trashed tickets unless trashed=false.
  • addTicketTags appends; unknown tag names are created.
  • Rate limit is about 40 requests per 20 seconds per API key.
  • This spec cannot delete or merge tickets, customers or tags.

Source: Gorgias REST API reference (https://developers.gorgias.com/reference/introduction), checked 2026-10-21.

How to use this spec

  1. Create a free VX Agents account (sandbox tools included).
  2. Open the marketplace and connect “Gorgias Helpdesk Tickets & Customers” to an agent.
  3. Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.

Related APIs