{"openapi":"3.1.0","info":{"title":"Zammad (BYOK) API","version":"0.1.0","description":"Zammad (BYOK) lets an AI assistant read your own Zammad data through the Zammad API with a key you supply (Zammad API access token (profile > Token Access)). Read-only: 10 tools (list_tickets, get_ticket, search_tickets, list_ticket_articles, list_users, search_users, list_organizations, list_groups, list_ticket_states, list_ticket_priorities). The BYOK key travels with each request, is used for...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-zammad.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-zammad/docs"},"termsOfService":"https://connectorbay.com/byok-zammad/terms"},"servers":[{"url":"https://byok-zammad.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-zammad/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/list_tickets":{"post":{"operationId":"list_tickets","summary":"List Zammad tickets visible to the token's user with title, state, priority, group, owner, customer and dates. Ids are n","description":"List Zammad tickets visible to the token's user with title, state, priority, group, owner, customer and dates. Ids are numeric; use list_ticket_states and list_ticket_priorities to translate them or set expand. Use for \"Show my newest Zammad tickets\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"subdomain":{"description":"Your Zammad Cloud subdomain, the part before .zammad.com (for example 'acme' for acme.zammad.com). Self-hosted Zammad is not supported.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Subdomain","type":"string"},"expand":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to add the names of related objects (state, priority, group, customer, owner) next to the ids.","title":"Expand"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many results to return (the server enforces its own hard maximum).","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"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 Zammad ticket by numeric id with state, priority, owner, customer, group and escalation dates. Use for \"Show Zam","description":"Get one Zammad ticket by numeric id with state, priority, owner, customer, group and escalation dates. Use for \"Show Zammad ticket 12\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"subdomain":{"description":"Your Zammad Cloud subdomain, the part before .zammad.com (for example 'acme' for acme.zammad.com). Self-hosted Zammad is not supported.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Subdomain","type":"string"},"ticket_id":{"description":"Numeric Zammad ticket id (not the ticket number).","maximum":999999999,"minimum":1,"title":"Ticket Id","type":"integer"},"expand":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to add the names of related objects (state, priority, group, customer, owner) next to the ids.","title":"Expand"}},"required":["subdomain","ticket_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/search_tickets":{"post":{"operationId":"search_tickets","summary":"Search Zammad tickets with the search syntax (free text or fields such as state.name:open, customer.email:x, tags:vip). ","description":"Search Zammad tickets with the search syntax (free text or fields such as state.name:open, customer.email:x, tags:vip). Returns matching tickets, 10 per page unless per_page is set. Use for \"Which Zammad tickets are open and mention refund\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"subdomain":{"description":"Your Zammad Cloud subdomain, the part before .zammad.com (for example 'acme' for acme.zammad.com). Self-hosted Zammad is not supported.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Subdomain","type":"string"},"query":{"description":"Search query, for example 'refund AND state.name:open'.","maxLength":300,"title":"Query","type":"string"},"sort_by":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Field to sort by, for example created_at.","title":"Sort By"},"order_by":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"asc or desc.","title":"Order By"},"expand":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to add the names of related objects (state, priority, group, customer, owner) next to the ids.","title":"Expand"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return (the server enforces its own hard maximum).","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["subdomain","query"],"title":"search_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/list_ticket_articles":{"post":{"operationId":"list_ticket_articles","summary":"List the articles (messages, notes) of a Zammad ticket with sender, subject, body and time. Use for \"What was said in Za","description":"List the articles (messages, notes) of a Zammad ticket with sender, subject, body and time. Use for \"What was said in Zammad ticket 12\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"subdomain":{"description":"Your Zammad Cloud subdomain, the part before .zammad.com (for example 'acme' for acme.zammad.com). Self-hosted Zammad is not supported.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Subdomain","type":"string"},"ticket_id":{"description":"Numeric Zammad ticket id.","maximum":999999999,"minimum":1,"title":"Ticket Id","type":"integer"}},"required":["subdomain","ticket_id"],"title":"list_ticket_articlesArguments","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_users":{"post":{"operationId":"list_users","summary":"List Zammad users (agents and customers) with name, email, organization and active flag; needs the agent or admin permis","description":"List Zammad users (agents and customers) with name, email, organization and active flag; needs the agent or admin permission. Use for \"Who are the users in Zammad\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"subdomain":{"description":"Your Zammad Cloud subdomain, the part before .zammad.com (for example 'acme' for acme.zammad.com). Self-hosted Zammad is not supported.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Subdomain","type":"string"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many results to return (the server enforces its own hard maximum).","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["subdomain"],"title":"list_usersArguments","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/search_users":{"post":{"operationId":"search_users","summary":"Search Zammad users by name, email or organization with the search syntax. Use for \"Find the Zammad user jane@example.co","description":"Search Zammad users by name, email or organization with the search syntax. Use for \"Find the Zammad user jane@example.com\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"subdomain":{"description":"Your Zammad Cloud subdomain, the part before .zammad.com (for example 'acme' for acme.zammad.com). Self-hosted Zammad is not supported.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Subdomain","type":"string"},"query":{"description":"Search text or query, for example 'jane@example.com'.","maxLength":300,"title":"Query","type":"string"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return (the server enforces its own hard maximum).","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["subdomain","query"],"title":"search_usersArguments","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_organizations":{"post":{"operationId":"list_organizations","summary":"List Zammad organizations with name, domain, VIP and shared flags and member ids. Use for \"Which organizations are in Za","description":"List Zammad organizations with name, domain, VIP and shared flags and member ids. Use for \"Which organizations are in Zammad\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"subdomain":{"description":"Your Zammad Cloud subdomain, the part before .zammad.com (for example 'acme' for acme.zammad.com). Self-hosted Zammad is not supported.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Subdomain","type":"string"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many results to return (the server enforces its own hard maximum).","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["subdomain"],"title":"list_organizationsArguments","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_groups":{"post":{"operationId":"list_groups","summary":"List Zammad groups with name, active flag and member ids; needs the admin permission. Use for \"What groups does Zammad h","description":"List Zammad groups with name, active flag and member ids; needs the admin permission. Use for \"What groups does Zammad have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"subdomain":{"description":"Your Zammad Cloud subdomain, the part before .zammad.com (for example 'acme' for acme.zammad.com). Self-hosted Zammad is not supported.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Subdomain","type":"string"}},"required":["subdomain"],"title":"list_groupsArguments","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_ticket_states":{"post":{"operationId":"list_ticket_states","summary":"List Zammad ticket states (new, open, pending, closed ...) with their ids. Use for \"What do Zammad state ids mean\".","description":"List Zammad ticket states (new, open, pending, closed ...) with their ids. Use for \"What do Zammad state ids mean\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"subdomain":{"description":"Your Zammad Cloud subdomain, the part before .zammad.com (for example 'acme' for acme.zammad.com). Self-hosted Zammad is not supported.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Subdomain","type":"string"}},"required":["subdomain"],"title":"list_ticket_statesArguments","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_ticket_priorities":{"post":{"operationId":"list_ticket_priorities","summary":"List Zammad ticket priorities with their ids. Use for \"What do Zammad priority ids mean\".","description":"List Zammad ticket priorities with their ids. Use for \"What do Zammad priority ids mean\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"subdomain":{"description":"Your Zammad Cloud subdomain, the part before .zammad.com (for example 'acme' for acme.zammad.com). Self-hosted Zammad is not supported.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Subdomain","type":"string"}},"required":["subdomain"],"title":"list_ticket_prioritiesArguments","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}}}}