{"openapi":"3.1.0","info":{"title":"Wilmo API","version":"2026-11-06","description":"Read tickets, messages and reporting. Every operation is also a tool of Wilmo's MCP server (https://app.wilmo.ai/api/mcp) and a command of the wilmo CLI. Authenticate with a team API key (Settings > API keys) or an OAuth access token. Versions: https://app.wilmo.ai/api/public/v1/api-versions."},"servers":[{"url":"https://app.wilmo.ai"}],"x-wilmo-api-version":"2026-11-06","x-wilmo-api-versions":"https://app.wilmo.ai/api/public/v1/api-versions","components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"A team API key from Settings > API keys."},"oauth":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://app.wilmo.ai/oauth/authorize","tokenUrl":"https://app.wilmo.ai/api/oauth/token","refreshUrl":"https://app.wilmo.ai/api/oauth/token","scopes":{"read:tickets":"Read tickets and messages","read:analytics":"Read reporting and Autopilot"}}}}}},"paths":{"/api/v2/ticket-counts":{"get":{"operationId":"get_ticket_counts","summary":"Get ticket counts for the dashboard","description":"How many of the caller's tickets are open, pending and resolved right now, across every team it reads, and their total. Spam and deleted tickets are not counted. These are the numbers on the dashboard home screen.","tags":["ticket-counts"],"security":[{"apiKey":["read:team"]}],"x-wilmo-scope":"read:team","x-wilmo-mcp-tool":"get_ticket_counts","x-wilmo-since":"2026-11-06","parameters":[{"name":"Wilmo-Organization","in":"header","required":false,"description":"The organization to act in, for a principal that spans several (a person in several organizations).","schema":{"type":"string","format":"uuid"}},{"name":"Wilmo-Version","in":"header","required":false,"description":"The API version to shape the request and response for. Default: the version your API key or grant is pinned to.","schema":{"type":"string","example":"2026-11-06"}}],"responses":{"200":{"description":"The ticket counts","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"openTicketsCount":{"type":"number"},"pendingTicketsCount":{"type":"number"},"resolvedTicketsCount":{"type":"number"},"totalTicketsCount":{"type":"number"}},"required":["openTicketsCount","pendingTicketsCount","resolvedTicketsCount","totalTicketsCount"],"additionalProperties":false}}}},"400":{"description":"- `invalid_input`: the input does not match the schema.\n- `team_required`: Called without a caller: the counts are read for its teams.","content":{"application/json":{"schema":{"type":"object","description":"Every v2 error: one short sentence an agent can act on, a stable code, and where to read more.","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found_error","conflict_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":["string","null"]},"request_id":{"type":["string","null"]},"doc_url":{"type":"string"}},"required":["type","code","message","doc_url"]}},"required":["error"]}}}},"401":{"description":"- `authentication_required`: no valid API key or access token.","content":{"application/json":{"schema":{"type":"object","description":"Every v2 error: one short sentence an agent can act on, a stable code, and where to read more.","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found_error","conflict_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":["string","null"]},"request_id":{"type":["string","null"]},"doc_url":{"type":"string"}},"required":["type","code","message","doc_url"]}},"required":["error"]}}}},"429":{"description":"- `rate_limited`: too many requests; wait for Retry-After seconds.","content":{"application/json":{"schema":{"type":"object","description":"Every v2 error: one short sentence an agent can act on, a stable code, and where to read more.","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found_error","conflict_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":["string","null"]},"request_id":{"type":["string","null"]},"doc_url":{"type":"string"}},"required":["type","code","message","doc_url"]}},"required":["error"]}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}}}}}},"/api/v2/teams":{"get":{"operationId":"list_teams","summary":"List the teams of the organization","description":"Every team (store, market or brand) of the caller's Wilmo organization, by id and name, sorted by name. Each team has its own inbox and AI agent. The ids are the team_id that ticket and analytics reads accept to narrow to one team.","tags":["teams"],"security":[{"apiKey":["read:tickets"]},{"oauth":["read:tickets"]}],"x-wilmo-scope":"read:tickets","x-wilmo-mcp-tool":"list_teams","x-wilmo-since":"2026-11-06","parameters":[{"name":"Wilmo-Organization","in":"header","required":false,"description":"The organization to act in, for a principal that spans several (a person in several organizations).","schema":{"type":"string","format":"uuid"}},{"name":"Wilmo-Version","in":"header","required":false,"description":"The API version to shape the request and response for. Default: the version your API key or grant is pinned to.","schema":{"type":"string","example":"2026-11-06"}}],"responses":{"200":{"description":"The teams, sorted by name","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as cursor for the next page."}},"required":["object","data","has_more","next_cursor"]}}}},"400":{"description":"- `invalid_input`: the input does not match the schema.\n- `team_required`: Called without a caller: there are no teams to list.","content":{"application/json":{"schema":{"type":"object","description":"Every v2 error: one short sentence an agent can act on, a stable code, and where to read more.","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found_error","conflict_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":["string","null"]},"request_id":{"type":["string","null"]},"doc_url":{"type":"string"}},"required":["type","code","message","doc_url"]}},"required":["error"]}}}},"401":{"description":"- `authentication_required`: no valid API key or access token.","content":{"application/json":{"schema":{"type":"object","description":"Every v2 error: one short sentence an agent can act on, a stable code, and where to read more.","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found_error","conflict_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":["string","null"]},"request_id":{"type":["string","null"]},"doc_url":{"type":"string"}},"required":["type","code","message","doc_url"]}},"required":["error"]}}}},"429":{"description":"- `rate_limited`: too many requests; wait for Retry-After seconds.","content":{"application/json":{"schema":{"type":"object","description":"Every v2 error: one short sentence an agent can act on, a stable code, and where to read more.","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found_error","conflict_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":["string","null"]},"request_id":{"type":["string","null"]},"doc_url":{"type":"string"}},"required":["type","code","message","doc_url"]}},"required":["error"]}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}}}}}},"/api/v2/tickets":{"get":{"operationId":"list_tickets","summary":"Search and filter support tickets","description":"Support tickets across every team of the caller's organization (or one team with team_id). With q, a free-text search over ticket number, subject, customer, notes and message text, best match first, each row saying where it matched. Without q, the newest received first. Filters: status, channel, tag, received_after, received_before. Each row: id, number, team, subject, status, channel, customer name and email, tags, how it was answered (autopilot, copilot, human), a short AI summary and dates. Pages of up to 50; pass next_cursor back for more. Read one conversation with get_ticket.","tags":["tickets"],"security":[{"apiKey":["read:tickets"]},{"oauth":["read:tickets"]}],"x-wilmo-scope":"read:tickets","x-wilmo-mcp-tool":"list_tickets","x-wilmo-since":"2026-11-06","parameters":[{"name":"q","in":"query","required":false,"description":"Free text, matched like the inbox search: ticket number, subject, customer name or email, notes and message text. Results are ranked best match first.","schema":{"description":"Free text, matched like the inbox search: ticket number, subject, customer name or email, notes and message text. Results are ranked best match first.","type":"string","minLength":1,"maxLength":200}},{"name":"team_id","in":"query","required":false,"description":"Only this team (an id from list_teams).","schema":{"description":"Only this team (an id from list_teams).","type":"string"}},{"name":"status","in":"query","required":false,"description":"Only tickets with this status.","schema":{"description":"Only tickets with this status.","type":"string","enum":["pending","open","resolved","spam"]}},{"name":"channel","in":"query","required":false,"description":"Only tickets that started on this channel.","schema":{"description":"Only tickets that started on this channel.","type":"string","enum":["email","live_chat","instagram_dm","phone","chatbot","messenger","trustpilot","event"]}},{"name":"tag","in":"query","required":false,"description":"Only tickets carrying this tag (category): its id, or its name (case-insensitive).","schema":{"description":"Only tickets carrying this tag (category): its id, or its name (case-insensitive).","type":"string","minLength":1,"maxLength":200}},{"name":"received_after","in":"query","required":false,"description":"Only tickets received at or after this ISO 8601 date or date-time.","schema":{"description":"Only tickets received at or after this ISO 8601 date or date-time.","anyOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}]}},{"name":"received_before","in":"query","required":false,"description":"Only tickets received before this ISO 8601 date or date-time (exclusive).","schema":{"description":"Only tickets received before this ISO 8601 date or date-time (exclusive).","anyOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}]}},{"name":"limit","in":"query","required":false,"description":"Tickets per page, at most 50.","schema":{"default":25,"description":"Tickets per page, at most 50.","type":"integer","minimum":1,"maximum":50}},{"name":"cursor","in":"query","required":false,"description":"next_cursor of the previous page, with the same filters.","schema":{"description":"next_cursor of the previous page, with the same filters.","type":"string","minLength":1,"maxLength":500}},{"name":"Wilmo-Organization","in":"header","required":false,"description":"The organization to act in, for a principal that spans several (a person in several organizations).","schema":{"type":"string","format":"uuid"}},{"name":"Wilmo-Version","in":"header","required":false,"description":"The API version to shape the request and response for. Default: the version your API key or grant is pinned to.","schema":{"type":"string","example":"2026-11-06"}}],"responses":{"200":{"description":"A page of tickets","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"maxItems":50,"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"ticket_number":{"type":"number"},"team_id":{"type":"string"},"team_name":{"type":["string","null"]},"subject":{"type":"string"},"status":{"type":"string","enum":["pending","open","resolved","spam"]},"channel":{"type":"string","enum":["email","live_chat","instagram_dm","phone","chatbot","messenger","trustpilot","event"]},"customer_name":{"type":["string","null"]},"customer_email":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}},"answered_by":{"anyOf":[{"type":"string","enum":["human","copilot","autopilot"]},{"type":"null"}]},"summary":{"type":["string","null"]},"received_at":{"type":"string"},"updated_at":{"type":"string"},"match":{"anyOf":[{"type":"object","properties":{"source":{"type":"string","enum":["ticket_number","subject","contact_email","contact_name","ticket_note","message"]},"preview":{"type":["string","null"]}},"required":["source","preview"],"additionalProperties":false},{"type":"null"}]}},"required":["id","ticket_number","team_id","team_name","subject","status","channel","customer_name","customer_email","tags","answered_by","summary","received_at","updated_at","match"],"additionalProperties":false}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as cursor for the next page."}},"required":["object","data","has_more","next_cursor"]}}}},"400":{"description":"- `invalid_input`: the input does not match the schema.\n- `team_required`: Called without a caller and without team_id.\n- `invalid`: The cursor is not one this list gave, or not for these filters.","content":{"application/json":{"schema":{"type":"object","description":"Every v2 error: one short sentence an agent can act on, a stable code, and where to read more.","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found_error","conflict_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":["string","null"]},"request_id":{"type":["string","null"]},"doc_url":{"type":"string"}},"required":["type","code","message","doc_url"]}},"required":["error"]}}}},"401":{"description":"- `authentication_required`: no valid API key or access token.","content":{"application/json":{"schema":{"type":"object","description":"Every v2 error: one short sentence an agent can act on, a stable code, and where to read more.","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found_error","conflict_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":["string","null"]},"request_id":{"type":["string","null"]},"doc_url":{"type":"string"}},"required":["type","code","message","doc_url"]}},"required":["error"]}}}},"404":{"description":"- `not_found`: team_id is not a team the caller reads.","content":{"application/json":{"schema":{"type":"object","description":"Every v2 error: one short sentence an agent can act on, a stable code, and where to read more.","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found_error","conflict_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":["string","null"]},"request_id":{"type":["string","null"]},"doc_url":{"type":"string"}},"required":["type","code","message","doc_url"]}},"required":["error"]}}}},"429":{"description":"- `rate_limited`: too many requests; wait for Retry-After seconds.","content":{"application/json":{"schema":{"type":"object","description":"Every v2 error: one short sentence an agent can act on, a stable code, and where to read more.","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found_error","conflict_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":["string","null"]},"request_id":{"type":["string","null"]},"doc_url":{"type":"string"}},"required":["type","code","message","doc_url"]}},"required":["error"]}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}}}}}},"/api/v2/skills":{"get":{"operationId":"list_skills","summary":"List skills","description":"Lists the organization's skills (and its teams' own), newest first, a page at a time (limit up to 100, default 20). search filters by name or slug. Each skill has its name, slug, description, content and folder.","tags":["skills"],"security":[{"apiKey":["read:skills"]}],"x-wilmo-scope":"read:skills","x-wilmo-mcp-tool":"list_skills","x-wilmo-since":"2026-11-06","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0}},{"name":"search","in":"query","required":false,"schema":{"type":"string"}},{"name":"Wilmo-Organization","in":"header","required":false,"description":"The organization to act in, for a principal that spans several (a person in several organizations).","schema":{"type":"string","format":"uuid"}},{"name":"Wilmo-Version","in":"header","required":false,"description":"The API version to shape the request and response for. Default: the version your API key or grant is pinned to.","schema":{"type":"string","example":"2026-11-06"}}],"responses":{"200":{"description":"A page of skills and the total count","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object","properties":{"content":{"type":"string"},"created_at":{"type":"string"},"created_by_user_id":{"type":["string","null"]},"deleted_at":{"type":["string","null"]},"description":{"type":"string"},"folder_id":{"type":["string","null"]},"id":{"type":"string"},"kind":{"type":"string","enum":["router","situations","facts"]},"name":{"type":"string"},"organization_id":{"type":["string","null"]},"position":{"type":"number"},"slug":{"type":"string"},"team_id":{"type":["string","null"]},"updated_at":{"type":"string"},"updated_by_user_id":{"type":["string","null"]}},"required":["content","created_at","created_by_user_id","deleted_at","description","folder_id","id","kind","name","organization_id","position","slug","team_id","updated_at","updated_by_user_id"],"additionalProperties":false}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as cursor for the next page."},"total_count":{"type":"integer","minimum":0}},"required":["object","data","has_more","next_cursor"]}}}},"400":{"description":"- `invalid_input`: the input does not match the schema.","content":{"application/json":{"schema":{"type":"object","description":"Every v2 error: one short sentence an agent can act on, a stable code, and where to read more.","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found_error","conflict_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":["string","null"]},"request_id":{"type":["string","null"]},"doc_url":{"type":"string"}},"required":["type","code","message","doc_url"]}},"required":["error"]}}}},"401":{"description":"- `authentication_required`: no valid API key or access token.","content":{"application/json":{"schema":{"type":"object","description":"Every v2 error: one short sentence an agent can act on, a stable code, and where to read more.","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found_error","conflict_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":["string","null"]},"request_id":{"type":["string","null"]},"doc_url":{"type":"string"}},"required":["type","code","message","doc_url"]}},"required":["error"]}}}},"429":{"description":"- `rate_limited`: too many requests; wait for Retry-After seconds.","content":{"application/json":{"schema":{"type":"object","description":"Every v2 error: one short sentence an agent can act on, a stable code, and where to read more.","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found_error","conflict_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":["string","null"]},"request_id":{"type":["string","null"]},"doc_url":{"type":"string"}},"required":["type","code","message","doc_url"]}},"required":["error"]}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}}}}}},"/api/v2/tags":{"get":{"operationId":"list_tags","summary":"List tags","description":"The tags of the caller's teams and organization, newest first, each with its current version and versions. Page with limit (at most 100) and offset; search by name or key; excludeSystemTags=true leaves out system tags; ids (comma-separated, at most 100) returns exactly those tags.","tags":["tags"],"security":[{"apiKey":["read:tags"]}],"x-wilmo-scope":"read:tags","x-wilmo-mcp-tool":"list_tags","x-wilmo-since":"2026-11-06","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0}},{"name":"search","in":"query","required":false,"schema":{"type":"string"}},{"name":"excludeSystemTags","in":"query","required":true,"schema":{"type":"boolean"}},{"name":"ids","in":"query","required":true,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]}},{"name":"Wilmo-Organization","in":"header","required":false,"description":"The organization to act in, for a principal that spans several (a person in several organizations).","schema":{"type":"string","format":"uuid"}},{"name":"Wilmo-Version","in":"header","required":false,"description":"The API version to shape the request and response for. Default: the version your API key or grant is pinned to.","schema":{"type":"string","example":"2026-11-06"}}],"responses":{"200":{"description":"A page of tags","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object","properties":{"autopilot_lock":{"type":["string","null"]},"channel_types":{"anyOf":[{"type":"array","items":{"type":"string","enum":["email","live_chat","instagram_dm","phone","chatbot","messenger","trustpilot","event"]}},{"type":"null"}]},"created_at":{"type":"string"},"created_by_user_id":{"type":["string","null"]},"current_version_id":{"type":["string","null"]},"deleted_at":{"type":["string","null"]},"folder_id":{"type":["string","null"]},"freshdesk_id":{"type":["string","null"]},"herodesk_id":{"type":["string","null"]},"id":{"type":"string"},"key":{"type":"string"},"organization_id":{"type":["string","null"]},"position":{"type":"number"},"rule":{"anyOf":[{"$ref":"#/definitions/__schema0"},{"type":"null"}]},"source":{"type":"string","enum":["manual","llm","system","integration","rule"]},"team_id":{"type":["string","null"]},"updated_at":{"type":"string"},"zendesk_id":{"type":["string","null"]},"current_version":{"anyOf":[{"type":"object","properties":{"blocks_autopilot":{"type":"boolean"},"color":{"type":"string","enum":["fef3c7","dcfce7","fee2e2","f3f4f6","dbeafe","e9d5ff","fce7f3","fed7aa","ccfbf1","ddd6fe"]},"created_at":{"type":"string"},"created_by_user_id":{"type":["string","null"]},"enable_autopilot":{"type":"boolean"},"id":{"type":"string"},"name":{"type":"string"},"organization_id":{"type":["string","null"]},"prompt":{"type":"string"},"prompt_tokens":{"type":["number","null"]},"tag_id":{"type":"string"},"team_id":{"type":["string","null"]},"updated_at":{"type":"string"}},"required":["blocks_autopilot","color","created_at","created_by_user_id","enable_autopilot","id","name","organization_id","prompt","prompt_tokens","tag_id","team_id","updated_at"],"additionalProperties":false},{"type":"null"}]},"versions":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"blocks_autopilot":{"type":"boolean"},"color":{"type":"string","enum":["fef3c7","dcfce7","fee2e2","f3f4f6","dbeafe","e9d5ff","fce7f3","fed7aa","ccfbf1","ddd6fe"]},"created_at":{"type":"string"},"created_by_user_id":{"type":["string","null"]},"enable_autopilot":{"type":"boolean"},"id":{"type":"string"},"name":{"type":"string"},"organization_id":{"type":["string","null"]},"prompt":{"type":"string"},"prompt_tokens":{"type":["number","null"]},"tag_id":{"type":"string"},"team_id":{"type":["string","null"]},"updated_at":{"type":"string"}},"required":["blocks_autopilot","color","created_at","created_by_user_id","enable_autopilot","id","name","organization_id","prompt","prompt_tokens","tag_id","team_id","updated_at"],"additionalProperties":false}},{"type":"null"}]}},"required":["autopilot_lock","channel_types","created_at","created_by_user_id","current_version_id","deleted_at","folder_id","freshdesk_id","herodesk_id","id","key","organization_id","position","rule","source","team_id","updated_at","zendesk_id","current_version","versions"],"additionalProperties":false}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as cursor for the next page."},"total_count":{"type":"integer","minimum":0}},"required":["object","data","has_more","next_cursor"]}}}},"400":{"description":"- `invalid_input`: the input does not match the schema.","content":{"application/json":{"schema":{"type":"object","description":"Every v2 error: one short sentence an agent can act on, a stable code, and where to read more.","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found_error","conflict_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":["string","null"]},"request_id":{"type":["string","null"]},"doc_url":{"type":"string"}},"required":["type","code","message","doc_url"]}},"required":["error"]}}}},"401":{"description":"- `authentication_required`: no valid API key or access token.","content":{"application/json":{"schema":{"type":"object","description":"Every v2 error: one short sentence an agent can act on, a stable code, and where to read more.","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found_error","conflict_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":["string","null"]},"request_id":{"type":["string","null"]},"doc_url":{"type":"string"}},"required":["type","code","message","doc_url"]}},"required":["error"]}}}},"422":{"description":"- `workspace_required`: Tags are read by a person or an API key, in their workspace.","content":{"application/json":{"schema":{"type":"object","description":"Every v2 error: one short sentence an agent can act on, a stable code, and where to read more.","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found_error","conflict_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":["string","null"]},"request_id":{"type":["string","null"]},"doc_url":{"type":"string"}},"required":["type","code","message","doc_url"]}},"required":["error"]}}}},"429":{"description":"- `rate_limited`: too many requests; wait for Retry-After seconds.","content":{"application/json":{"schema":{"type":"object","description":"Every v2 error: one short sentence an agent can act on, a stable code, and where to read more.","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found_error","conflict_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":["string","null"]},"request_id":{"type":["string","null"]},"doc_url":{"type":"string"}},"required":["type","code","message","doc_url"]}},"required":["error"]}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}}}}}},"/api/v2/ticket-analytics":{"get":{"operationId":"get_ticket_analytics","summary":"Get ticket analytics for a period","description":"The analytics numbers for tickets received between date_from and date_to (ISO 8601 with an offset), across every team the caller reads. Optionally one assigned user, one saved ticket view, some tags (tag_ids, any of them) and one channel. analytics_version 'v1': ticket counts by status and by how they were resolved (a person, Copilot, Autopilot), resolution times, the daily trend and the tag distribution. analytics_version 'v2' (workspaces on the new analytics): customer messages answered by Autopilot, Copilot or a person, in total and per day, week or month, and when Autopilot settings changed.","tags":["ticket-analytics"],"security":[{"apiKey":["read:analytics"]},{"oauth":["read:analytics"]}],"x-wilmo-scope":"read:analytics","x-wilmo-mcp-tool":"get_ticket_analytics","x-wilmo-since":"2026-11-06","parameters":[{"name":"type","in":"query","required":false,"schema":{"default":"tickets","type":"string","enum":["tickets"]}},{"name":"limit","in":"query","required":false,"schema":{"default":10,"type":"number"}},{"name":"offset","in":"query","required":false,"schema":{"default":0,"type":"number"}},{"name":"date","in":"query","required":false,"schema":{"type":"string"}},{"name":"filters","in":"query","required":false,"schema":{"type":"string"}},{"name":"assigned_user_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"ticket_view_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"tag_ids","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","format":"uuid"}}},{"name":"channel","in":"query","required":false,"schema":{"type":"string","enum":["email","live_chat","instagram_dm","phone","chatbot","messenger","trustpilot","event"]}},{"name":"date_from","in":"query","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"date_to","in":"query","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"sort_field","in":"query","required":false,"schema":{"default":"created_at","type":"string","enum":["created_at","endpoint","method","status_code","response_time_ms"]}},{"name":"sort_direction","in":"query","required":false,"schema":{"default":"desc","type":"string","enum":["asc","desc"]}},{"name":"Wilmo-Organization","in":"header","required":false,"description":"The organization to act in, for a principal that spans several (a person in several organizations).","schema":{"type":"string","format":"uuid"}},{"name":"Wilmo-Version","in":"header","required":false,"description":"The API version to shape the request and response for. Default: the version your API key or grant is pinned to.","schema":{"type":"string","example":"2026-11-06"}}],"responses":{"200":{"description":"The numbers for the window","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","anyOf":[{"type":"object","properties":{"avg_time_to_first_response_seconds":{"type":"number"},"avg_time_to_resolution_seconds":{"type":"number"},"open_tickets_count":{"type":"number"},"pending_tickets_count":{"type":"number"},"resolved_tickets_count":{"type":"number"},"open_tickets_percentage":{"type":"number"},"pending_tickets_percentage":{"type":"number"},"resolved_tickets_percentage":{"type":"number"},"resolution_type_human_count":{"type":"number"},"resolution_type_copilot_count":{"type":"number"},"resolution_type_autopilot_count":{"type":"number"},"resolution_type_human_percentage":{"type":"number"},"resolution_type_copilot_percentage":{"type":"number"},"resolution_type_autopilot_percentage":{"type":"number"},"resolution_type_by_day":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"human_count":{"type":"number"},"copilot_count":{"type":"number"},"autopilot_count":{"type":"number"},"total_resolved":{"type":"number"},"human_percentage":{"type":"number"},"copilot_percentage":{"type":"number"},"autopilot_percentage":{"type":"number"}},"required":["date","human_count","copilot_count","autopilot_count","total_resolved","human_percentage","copilot_percentage","autopilot_percentage"],"additionalProperties":false}},"total_tickets_in_period":{"type":"number"},"tag_distribution":{"type":"array","items":{"type":"object","properties":{"tag_id":{"type":"string","format":"uuid"},"tag_key":{"type":"string"},"tag_name":{"type":"string"},"tag_color":{"type":"string"},"count":{"type":"number"},"percentage":{"type":"number"},"cumulative_ticket_count":{"type":"number"},"cumulative_ticket_percentage":{"type":"number"},"resolved_count":{"type":"number"},"copilot_count":{"type":"number"},"autopilot_count":{"type":"number"},"human_count":{"type":"number"},"copilot_percentage":{"type":"number"},"autopilot_percentage":{"type":"number"},"human_percentage":{"type":"number"},"is_autopilot_enabled":{"type":"boolean"},"autopilot_channels":{"type":"array","items":{"type":"string","enum":["email","live_chat","instagram_dm","phone","chatbot","messenger","trustpilot","event"]}}},"required":["tag_id","tag_key","tag_name","tag_color","count","percentage","cumulative_ticket_count","cumulative_ticket_percentage","resolved_count","copilot_count","autopilot_count","human_count","copilot_percentage","autopilot_percentage","human_percentage","is_autopilot_enabled","autopilot_channels"],"additionalProperties":false}},"autopilot_tag_coverage_count":{"type":"number"},"autopilot_tag_coverage_percentage":{"type":"number"},"autopilot_tag_coverage_by_day":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"ticket_count":{"type":"number"},"total_tickets":{"type":"number"},"percentage":{"type":"number"}},"required":["date","ticket_count","total_tickets","percentage"],"additionalProperties":false}},"training_data_count":{"type":"number"},"training_data_percentage":{"type":"number"},"training_data_by_day":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"training_count":{"type":"number"},"total_resolved":{"type":"number"},"percentage":{"type":"number"}},"required":["date","training_count","total_resolved","percentage"],"additionalProperties":false}},"analytics_version":{"type":"string","const":"v1"}},"required":["avg_time_to_first_response_seconds","avg_time_to_resolution_seconds","open_tickets_count","pending_tickets_count","resolved_tickets_count","open_tickets_percentage","pending_tickets_percentage","resolved_tickets_percentage","resolution_type_human_count","resolution_type_copilot_count","resolution_type_autopilot_count","resolution_type_human_percentage","resolution_type_copilot_percentage","resolution_type_autopilot_percentage","resolution_type_by_day","total_tickets_in_period","tag_distribution","autopilot_tag_coverage_count","autopilot_tag_coverage_percentage","autopilot_tag_coverage_by_day","training_data_count","training_data_percentage","training_data_by_day","analytics_version"],"additionalProperties":false},{"type":"object","properties":{"analytics_version":{"type":"string","const":"v2"},"grain":{"type":"string","enum":["day","week","month"]},"measured_at":{"type":"string","format":"date-time"},"window_start":{"type":"string","format":"date-time"},"window_end":{"type":"string","format":"date-time"},"totals":{"type":"object","properties":{"inbound_message_count":{"type":"integer","minimum":0},"answered_message_count":{"type":"integer","minimum":0},"historic_autopilot_message_count":{"type":"integer","minimum":0},"forecasted_autopilot_message_count":{"type":"integer","minimum":0},"historic_autopilot_percentage":{"type":"number","minimum":0},"forecasted_autopilot_percentage":{"type":"number","minimum":0}},"required":["inbound_message_count","answered_message_count","historic_autopilot_message_count","forecasted_autopilot_message_count","historic_autopilot_percentage","forecasted_autopilot_percentage"],"additionalProperties":false},"series":{"type":"array","items":{"type":"object","properties":{"inbound_message_count":{"type":"integer","minimum":0},"answered_message_count":{"type":"integer","minimum":0},"historic_autopilot_message_count":{"type":"integer","minimum":0},"forecasted_autopilot_message_count":{"type":"integer","minimum":0},"historic_autopilot_percentage":{"type":"number","minimum":0},"forecasted_autopilot_percentage":{"type":"number","minimum":0},"bucket_start":{"type":"string","format":"date"},"is_incomplete":{"type":"boolean"},"is_partial":{"type":"boolean"},"setting_changes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"team_id":{"type":"string"},"tag_id":{"type":["string","null"]},"tag_key":{"type":"string"},"tag_name":{"type":"string"},"channel_type":{"type":"string","enum":["email","live_chat","instagram_dm","phone","chatbot","messenger","trustpilot","event"]},"setting":{"type":"string","enum":["enable_autopilot","blocks_autopilot"]},"previous_value":{"type":"boolean"},"new_value":{"type":"boolean"}},"required":["id","created_at","team_id","tag_id","tag_key","tag_name","channel_type","setting","previous_value","new_value"],"additionalProperties":false}}},"required":["inbound_message_count","answered_message_count","historic_autopilot_message_count","forecasted_autopilot_message_count","historic_autopilot_percentage","forecasted_autopilot_percentage","bucket_start","is_incomplete","is_partial","setting_changes"],"additionalProperties":false}},"setting_changes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"team_id":{"type":"string"},"tag_id":{"type":["string","null"]},"tag_key":{"type":"string"},"tag_name":{"type":"string"},"channel_type":{"type":"string","enum":["email","live_chat","instagram_dm","phone","chatbot","messenger","trustpilot","event"]},"setting":{"type":"string","enum":["enable_autopilot","blocks_autopilot"]},"previous_value":{"type":"boolean"},"new_value":{"type":"boolean"}},"required":["id","created_at","team_id","tag_id","tag_key","tag_name","channel_type","setting","previous_value","new_value"],"additionalProperties":false}}},"required":["analytics_version","grain","measured_at","window_start","window_end","totals","series","setting_changes"],"additionalProperties":false}]}}}},"400":{"description":"- `invalid_input`: the input does not match the schema.\n- `team_required`: Called without a caller: the numbers are read for its teams.","content":{"application/json":{"schema":{"type":"object","description":"Every v2 error: one short sentence an agent can act on, a stable code, and where to read more.","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found_error","conflict_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":["string","null"]},"request_id":{"type":["string","null"]},"doc_url":{"type":"string"}},"required":["type","code","message","doc_url"]}},"required":["error"]}}}},"401":{"description":"- `authentication_required`: no valid API key or access token.","content":{"application/json":{"schema":{"type":"object","description":"Every v2 error: one short sentence an agent can act on, a stable code, and where to read more.","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found_error","conflict_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":["string","null"]},"request_id":{"type":["string","null"]},"doc_url":{"type":"string"}},"required":["type","code","message","doc_url"]}},"required":["error"]}}}},"429":{"description":"- `rate_limited`: too many requests; wait for Retry-After seconds.","content":{"application/json":{"schema":{"type":"object","description":"Every v2 error: one short sentence an agent can act on, a stable code, and where to read more.","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found_error","conflict_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":["string","null"]},"request_id":{"type":["string","null"]},"doc_url":{"type":"string"}},"required":["type","code","message","doc_url"]}},"required":["error"]}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}}}}}},"/api/v2/tickets/{ticket_id}":{"get":{"operationId":"get_ticket","summary":"Read one ticket and its conversation","description":"One support ticket (team, subject, status, channel, customer, tags, how it was answered, AI summary) and its sent messages as plain text, oldest first. Each message says who wrote it: customer, ai (Wilmo's AI agent on its own, Autopilot), agent (a person, including an AI draft a person sent: Copilot), note (internal, never sent) or system. Returns the newest messages (25 by default, at most 50), each cut to 4,000 characters (truncated says so); pass older_messages_cursor back for earlier ones.","tags":["tickets"],"security":[{"apiKey":["read:tickets"]},{"oauth":["read:tickets"]}],"x-wilmo-scope":"read:tickets","x-wilmo-mcp-tool":"get_ticket","x-wilmo-since":"2026-11-06","parameters":[{"name":"ticket_id","in":"path","required":true,"description":"The ticket id (from list_tickets).","schema":{"type":"string","description":"The ticket id (from list_tickets)."}},{"name":"message_limit","in":"query","required":false,"description":"The newest messages to return, at most 50.","schema":{"default":25,"description":"The newest messages to return, at most 50.","type":"integer","minimum":1,"maximum":50}},{"name":"cursor","in":"query","required":false,"description":"older_messages_cursor of the previous call, for older messages.","schema":{"description":"older_messages_cursor of the previous call, for older messages.","type":"string","minLength":1,"maxLength":200}},{"name":"Wilmo-Organization","in":"header","required":false,"description":"The organization to act in, for a principal that spans several (a person in several organizations).","schema":{"type":"string","format":"uuid"}},{"name":"Wilmo-Version","in":"header","required":false,"description":"The API version to shape the request and response for. Default: the version your API key or grant is pinned to.","schema":{"type":"string","example":"2026-11-06"}}],"responses":{"200":{"description":"The ticket and a page of its messages","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ticket":{"type":"object","properties":{"id":{"type":"string"},"ticket_number":{"type":"number"},"team_id":{"type":"string"},"team_name":{"type":["string","null"]},"subject":{"type":"string"},"status":{"type":"string","enum":["pending","open","resolved","spam"]},"channel":{"type":"string","enum":["email","live_chat","instagram_dm","phone","chatbot","messenger","trustpilot","event"]},"customer_name":{"type":["string","null"]},"customer_email":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}},"answered_by":{"anyOf":[{"type":"string","enum":["human","copilot","autopilot"]},{"type":"null"}]},"summary":{"type":["string","null"]},"received_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","ticket_number","team_id","team_name","subject","status","channel","customer_name","customer_email","tags","answered_by","summary","received_at","updated_at"],"additionalProperties":false},"messages":{"maxItems":50,"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string","enum":["customer","ai","agent","note","system"]},"author_name":{"type":["string","null"]},"channel":{"type":"string","enum":["email","live_chat","instagram_dm","phone","chatbot","messenger","trustpilot","event"]},"sent_at":{"type":"string"},"subject":{"type":["string","null"]},"text":{"type":"string"},"truncated":{"type":"boolean"}},"required":["id","role","author_name","channel","sent_at","subject","text","truncated"],"additionalProperties":false}},"message_count":{"type":"integer","minimum":0},"older_messages_cursor":{"type":["string","null"]}},"required":["ticket","messages","message_count","older_messages_cursor"],"additionalProperties":false}}}},"400":{"description":"- `invalid_input`: the input does not match the schema.\n- `team_required`: Called without a caller: there are no teams to read.\n- `invalid`: The cursor is not one this read gave.","content":{"application/json":{"schema":{"type":"object","description":"Every v2 error: one short sentence an agent can act on, a stable code, and where to read more.","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found_error","conflict_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":["string","null"]},"request_id":{"type":["string","null"]},"doc_url":{"type":"string"}},"required":["type","code","message","doc_url"]}},"required":["error"]}}}},"401":{"description":"- `authentication_required`: no valid API key or access token.","content":{"application/json":{"schema":{"type":"object","description":"Every v2 error: one short sentence an agent can act on, a stable code, and where to read more.","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found_error","conflict_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":["string","null"]},"request_id":{"type":["string","null"]},"doc_url":{"type":"string"}},"required":["type","code","message","doc_url"]}},"required":["error"]}}}},"404":{"description":"- `not_found`: No ticket with this id in a team the caller reads.","content":{"application/json":{"schema":{"type":"object","description":"Every v2 error: one short sentence an agent can act on, a stable code, and where to read more.","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found_error","conflict_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":["string","null"]},"request_id":{"type":["string","null"]},"doc_url":{"type":"string"}},"required":["type","code","message","doc_url"]}},"required":["error"]}}}},"429":{"description":"- `rate_limited`: too many requests; wait for Retry-After seconds.","content":{"application/json":{"schema":{"type":"object","description":"Every v2 error: one short sentence an agent can act on, a stable code, and where to read more.","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found_error","conflict_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":["string","null"]},"request_id":{"type":["string","null"]},"doc_url":{"type":"string"}},"required":["type","code","message","doc_url"]}},"required":["error"]}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}}}}}}}}