{"openapi":"3.1.0","info":{"title":"Gorgias (BYOK) API","version":"0.1.0","description":"Gorgias (BYOK) lets an AI assistant read your own Gorgias data through the Gorgias API with a key you supply (your Gorgias account email address (the API username)). Read-only: 9 tools (get_account, list_tickets, get_ticket, list_messages, get_customer, list_tags, list_views, list_custom_fields, list_integrations). The BYOK key travels with each request, is used for that one call only and is...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-gorgias.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-gorgias/docs"},"termsOfService":"https://connectorbay.com/byok-gorgias/terms"},"servers":[{"url":"https://byok-gorgias.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-gorgias/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_account":{"post":{"operationId":"get_account","summary":"Show the Gorgias account the key belongs to: domain, creation time and settings. Use for \"Which Gorgias account am I con","description":"Show the Gorgias account the key belongs to: domain, creation time and settings. Use for \"Which Gorgias account am I connected to\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"subdomain":{"description":"Your Gorgias subdomain: the part before .gorgias.com, for example 'mystore' for mystore.gorgias.com.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Subdomain","type":"string"}},"required":["subdomain"],"title":"get_accountArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_tickets":{"post":{"operationId":"list_tickets","summary":"List tickets with subject, status, priority, channel, customer, assignee, tags and dates, newest or oldest first. Cursor","description":"List tickets with subject, status, priority, channel, customer, assignee, tags and dates, newest or oldest first. Cursor-paged. Use for \"Show the latest open Gorgias tickets\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"subdomain":{"description":"Your Gorgias subdomain: the part before .gorgias.com, for example 'mystore' for mystore.gorgias.com.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Subdomain","type":"string"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"Maximum number of tickets to return (the account's maximum applies, typically 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from meta.next_cursor of the previous answer for the next page; empty for the first page.","title":"Cursor"},"order_by":{"anyOf":[{"enum":["created_datetime:asc","created_datetime:desc","updated_datetime:asc","updated_datetime:desc"],"type":"string"},{"type":"null"}],"default":"created_datetime:desc","description":"Order: one of created_datetime:asc, created_datetime:desc, updated_datetime:asc, updated_datetime:desc.","title":"Order By"},"customer_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only tickets of this customer ID.","title":"Customer Id"},"view_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only tickets matching the filters of this view ID (see list_views).","title":"View Id"},"trashed":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include trashed tickets.","title":"Trashed"}},"required":["subdomain"],"title":"list_ticketsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_ticket":{"post":{"operationId":"get_ticket","summary":"Get one ticket by ID with subject, status, priority, channel, customer, assignee, tags, summary and dates. Use list_mess","description":"Get one ticket by ID with subject, status, priority, channel, customer, assignee, tags, summary and dates. Use list_messages for the conversation. Use for \"Show Gorgias ticket 12345\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"subdomain":{"description":"Your Gorgias subdomain: the part before .gorgias.com, for example 'mystore' for mystore.gorgias.com.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Subdomain","type":"string"},"id":{"description":"Ticket ID.","title":"Id","type":"integer"}},"required":["subdomain","id"],"title":"get_ticketArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_messages":{"post":{"operationId":"list_messages","summary":"List messages (customer messages, replies and internal notes) with sender, subject, text and send time, optionally for o","description":"List messages (customer messages, replies and internal notes) with sender, subject, text and send time, optionally for one ticket. Cursor-paged. Use for \"What are the messages on Gorgias ticket 12345\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"subdomain":{"description":"Your Gorgias subdomain: the part before .gorgias.com, for example 'mystore' for mystore.gorgias.com.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Subdomain","type":"string"},"ticket_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only messages of this ticket ID.","title":"Ticket Id"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"Maximum number of items to return (the account's maximum applies, typically 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from meta.next_cursor of the previous answer for the next page; empty for the first page.","title":"Cursor"},"order_by":{"anyOf":[{"enum":["created_datetime:asc","created_datetime:desc"],"type":"string"},{"type":"null"}],"default":"created_datetime:asc","description":"Order: one of created_datetime:asc, created_datetime:desc.","title":"Order By"}},"required":["subdomain"],"title":"list_messagesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_customer":{"post":{"operationId":"get_customer","summary":"Get one customer by ID with name, email, language, timezone, note and creation time. Use for \"Show Gorgias customer 678\"","description":"Get one customer by ID with name, email, language, timezone, note and creation time. Use for \"Show Gorgias customer 678\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"subdomain":{"description":"Your Gorgias subdomain: the part before .gorgias.com, for example 'mystore' for mystore.gorgias.com.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Subdomain","type":"string"},"id":{"description":"Customer ID.","title":"Id","type":"integer"}},"required":["subdomain","id"],"title":"get_customerArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_tags":{"post":{"operationId":"list_tags","summary":"List ticket tags with name, description and usage count, optionally searched by name. Cursor-paged. Use for \"Which tags ","description":"List ticket tags with name, description and usage count, optionally searched by name. Cursor-paged. Use for \"Which tags do we use in Gorgias\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"subdomain":{"description":"Your Gorgias subdomain: the part before .gorgias.com, for example 'mystore' for mystore.gorgias.com.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Subdomain","type":"string"},"search":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only tags whose name contains this text (case insensitive).","title":"Search"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"Maximum number of items to return (the account's maximum applies, typically 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from meta.next_cursor of the previous answer for the next page; empty for the first page.","title":"Cursor"},"order_by":{"anyOf":[{"enum":["created_datetime:asc","created_datetime:desc","name:asc","name:desc"],"type":"string"},{"type":"null"}],"default":"name:asc","description":"Order: one of created_datetime:asc, created_datetime:desc, name:asc, name:desc.","title":"Order By"}},"required":["subdomain"],"title":"list_tagsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_views":{"post":{"operationId":"list_views","summary":"List ticket and customer views (saved filters) with name, category, visibility and ordering. Cursor-paged. Use for \"What","description":"List ticket and customer views (saved filters) with name, category, visibility and ordering. Cursor-paged. Use for \"What ticket views exist in Gorgias\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"subdomain":{"description":"Your Gorgias subdomain: the part before .gorgias.com, for example 'mystore' for mystore.gorgias.com.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Subdomain","type":"string"},"category":{"anyOf":[{"enum":["system","user"],"type":"string"},{"type":"null"}],"default":null,"description":"Only system or user views.","title":"Category"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"Maximum number of items to return (the account's maximum applies, typically 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from meta.next_cursor of the previous answer for the next page; empty for the first page.","title":"Cursor"},"order_by":{"anyOf":[{"enum":["created_datetime:asc","created_datetime:desc"],"type":"string"},{"type":"null"}],"default":"created_datetime:asc","description":"Order: one of created_datetime:asc, created_datetime:desc.","title":"Order By"}},"required":["subdomain"],"title":"list_viewsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_custom_fields":{"post":{"operationId":"list_custom_fields","summary":"List the custom fields defined for tickets or customers with label, description, required flag and priority. Cursor-page","description":"List the custom fields defined for tickets or customers with label, description, required flag and priority. Cursor-paged. Use for \"Which custom ticket fields are set up in Gorgias\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"subdomain":{"description":"Your Gorgias subdomain: the part before .gorgias.com, for example 'mystore' for mystore.gorgias.com.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Subdomain","type":"string"},"object_type":{"description":"Which entity the fields belong to: Ticket or Customer.","enum":["Ticket","Customer"],"title":"Object Type","type":"string"},"archived":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True for archived fields only, false for active ones.","title":"Archived"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"Maximum number of items to return (the account's maximum applies, typically 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from meta.next_cursor of the previous answer for the next page; empty for the first page.","title":"Cursor"}},"required":["subdomain","object_type"],"title":"list_custom_fieldsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_integrations":{"post":{"operationId":"list_integrations","summary":"List connected integrations (email, chat, Shopify, phone and so on) with name, type and status. Cursor-paged. Use for \"W","description":"List connected integrations (email, chat, Shopify, phone and so on) with name, type and status. Cursor-paged. Use for \"Which integrations are connected to Gorgias\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"subdomain":{"description":"Your Gorgias subdomain: the part before .gorgias.com, for example 'mystore' for mystore.gorgias.com.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Subdomain","type":"string"},"type":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only integrations of this type, for example email, gorgias_chat, shopify, http.","title":"Type"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"Maximum number of items to return (the account's maximum applies, typically 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from meta.next_cursor of the previous answer for the next page; empty for the first page.","title":"Cursor"}},"required":["subdomain"],"title":"list_integrationsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}