A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Gorgias API is how an app or AI agent works with a support helpdesk: reading and replying to tickets, creating and merging customers, applying tags and macros, and managing the agents who handle conversations. Access is granted either through an API key with full account access or through an OAuth 2.0 token whose granular scopes set which resources a call can read or write. Activity is recorded as events, which an HTTP integration can also receive at a registered URL when something happens.
How an app or AI agent connects to Gorgias determines what it can reach. There is a route for making calls, a route for receiving events through HTTP integrations, and a hosted server that exposes Gorgias tools to agents, and each is governed by the credential behind it and the permissions it carries.
The REST API answers on each account's own subdomain at https://{subdomain}.gorgias.com/api. It takes JSON request bodies, returns JSON, and pages through lists with a cursor. A call authenticates with either an API key over HTTP Basic auth or an OAuth 2.0 Bearer token.
An HTTP integration registers a URL, an HTTP method, and a set of triggers like ticket-created, ticket-updated, or ticket-message-created. Gorgias then sends a request to that URL when a matching event occurs, so an integration receives activity without polling. The request body can carry templated values such as the ticket id.
A hosted Model Context Protocol server at https://mcp.gorgias.com/mcp exposes Gorgias tools to AI assistants, currently in beta and available on all Helpdesk plans. It connects through a browser-based sign-in on the account subdomain, and access follows the connecting user's helpdesk role. It exposes helpdesk data and settings such as tickets, tags, macros, help center articles, rules, and AI Agent configuration.
A private app authenticates with HTTP Basic auth, where the username is the email of the Gorgias account and the password is the API key. An API key has full access to the account and carries no scopes, so it can call every endpoint the account allows. It is created in the account settings and suits a server-side, single-account integration.
A public app uses the OAuth 2.0 authorization-code flow on the account subdomain, sending the user to /oauth/authorize and exchanging the code at /oauth/token for a Bearer access token. The app requests granular scopes, each a read or write variant per resource, such as tickets:read and customers:write, so the token reaches only what was consented. Access tokens expire after 24 hours and the offline scope returns a refresh token.
The Gorgias API is split into areas an agent can act on, like tickets, messages, customers, users, tags, macros, and views. Each area has its own methods, and writes in some areas send replies to customers or delete support history.
List, read, create, update, and delete tickets, the conversations between a support team and a customer.
List, read, create, update, and delete the messages inside a ticket, including replies sent to customers.
List, add, set, and remove the tags applied to a single ticket.
List, read, create, update, delete, and merge the customer records a helpdesk holds.
List, read, create, update, and delete the agents and other users of a helpdesk.
List, read, create, update, delete, and merge the account-wide tags used to label tickets.
List, read, create, update, and delete macros, the saved replies and actions agents apply to tickets.
List, read, create, update, and delete views, the saved filters that group tickets, and list the tickets inside one.
List, read, create, update, and delete the integrations that connect Gorgias to external services, including HTTP integrations that deliver events.
List and read the events that record what happened in an account, like a ticket being created or a message being sent.
Search across resources such as customers, agents, teams, tags, and integrations.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
TicketsList, read, create, update, and delete tickets, the conversations between a support team and a customer.5 | ||||||
| GET | /api/tickets | List tickets, paginated and ordered by the attribute of the given view. | read | tickets:read | Current | |
OAuth apps need tickets:read; an API key has full account access and needs no scope. Acts onticket Permission (capability) tickets:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/tickets/{id} | Retrieve a single ticket by its id. | read | tickets:read | Current | |
Read-only. OAuth scope tickets:read. Acts onticket Permission (capability) tickets:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/tickets | Create a ticket, the conversation between a support team and a customer. | write | tickets:write | Current | |
A core write. OAuth scope tickets:write. Acts onticket Permission (capability) tickets:writeVersionAvailable since the API’s base version Webhook event ticket-createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/tickets/{id} | Update a ticket, such as its status, assignee, or subject. | write | tickets:write | Current | |
Closing, reopening, and reassigning happen here. OAuth scope tickets:write. Acts onticket Permission (capability) tickets:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/tickets/{id} | Delete a ticket. | write | tickets:write | Current | |
Removes the ticket and its conversation. OAuth scope tickets:write. Acts onticket Permission (capability) tickets:writeVersionAvailable since the API’s base version Webhook event ticket-deletedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Ticket messagesList, read, create, update, and delete the messages inside a ticket, including replies sent to customers.5 | ||||||
| GET | /api/messages | List messages matching the given parameters, paginated, optionally filtered by ticket_id. | read | tickets:read | Current | |
Messages live under the tickets scope. OAuth scope tickets:read. Acts onticket message Permission (capability) tickets:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/tickets/{ticket_id}/messages/{id} | Retrieve a single message from a ticket. | read | tickets:read | Current | |
Read-only. OAuth scope tickets:read. Acts onticket message Permission (capability) tickets:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/tickets/{ticket_id}/messages | Create a message in a ticket, which can send a reply to the customer. | write | tickets:write | Current | |
A message is sent unless sent_datetime is set; an action query parameter (force, retry, cancel) controls external sending. OAuth scope tickets:write. Acts onticket message Permission (capability) tickets:writeVersionAvailable since the API’s base version Webhook event ticket-message-createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/tickets/{ticket_id}/messages/{id} | Update a message in a ticket. | write | tickets:write | Current | |
OAuth scope tickets:write. Acts onticket message Permission (capability) tickets:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/tickets/{ticket_id}/messages/{id} | Delete a message from a ticket. | write | tickets:write | Current | |
OAuth scope tickets:write. Acts onticket message Permission (capability) tickets:writeVersionAvailable since the API’s base version Webhook event ticket-message-deletedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Ticket tagsList, add, set, and remove the tags applied to a single ticket.3 | ||||||
| GET | /api/tickets/{ticket_id}/tags | List the tags applied to a single ticket. | read | tickets:read | Current | |
Read-only. OAuth scope tickets:read. Acts onticket tag Permission (capability) tickets:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/tickets/{ticket_id}/tags | Add one or more tags to a ticket without removing existing tags. | write | tickets:write | Current | |
OAuth scope tickets:write. Acts onticket tag Permission (capability) tickets:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/tickets/{ticket_id}/tags | Remove one or more tags from a ticket. | write | tickets:write | Current | |
OAuth scope tickets:write. Acts onticket tag Permission (capability) tickets:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CustomersList, read, create, update, delete, and merge the customer records a helpdesk holds.6 | ||||||
| GET | /api/customers | List customers, paginated, and ordered by their name in alphabetical order. | read | customers:read | Current | |
Read-only. OAuth scope customers:read. Acts oncustomer Permission (capability) customers:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/customers/{id} | Retrieve a single customer by id. | read | customers:read | Current | |
A merged customer returns a 301 redirect to the surviving record. OAuth scope customers:read. Acts oncustomer Permission (capability) customers:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/customers | Create a customer record. | write | customers:write | Current | |
A core write. OAuth scope customers:write. Acts oncustomer Permission (capability) customers:writeVersionAvailable since the API’s base version Webhook event customer-createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/customers/{id} | Update a customer record. | write | customers:write | Current | |
OAuth scope customers:write. Acts oncustomer Permission (capability) customers:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/customers/{id} | Delete a customer record. | write | customers:write | Current | |
OAuth scope customers:write. Acts oncustomer Permission (capability) customers:writeVersionAvailable since the API’s base version Webhook event customer-deletedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/customers/{id}/merge | Merge two customers into one record. | write | customers:write | Current | |
After a merge, requests to the merged customer return a 301 redirect. OAuth scope customers:write. Acts oncustomer Permission (capability) customers:writeVersionAvailable since the API’s base version Webhook event customer-mergedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
UsersList, read, create, update, and delete the agents and other users of a helpdesk.5 | ||||||
| GET | /api/users | List the users of a helpdesk, such as agents. | read | users:read | Current | |
Read-only. OAuth scope users:read. Acts onuser Permission (capability) users:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/users/{id} | Retrieve a single user by id. | read | users:read | Current | |
Read-only. OAuth scope users:read. Acts onuser Permission (capability) users:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/users | Create a user, such as inviting an agent to the helpdesk. | write | users:write | Current | |
Adds someone who can access the helpdesk. OAuth scope users:write. Acts onuser Permission (capability) users:writeVersionAvailable since the API’s base version Webhook event user-createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/users/{id} | Update a user. | write | users:write | Current | |
OAuth scope users:write. Acts onuser Permission (capability) users:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/users/{id} | Delete a user. | write | users:write | Current | |
Removes the person's helpdesk access. OAuth scope users:write. Acts onuser Permission (capability) users:writeVersionAvailable since the API’s base version Webhook event user-deletedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TagsList, read, create, update, delete, and merge the account-wide tags used to label tickets.4 | ||||||
| GET | /api/tags | List the account-wide tags used to label tickets. | read | tags:read | Current | |
Read-only. OAuth scope tags:read. Acts ontag Permission (capability) tags:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/tags | Create an account-wide tag. | write | tags:write | Current | |
OAuth scope tags:write. Acts ontag Permission (capability) tags:writeVersionAvailable since the API’s base version Webhook event tag-createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/tags/{id} | Update an account-wide tag. | write | tags:write | Current | |
OAuth scope tags:write. Acts ontag Permission (capability) tags:writeVersionAvailable since the API’s base version Webhook event tag-updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/tags/merge | Merge tags into a single tag. | write | tags:write | Current | |
OAuth scope tags:write. Acts ontag Permission (capability) tags:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
MacrosList, read, create, update, and delete macros, the saved replies and actions agents apply to tickets.4 | ||||||
| GET | /api/macros | List macros, the saved replies and actions agents apply to tickets. | read | macros:read | Current | |
Read-only. OAuth scope macros:read. Acts onmacro Permission (capability) macros:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/macros/{id} | Retrieve a single macro by id. | read | macros:read | Current | |
Read-only. OAuth scope macros:read. Acts onmacro Permission (capability) macros:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/macros | Create a macro. | write | macros:write | Current | |
OAuth scope macros:write. Acts onmacro Permission (capability) macros:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/macros/{id} | Update a macro. | write | macros:write | Current | |
OAuth scope macros:write. Acts onmacro Permission (capability) macros:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ViewsList, read, create, update, and delete views, the saved filters that group tickets, and list the tickets inside one.4 | ||||||
| GET | /api/views | List views, the saved filters that group tickets. | read | tickets:read | Current | |
Views fall under the tickets scope. OAuth scope tickets:read. Acts onview Permission (capability) tickets:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/views/{id} | Retrieve a single view by id. | read | tickets:read | Current | |
Read-only. OAuth scope tickets:read. Acts onview Permission (capability) tickets:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/views/{view_id}/items | List a view's items, paginated and ordered by the attribute specified in the view. | read | tickets:read | Current | |
Returns the tickets that match the view. OAuth scope tickets:read. Acts onview Permission (capability) tickets:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/views | Create a view. | write | tickets:write | Current | |
OAuth scope tickets:write. Acts onview Permission (capability) tickets:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
IntegrationsList, read, create, update, and delete the integrations that connect Gorgias to external services, including HTTP integrations that deliver events.4 | ||||||
| GET | /api/integrations | List the integrations that connect Gorgias to external services. | read | integrations:read | Current | |
Read-only. OAuth scope integrations:read. Acts onintegration Permission (capability) integrations:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/integrations/{id} | Retrieve a single integration by id. | read | integrations:read | Current | |
Read-only. OAuth scope integrations:read. Acts onintegration Permission (capability) integrations:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/integrations | Create an integration, including an HTTP integration that delivers events to a URL. | write | integrations:write | Current | |
An HTTP integration sets a type of http with a URL, method, and triggers like ticket-created. OAuth scope integrations:write. Acts onintegration Permission (capability) integrations:writeVersionAvailable since the API’s base version Webhook event integration-createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/integrations/{id} | Delete an integration. | write | integrations:write | Current | |
OAuth scope integrations:write. Acts onintegration Permission (capability) integrations:writeVersionAvailable since the API’s base version Webhook event integration-deletedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
EventsList and read the events that record what happened in an account, like a ticket being created or a message being sent.2 | ||||||
| GET | /api/events | List events, paginated and ordered by creation date with the most recent first. | read | events:read | Current | |
Read-only. OAuth scope events:read. Acts onevent Permission (capability) events:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/events/{id} | Retrieve a single event by id. | read | events:read | Current | |
Read-only. OAuth scope events:read. Acts onevent Permission (capability) events:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SearchSearch across resources such as customers, agents, teams, tags, and integrations.1 | ||||||
| POST | /api/search | Search across resources such as customers, agents, teams, tags, and integrations. | read | — | Current | |
A type parameter selects what to search, such as customer or customer_profile. The scope needed depends on the resource type searched. Acts onsearch result Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Gorgias can notify an app when something happens in a helpdesk, like a ticket being created or a message being sent. An HTTP integration registers a URL and a set of triggers, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
ticket-created | A ticket was created in the helpdesk. | /api/tickets |
ticket-deleted | A ticket was deleted. | /api/tickets/{id} |
ticket-message-created | A message was created in a ticket, such as a reply sent to a customer. | /api/tickets/{ticket_id}/messages |
ticket-message-deleted | A message was deleted from a ticket. | /api/tickets/{ticket_id}/messages/{id} |
customer-created | A customer record was created. | /api/customers |
customer-merged | Two customer records were merged into one. | /api/customers/{id}/merge |
customer-deleted | A customer record was deleted. | /api/customers/{id} |
user-created | A user was added to the helpdesk. | /api/users |
user-deleted | A user was removed from the helpdesk. | /api/users/{id} |
tag-created | An account-wide tag was created. | /api/tags |
tag-updated | An account-wide tag was updated. | /api/tags/{id} |
integration-created | An integration was created, including an HTTP integration that delivers events. | /api/integrations |
integration-deleted | An integration was deleted. | /api/integrations/{id} |
Gorgias limits how fast an app can call, by a request count measured over a rolling window that depends on the authentication method and the account plan.
Gorgias meters requests by count over a rolling window, enforced per account with a leaky bucket so the allowance replenishes over time rather than resetting all at once. An API key integration gets 40 requests in a 20-second window, and an OAuth 2.0 app gets 80 requests in a 20-second window; Enterprise accounts get the same counts in a shorter 10-second window, so the allowance refills faster. The limit is shared across every integration on the account. Each response carries an X-Gorgias-Account-Api-Call-Limit header showing usage against the limit, like 10/80. Going over returns HTTP 429 with a Retry-After header giving the seconds to wait, and the over-limit request is dropped.
Lists are cursor-based, having replaced an earlier offset model. A request sets limit for the page size, defaulting to 30, and passes the cursor value to move through the list. The response carries a meta object with prev_cursor and next_cursor, alongside the data array, the object type, and the request uri. Following next_cursor walks forward until it is absent.
A ticket subject is limited to 998 characters. File uploads over the size limit return HTTP 413 Payload Too Large. The default page size is 30 items.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Bad Request | The request was invalid, with a missing or invalid parameter or an unknown field specified. | Read the error message, fix the parameters, and resend. The request is not retryable as-is. |
| 401 | Unauthorized | The request was not authenticated, because the API key or token is missing, invalid, or expired. | Send valid credentials, and refresh an expired OAuth access token. |
| 403 | Forbidden | The credential does not have permission for this request, for example an OAuth token without the needed scope. | Grant the missing scope on the OAuth app, or use a credential with access to the resource. |
| 404 | Not Found | The requested resource does not exist, for example a deleted ticket or customer. | Confirm the id and that the resource still exists. |
| 409 | Conflict | The request tried to create or update a resource with a duplicate identifier. | Resolve the conflict, such as using a unique identifier, and retry. |
| 413 | Payload Too Large | The payload is too large, most often a file upload over the limit. | Reduce the payload or file size and resend. |
| 429 | Too Many Requests | Too many requests were made in the rate-limit window. The dropped request is not processed. | Wait the number of seconds in the Retry-After header, then retry, and smooth the request rate. |
| 500 | Internal Server Error | The request was valid but something went wrong on Gorgias's side. It is rare. | Retry with backoff, and contact Gorgias support if it persists. |
Gorgias serves a single v1 API per account on the account's own subdomain, and ships dated changes through its developer changelog rather than minting new version numbers.
Gorgias serves a single v1 REST API per account on the account's own subdomain. There are no dated API versions to pin; changes are announced through the developer changelog and integrations adjust as they land. Recent changelog entries cover audit log retention, rate limit improvements, and pagination format changes.
The self-service-overview option was removed from the Statistics API.
Requests to a merged customer now return a 301 redirect to the surviving record.
The HTTP PUT method was removed from the ticket search endpoint.
Track the changelog and adjust when a dated change lands.
Gorgias API changelog ↗Bollard AI sits between a team's AI agents and Gorgias. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.