{"openapi":"3.1.0","info":{"title":"Freshdesk (BYOK) API","version":"0.1.0","description":"Freshdesk (BYOK) lets an AI assistant read your own Freshdesk data through the Freshdesk API with a key you supply (API key). Read-only: 8 tools (list_tickets, get_ticket, search_tickets, list_ticket_conversations, list_contacts, list_companies, list_agents, list_groups). The BYOK key travels with each request, is used for that one call only and is never stored, logged or cached; it is only ever...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-freshdesk.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-freshdesk/docs"},"termsOfService":"https://connectorbay.com/byok-freshdesk/terms"},"servers":[{"url":"https://byok-freshdesk.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-freshdesk/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 support tickets (only those created in the last 30 days unless updated_since is given) with numeric status (2 open,","description":"List support tickets (only those created in the last 30 days unless updated_since is given) with numeric status (2 open, 3 pending, 4 resolved, 5 closed) and priority (1 low, 2 medium, 3 high, 4 urgent). Use for \"What are my newest Freshdesk tickets\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"domain":{"description":"Your Freshdesk account subdomain, the part before .freshdesk.com (for example 'acme' for acme.freshdesk.com).","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Domain","type":"string"},"filter":{"anyOf":[{"enum":["new_and_my_open","watching","spam","deleted"],"type":"string"},{"type":"null"}],"default":null,"description":"Predefined view: new_and_my_open, watching, spam or deleted. Leave empty for all tickets.","title":"Filter"},"updated_since":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only tickets updated after this ISO 8601 UTC time, for example 2026-01-01T00:00:00Z. Also lifts the 30-day window.","title":"Updated Since"},"order_by":{"anyOf":[{"enum":["created_at","due_by","updated_at","status"],"type":"string"},{"type":"null"}],"default":"created_at","description":"Sort field: created_at, due_by, updated_at or status.","title":"Order By"},"order_type":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":"desc","description":"Sort direction: asc or desc.","title":"Order Type"},"include":{"anyOf":[{"enum":["requester","stats","description"],"type":"string"},{"type":"null"}],"default":null,"description":"Embed extra data in each ticket: requester (name and email), stats (closed, resolved and first response times) or description.","title":"Include"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"How many results to return (1 to 100, default 30).","title":"Per Page"},"page":{"anyOf":[{"maximum":300,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["domain"],"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, plain-text description, tags and custom fields; optionally embed th","description":"Get one ticket by id with subject, status, priority, plain-text description, tags and custom fields; optionally embed the requester, company or stats. Use for \"Show Freshdesk ticket 12\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"domain":{"description":"Your Freshdesk account subdomain, the part before .freshdesk.com (for example 'acme' for acme.freshdesk.com).","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Domain","type":"string"},"ticket_id":{"description":"Numeric ticket id.","title":"Ticket Id","type":"integer"},"include":{"anyOf":[{"enum":["requester","company","stats"],"type":"string"},{"type":"null"}],"default":null,"description":"Embed extra data: requester, company or stats.","title":"Include"}},"required":["domain","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 tickets with Freshdesk's query language over ticket fields such as priority, status, tag, agent_id, group_id and ","description":"Search tickets with Freshdesk's query language over ticket fields such as priority, status, tag, agent_id, group_id and dates; 30 results per page, at most 10 pages. Use for \"Which Freshdesk tickets are urgent or high priority\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"domain":{"description":"Your Freshdesk account subdomain, the part before .freshdesk.com (for example 'acme' for acme.freshdesk.com).","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Domain","type":"string"},"query":{"description":"Query in double quotes, up to 512 characters, for example '\"priority:4 OR priority:3\"' or '\"status:2 AND tag:'billing'\"'. Dates use YYYY-MM-DD.","maxLength":512,"title":"Query","type":"string"},"page":{"anyOf":[{"maximum":10,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, 1 to 10.","title":"Page"}},"required":["domain","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_conversations":{"post":{"operationId":"list_ticket_conversations","summary":"List the replies and notes of a ticket (30 per page) with sender address, direction, private flag and plain-text body. U","description":"List the replies and notes of a ticket (30 per page) with sender address, direction, private flag and plain-text body. Use for \"What was said on Freshdesk ticket 12\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"domain":{"description":"Your Freshdesk account subdomain, the part before .freshdesk.com (for example 'acme' for acme.freshdesk.com).","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Domain","type":"string"},"ticket_id":{"description":"Numeric ticket id.","title":"Ticket Id","type":"integer"},"page":{"anyOf":[{"maximum":300,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1 (30 entries per page).","title":"Page"}},"required":["domain","ticket_id"],"title":"list_ticket_conversationsArguments","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_contacts":{"post":{"operationId":"list_contacts","summary":"List customer contacts (verified and unblocked by default) with name, email, phone, company and language; filter by emai","description":"List customer contacts (verified and unblocked by default) with name, email, phone, company and language; filter by email, phone, company or state. Use for \"Who are my Freshdesk contacts\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"domain":{"description":"Your Freshdesk account subdomain, the part before .freshdesk.com (for example 'acme' for acme.freshdesk.com).","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Domain","type":"string"},"email":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only the contact with this exact email address.","title":"Email"},"phone":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only contacts with this phone number.","title":"Phone"},"mobile":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only contacts with this mobile number.","title":"Mobile"},"company_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only contacts of this company id.","title":"Company Id"},"state":{"anyOf":[{"enum":["blocked","deleted","unverified","verified"],"type":"string"},{"type":"null"}],"default":null,"description":"Contact state: blocked, deleted, unverified or verified.","title":"State"},"updated_since":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only contacts updated after this ISO 8601 UTC time, for example 2026-01-01T00:00:00Z.","title":"Updated Since"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"How many results to return (1 to 100, default 30).","title":"Per Page"},"page":{"anyOf":[{"maximum":300,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["domain"],"title":"list_contactsArguments","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_companies":{"post":{"operationId":"list_companies","summary":"List the companies (customer organizations) of the account with name, description, email domains, tier and renewal date.","description":"List the companies (customer organizations) of the account with name, description, email domains, tier and renewal date. Use for \"Which companies are in my Freshdesk account\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"domain":{"description":"Your Freshdesk account subdomain, the part before .freshdesk.com (for example 'acme' for acme.freshdesk.com).","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Domain","type":"string"},"updated_since":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only companies updated after this ISO 8601 UTC time, for example 2026-01-01T00:00:00Z.","title":"Updated Since"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"How many results to return (1 to 100, default 30).","title":"Per Page"},"page":{"anyOf":[{"maximum":300,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["domain"],"title":"list_companiesArguments","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_agents":{"post":{"operationId":"list_agents","summary":"List support agents with name, email, whether they are available, full-time or occasional, and ticket scope. Use for \"Wh","description":"List support agents with name, email, whether they are available, full-time or occasional, and ticket scope. Use for \"Who are the agents in my Freshdesk account\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"domain":{"description":"Your Freshdesk account subdomain, the part before .freshdesk.com (for example 'acme' for acme.freshdesk.com).","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Domain","type":"string"},"email":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only the agent with this exact email address.","title":"Email"},"state":{"anyOf":[{"enum":["fulltime","occasional"],"type":"string"},{"type":"null"}],"default":null,"description":"Agent type: fulltime or occasional.","title":"State"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"How many results to return (1 to 100, default 30).","title":"Per Page"},"page":{"anyOf":[{"maximum":300,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["domain"],"title":"list_agentsArguments","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 the agent groups (teams) with name, description, escalation setting and auto-assignment flag. Use for \"What support","description":"List the agent groups (teams) with name, description, escalation setting and auto-assignment flag. Use for \"What support groups exist in Freshdesk\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"domain":{"description":"Your Freshdesk account subdomain, the part before .freshdesk.com (for example 'acme' for acme.freshdesk.com).","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Domain","type":"string"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"How many results to return (1 to 100, default 30).","title":"Per Page"},"page":{"anyOf":[{"maximum":300,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["domain"],"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}}}}