SupportBee MCP by usefulapi

List tickets of the shared inbox, newest activity first, with filters (assignee, team, label, requester, dates, spam/trash/archived). By default archived, spam and trashed tickets are left out. Each ticket has id, subject, labels, requester, assignee, replies_count, comments_count, unanswered, archived and the first message text (cut). With total_only=true only the number of matching tickets comes back. GET /tickets.

{
  "type": "object",
  "properties": {
    "archived": {
      "description": "true = only archived tickets, false = no archived tickets (default), any = both.",
      "type": "string",
      "enum": [
        "true",
        "false",
        "any"
      ]
    },
    "spam": {
      "description": "Include tickets marked as spam (default false).",
      "type": "boolean"
    },
    "trash": {
      "description": "Include trashed tickets (default false).",
      "type": "boolean"
    },
    "has_replies": {
      "description": "true = only tickets that have replies, false = only tickets without replies.",
      "type": "boolean"
    },
    "max_replies": {
      "description": "Only tickets with this number of replies (not with has_replies=false).",
      "type": "integer",
      "minimum": 0,
      "maximum": 1000
    },
    "assigned_user": {
      "description": "me = assigned to the token's user, an agent id (from supportbee_list_users), any = assigned to someone, none = unassigned.",
      "type": "string",
      "pattern": "^(me|any|none|\\d{1,12})$"
    },
    "assigned_team": {
      "description": "mine = assigned to the user's teams, a team id (from supportbee_list_teams), none = no team.",
      "type": "string",
      "pattern": "^(mine|none|\\d{1,12})$"
    },
    "label": {
      "description": "Only tickets with this label name (supportbee_list_labels).",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "since": {
      "type": "string",
      "pattern": "^(\\d{4}-\\d{2}-\\d{2}([T ]\\d{2}:\\d{2}(:\\d{2}(\\.\\d+)?)?(Z|[+-]\\d{2}:?\\d{2})?)?|\\d{9,11})$",
      "description": "Only tickets with last activity after this time (date, ISO date-time or Unix timestamp)."
    },
    "until": {
      "type": "string",
      "pattern": "^(\\d{4}-\\d{2}-\\d{2}([T ]\\d{2}:\\d{2}(:\\d{2}(\\.\\d+)?)?(Z|[+-]\\d{2}:?\\d{2})?)?|\\d{9,11})$",
      "description": "Only tickets with last activity before this time (date, ISO date-time or Unix timestamp)."
    },
    "sort_by": {
      "description": "Sort order (default last_activity).",
      "type": "string",
      "enum": [
        "last_activity",
        "creation_time"
      ]
    },
    "requester_emails": {
      "description": "Only tickets from these requester e-mail addresses (max 10).",
      "minItems": 1,
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 254,
        "format": "email",
        "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
      }
    },
    "total_only": {
      "description": "Return only the total number of matching tickets.",
      "type": "boolean"
    },
    "per_page": {
      "description": "Tickets per page, 1-99 (default 15).",
      "type": "integer",
      "minimum": 1,
      "maximum": 99
    },
    "page": {
      "description": "Page number, 1-based (default 1). Use next_page from the previous reply.",
      "type": "integer",
      "minimum": 1,
      "maximum": 10000
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Full-text search over tickets (subject, body, requester) with SupportBee's search syntax, newest activity first. Spam and trash are excluded unless asked. GET /tickets/search.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500,
      "description": "The search keywords or query."
    },
    "spam": {
      "description": "Include tickets marked as spam (default false).",
      "type": "boolean"
    },
    "trash": {
      "description": "Include trashed tickets (default false).",
      "type": "boolean"
    },
    "per_page": {
      "description": "Tickets per page, 1-99 (default 15).",
      "type": "integer",
      "minimum": 1,
      "maximum": 99
    },
    "page": {
      "description": "Page number, 1-based (default 1). Use next_page from the previous reply.",
      "type": "integer",
      "minimum": 1,
      "maximum": 10000
    }
  },
  "required": [
    "query"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One ticket with subject, requester, labels, assignees, state and the first message text. Replies and comments are separate calls. GET /tickets/{id}.

{
  "type": "object",
  "properties": {
    "ticket_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The SupportBee ticket id (the number in the ticket URL; from supportbee_list_tickets)."
    }
  },
  "required": [
    "ticket_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

The public replies (the conversation with the customer) of a ticket, oldest first, as text. GET /tickets/{id}/replies.

{
  "type": "object",
  "properties": {
    "ticket_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The SupportBee ticket id (the number in the ticket URL; from supportbee_list_tickets)."
    }
  },
  "required": [
    "ticket_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One reply of a ticket (text, replier, cc/bcc). GET /tickets/{ticket_id}/replies/{id}.

{
  "type": "object",
  "properties": {
    "ticket_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The SupportBee ticket id (the number in the ticket URL; from supportbee_list_tickets)."
    },
    "reply_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The reply id (from supportbee_list_replies)."
    }
  },
  "required": [
    "ticket_id",
    "reply_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

The internal comments (visible to agents only, never e-mailed) of a ticket, oldest first, as text. GET /tickets/{id}/comments.

{
  "type": "object",
  "properties": {
    "ticket_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The SupportBee ticket id (the number in the ticket URL; from supportbee_list_tickets)."
    }
  },
  "required": [
    "ticket_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

What happened to a ticket and who did it (assignments, label changes, replies, archiving) with timestamps. GET /tickets/{id}/audit.

{
  "type": "object",
  "properties": {
    "ticket_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The SupportBee ticket id (the number in the ticket URL; from supportbee_list_tickets)."
    }
  },
  "required": [
    "ticket_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

All custom labels of the company (name and color). Use a label name with supportbee_add_label or the label filter. GET /labels.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

The teams of the company (id, name), optionally only those that have users in them, or only the token user's teams. GET /teams.

{
  "type": "object",
  "properties": {
    "with_users": {
      "description": "Only teams that have users in them (SupportBee's with_users filter; it does not add the member list).",
      "type": "boolean"
    },
    "mine_only": {
      "description": "Only the teams of the user who owns the token.",
      "type": "boolean"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

The agents, admins and collaborators of the desk (id, name, e-mail, role, teams), or customer groups. Use the id as assigned_user or user_id. GET /users.

{
  "type": "object",
  "properties": {
    "type": {
      "description": "user (default) or customer_group.",
      "type": "string",
      "enum": [
        "user",
        "customer_group"
      ]
    },
    "with_roles": {
      "description": "Roles to include (default admin, agent, collaborator).",
      "minItems": 1,
      "maxItems": 4,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "admin",
          "agent",
          "collaborator",
          "customer"
        ]
      }
    },
    "with_invited": {
      "description": "Include users who were invited but have not joined yet (default false).",
      "type": "boolean"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One user or customer with role, teams, ticket counts and a few of their recent tickets. GET /users/{id}.

{
  "type": "object",
  "properties": {
    "user_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The user id (from supportbee_list_users)."
    },
    "max_tickets": {
      "description": "How many of the user's tickets to include (default 5).",
      "type": "integer",
      "minimum": 0,
      "maximum": 50
    }
  },
  "required": [
    "user_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

The canned replies (snippets) of the company: name, tags and text, to reuse in a reply. GET /snippets.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

The support e-mail addresses (forwarding addresses) of the desk: id, name, the address tickets arrive at and the from address. GET /emails.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

A report as time-series data points (value, timestamp): tickets_count, replies_count or avg_first_response_time, optionally for one agent, team or label. Needs an admin token. GET /reports/{report}.

{
  "type": "object",
  "properties": {
    "report": {
      "type": "string",
      "enum": [
        "tickets_count",
        "replies_count",
        "avg_first_response_time"
      ],
      "description": "Which report."
    },
    "user": {
      "description": "Only this agent (user id).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "team": {
      "description": "Only this team (team id).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "label": {
      "description": "Only this label (name).",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "since": {
      "type": "string",
      "pattern": "^(\\d{4}-\\d{2}-\\d{2}([T ]\\d{2}:\\d{2}(:\\d{2}(\\.\\d+)?)?(Z|[+-]\\d{2}:?\\d{2})?)?|\\d{9,11})$",
      "description": "Start of the period (date, ISO date-time or Unix timestamp)."
    }
  },
  "required": [
    "report"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: SENDS AN E-MAIL to the customer. Posts a public reply on ONE ticket; SupportBee e-mails it to the ticket's requester and to the cc/bcc addresses you list (at most 10 addresses in total). It cannot be recalled. The reply comes from the token's user. For a note only your team sees, use supportbee_add_comment. POST /tickets/{id}/replies.

{
  "type": "object",
  "properties": {
    "ticket_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The SupportBee ticket id (the number in the ticket URL; from supportbee_list_tickets)."
    },
    "text": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20000,
      "description": "The reply text (plain text; blank lines separate paragraphs)."
    },
    "cc": {
      "description": "Extra recipients in cc (cc + bcc together at most 10).",
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 254,
        "format": "email",
        "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
      }
    },
    "bcc": {
      "description": "Extra recipients in bcc (cc + bcc together at most 10).",
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 254,
        "format": "email",
        "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
      }
    }
  },
  "required": [
    "ticket_id",
    "text"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: adds an internal comment to a ticket. Comments are visible to your agents only and are never e-mailed to the customer. POST /tickets/{id}/comments.

{
  "type": "object",
  "properties": {
    "ticket_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The SupportBee ticket id (the number in the ticket URL; from supportbee_list_tickets)."
    },
    "text": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20000,
      "description": "The comment text (plain text; blank lines separate paragraphs)."
    }
  },
  "required": [
    "ticket_id",
    "text"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: adds an existing label to a ticket (404 if the label does not exist; names come from supportbee_list_labels). Safe to repeat. POST /tickets/{id}/labels/{label}.

{
  "type": "object",
  "properties": {
    "ticket_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The SupportBee ticket id (the number in the ticket URL; from supportbee_list_tickets)."
    },
    "label": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "The label name, exactly as in supportbee_list_labels."
    }
  },
  "required": [
    "ticket_id",
    "label"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: removes a label from a ticket (the label itself stays; 404 if the ticket does not have it). DELETE /tickets/{id}/labels/{label}.

{
  "type": "object",
  "properties": {
    "ticket_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The SupportBee ticket id (the number in the ticket URL; from supportbee_list_tickets)."
    },
    "label": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "The label name."
    }
  },
  "required": [
    "ticket_id",
    "label"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: assigns a ticket to ONE agent (user_id) or ONE team (team_id), not both. A ticket that belongs to a team can only go to a member of that team; assigning to another team removes the user assignee. The customer is not e-mailed (SupportBee may notify the assigned agent). POST /tickets/{id}/user_assignment or /team_assignment.

{
  "type": "object",
  "properties": {
    "ticket_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The SupportBee ticket id (the number in the ticket URL; from supportbee_list_tickets)."
    },
    "user_id": {
      "description": "The agent id (supportbee_list_users).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "team_id": {
      "description": "The team id (supportbee_list_teams).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "ticket_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: clears the user assignee or the team assignee of a ticket. DELETE /tickets/{id}/user_assignment or /team_assignment.

{
  "type": "object",
  "properties": {
    "ticket_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The SupportBee ticket id (the number in the ticket URL; from supportbee_list_tickets)."
    },
    "assignee": {
      "type": "string",
      "enum": [
        "user",
        "team"
      ],
      "description": "Which assignment to clear."
    }
  },
  "required": [
    "ticket_id",
    "assignee"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: archives a ticket (archived=true, it leaves the open inbox) or moves it back (archived=false). Nothing is deleted or sent. POST/DELETE /tickets/{id}/archive.

{
  "type": "object",
  "properties": {
    "ticket_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The SupportBee ticket id (the number in the ticket URL; from supportbee_list_tickets)."
    },
    "archived": {
      "type": "boolean",
      "description": "true = archive, false = move back to the inbox."
    }
  },
  "required": [
    "ticket_id",
    "archived"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: marks a ticket as answered (answered=true) or unanswered (answered=false) without sending anything. POST/DELETE /tickets/{id}/answered.

{
  "type": "object",
  "properties": {
    "ticket_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The SupportBee ticket id (the number in the ticket URL; from supportbee_list_tickets)."
    },
    "answered": {
      "type": "boolean",
      "description": "true = mark answered, false = mark unanswered."
    }
  },
  "required": [
    "ticket_id",
    "answered"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}