one-desk

name

one-desk

description

OneDesk is a unified work management platform that provides helpdesk, project management, live chat, and workflow automation capabilities, allowing teams to manage customer support requests, internal tasks, and service delivery from a single system with API and integration support. Read and write OneDesk data through One: attachments, customers, items, projects, timers, timesheets and more, 93 actions with real parameter documentation. Use whenever the user asks to look something up in OneDesk, create or update a record there, or build code against the OneDesk API.

OneDesk through One

OneDesk is a unified work management platform that provides helpdesk, project management, live chat, and workflow automation capabilities, allowing teams to manage customer support requests, internal tasks, and service delivery from a single system with API and integration support.

One exposes OneDesk through four MCP tools. The table below carries real action ids from One's knowledge base, so for a common operation you can skip search and go straight to reading the action's parameters.

How to run an action

1. Find the action in the table below, or call search_one_platform_actions with platform one-desk if it is not listed.
2. Call get_one_action_knowledge with the action id. Do this every time, including for actions in this table. The table gives you the id, not the parameters.
3. Call execute_one_action with parameters copied from that knowledge.

Never guess a parameter name, a body field, or an enum value. The knowledge has the real schema, and a guessed field is either a 400 or a silent write of the wrong thing.

Before you start

Call list_one_integrations once and confirm OneDesk is connected. If it is missing, the user has not connected it: say so and point them at https://app.withone.ai rather than reaching for raw HTTP.

Each connection carries an access field. If it reports {"policy": "methods", "methods": ["GET"]} the agent is read-only here, so plan a read-only answer instead of attempting a write that will be refused.

Before a write

Creates, updates, deletes and sends land on a real OneDesk account and cannot be recalled. State the action and the specific target in one line before the first write in a task, and let the user stop you. Reads need no confirmation.

Actions

Attachments

Action	Method	Path	Action id
Get Attachment by External ID	GET	/rest/public/attachments/externalId/{{externalId}}	conn_mod_def::GK8PshF2U_A::ExnXw5X2Tp-wC3ZGZiRJxw
Add Attachment to a Portfolio	POST	/rest/public/attachments/portfolio/{{externalId}}	conn_mod_def::GK8PsXnfE7A::TCDU_J-jTWijX-ei90_dvg
Add Attachment to a Project	POST	/rest/public/attachments/project/{{externalId}}	conn_mod_def::GK8PsXMZU9g::FXCDxH5RS1qSNOk81hnM6Q
Add Attachment to an Item	POST	/rest/public/attachments/item/{{externalId}}	conn_mod_def::GK8PsX4KL2A::cYMziuyXQd23_3oZFtPVLA
Create Attachment	POST	/rest/public/attachments/	conn_mod_def::GK8PsiTp1dg::hjubco9xQ9-boH_76EBzQA
Filter Attachment Details	POST	/rest/public/attachments/filter/details	conn_mod_def::GK8PsgRlQBg::hdLiORo4RbSDfJ3Wz2AKlA
Filter Attachment External IDs	POST	/rest/public/attachments/filter	conn_mod_def::GK8PshFlwcA::-F8IRtSJRSyEFj1MxEIitQ

Customers

Action	Method	Path	Action id
Get Customer by External ID	GET	/rest/public/customers/externalId/{{externalId}}	conn_mod_def::GK8PtLKNl4g::L97aD8UHT_icRjPzLxb2lQ
Get Customer by ID	GET	/rest/public/customers/id/{{id}}	conn_mod_def::GK8PtKKy4Eg::bALY8UhaQM-G-bR4Ve_Q7A
Create Customer	POST	/rest/public/customers/	conn_mod_def::GK8Ps-gEHrA::cxf-jWgAQ2-SFilp3NwyFw
Filter Customers and Get Customer External IDs	POST	/rest/public/customers/filter	conn_mod_def::GK8PtLKFlMA::18UOilBMS06Rp0yilmQ7ig
Filter Customers With Details	POST	/rest/public/customers/filter/details	conn_mod_def::GK8PtKJBr7g::WxlapOhoQauV9Cg5vUjsEQ
Update Customer by External ID	POST	/rest/public/customers/externalId/{{externalId}}	conn_mod_def::GK8PtKKQmtg::3x6Y1cOnQFe455IH5Yps-A
Update Customer by ID	POST	/rest/public/customers/id/{{id}}	conn_mod_def::GK8PtTiQ-vA::77gkQCimTd6dQFdNW706Vg

Items

Action	Method	Path	Action id
Get Item Details by External ID	GET	/rest/public/items/externalId/{{externalId}}	conn_mod_def::GK8Ptm1I_kA::XB-OsR4rRjWzfDbNv90h_g
Get Item Details by ID	GET	/rest/public/items/id/{{id}}	conn_mod_def::GK8PtmddH8A::sqfM6OiHQ5i6IiXC7RN4Kg
Create Work Item	POST	/rest/public/items/	conn_mod_def::GK8PtcpK-uA::KlhddBjiSniFkrnE8exXWw
Filter Items and Get External IDs	POST	/rest/public/items/filter	conn_mod_def::GK8PtcUFWvg::rP7wZxvCSfqlWQ1NbVWdnQ
Filter Items With Details	POST	/rest/public/items/filter/details	conn_mod_def::GK8PtdLs2XA::_XImy9upQeCR2nCVxnxoTg
Update an Item by External ID	POST	/rest/public/items/externalId/{{externalId}}	conn_mod_def::GK8PtmcdxQA::Qc2G599cT0abrp-ylGJEFw
Update Item by ID	POST	/rest/public/items/id/{{id}}	conn_mod_def::GK8PtmthXjg::6fGzplehRYWkK7-IptoLqg

Projects

Action	Method	Path	Action id
Get a Project (by ID)	GET	/rest/public/projects/id/{{id}}	conn_mod_def::GK8PucFzNrg::ckeDUVhpS6-2nOadU-LWSw
Get Project by External ID	GET	/rest/public/projects/externalId/{{externalId}}	conn_mod_def::GK8PuZtT4Bg::9-lK3aOBQSOCZ9UQz_HuRg
Create a Project	POST	/rest/public/projects/	conn_mod_def::GK8PuOO8Pdg::LfnX51mpRzGBjZbOIyb2Gw
Filter Project External IDs	POST	/rest/public/projects/filter	conn_mod_def::GK8Puabjo1A::r_NQCoMsRcG_K_6K8YKj5g
Filter Projects and Get Project Details	POST	/rest/public/projects/filter/details	conn_mod_def::GK8PuilbKKg::a9TVh5Q6RUWKFyRHHmVz3A
Update Project (by ID)	POST	/rest/public/projects/id/{{id}}	conn_mod_def::GK8PuryWv4g::Hrz-eKYCR32PEAJ4EiTVvQ
Update Project by External ID	POST	/rest/public/projects/externalId/{{externalId}}	conn_mod_def::GK8PuZt2zYA::vBh8X_ZDQjiKSrKj3PrOSg

Timers

Action	Method	Path	Action id
Cancel Work Timer	GET	/rest/public/timers/cancel/{{timerExternalId}}	conn_mod_def::GK8Pu-E9jmA::3pzX-hbASsuHpWvjnZo11Q
Get Timer by External ID	GET	/rest/public/timers/externalId/{{externalId}}	conn_mod_def::GK8PvKgNGDA::K3Hfe3dlQui4u231cjnv4Q
Pause Work Timer	GET	/rest/public/timers/pause/{{timerExternalId}}	conn_mod_def::GK8PvJogRnA::E-9F4XBsSUSmIIaxYcW-ZA
Resume Work Timer	GET	/rest/public/timers/resume/{{timerExternalId}}	conn_mod_def::GK8PvKEBYjA::h2--cHcsTnmqFA6NaZfdbA
Start Work Timer by External ID	GET	/rest/public/timers/start/{{timerExternalId}}/{{itemExternalId}}	conn_mod_def::GK8PvLAIVoA::PvcgvN2LQs21qWcImTne9Q
Filter Timer External IDs	POST	/rest/public/timers/filter	conn_mod_def::GK8PvAUdswA::XqaVn_lZQjq3TKK6bGdYAQ
Filter Timers With Details	POST	/rest/public/timers/filter/details	conn_mod_def::GK8PvBvfG7A::yYXwOhA5Tna9Cpx2rUzktA

Timesheets

Action	Method	Path	Action id
Get a Timesheet by External ID	GET	/rest/public/timesheets/externalId/{{externalId}}	conn_mod_def::GK8PvT9sjzA::IAS14r6TRN-wChTVUz30Ig
Get a Timesheet by ID	GET	/rest/public/timesheets/id/{{id}}	conn_mod_def::GK8PvTsvalA::Lsm70PUITM2oeLicSgw1rw
Create Timesheet	POST	/rest/public/timesheets/	conn_mod_def::GK8PvKw8jSg::IXFk8Yo1SRKJ8Dyvn_QmSw
Filter Timesheets and Get External IDs	POST	/rest/public/timesheets/filter	conn_mod_def::GK8Pvj5qWHg::K7pKUeA_TaiBlAhwVqNBag
Filter Timesheets and Get Timesheet Details	POST	/rest/public/timesheets/filter/details	conn_mod_def::GK8PvT08Dug::H0pnFc0GQKquvvMKDOVEKw
Update a Timesheet (by ID)	POST	/rest/public/timesheets/id/{{id}}	conn_mod_def::GK8PvsO5Fcg::cwMY-vX7QHSEPc18eJYgfA
Update Timesheet by External ID	POST	/rest/public/timesheets/externalId/{{externalId}}	conn_mod_def::GK8PvUH95Ig::r5n8M2p1RCmNisC1aNSOCA

Users

Action	Method	Path	Action id
Get a User by ID	GET	/rest/public/users/id/{{id}}	conn_mod_def::GK8Pv4ORY8g::oc0ej_iqRDqMq1B3rcax4g
Get User by External ID	GET	/rest/public/users/externalId/{{externalId}}	conn_mod_def::GK8Pvs2fgkg::rvZttHYzTSCzGRBH_gaSxw
Create User	POST	/rest/public/users/	conn_mod_def::GK8PvvyqKEA::6JTLu4ORR562B5cnaIjDvg
Filter User Details	POST	/rest/public/users/filter/details	conn_mod_def::GK8PvsnRhnA::8Hs2DjgfS82BTl0z3jj7Og
Filter Users and Get User External IDs	POST	/rest/public/users/filter	conn_mod_def::GK8PvtEMtMg::gZyZZy7XRqiNxiKy4UFa9A
Update a User by External ID	POST	/rest/public/users/externalId/{{externalId}}	conn_mod_def::GK8Pv551cDA::8rdl8yoORAug1dkaLoLQiQ
Update a User by ID	POST	/rest/public/users/id/{{id}}	conn_mod_def::GK8Pv3n26LA::ewohG-EzRumUs4PofyZGbw

Invoices

Action	Method	Path	Action id
Get Invoice by External ID	GET	/rest/public/invoices/externalId/{{externalId}}	conn_mod_def::GK8PtUAIdsg::GLVtONFfQuCCUzdglxNjfQ
Get Invoice by ID	GET	/rest/public/invoices/id/{{id}}	conn_mod_def::GK8PtT-lMLg::oNDOOwB8TRGSAGkqzzSnwA
Filter Invoice Details	POST	/rest/public/invoices/filter/details	conn_mod_def::GK8PtTi3ZuA::MBRnrkRaTOqShprOEiDAOg
Filter Invoice External IDs	POST	/rest/public/invoices/filter	conn_mod_def::GK8PtTm1y-A::hMwwBpBcTqWCB44v6Fr7yA
Update Invoice by External ID	POST	/rest/public/invoices/externalId/{{externalId}}	conn_mod_def::GK8Ptc_eDug::kQljvEvyQSOypSgBbiTumg
Update Invoice by ID	POST	/rest/public/invoices/id/{{id}}	conn_mod_def::GK8Ptc75krg::8I30oRqlTtuGGKOgYS_5NA

Quotes

Action	Method	Path	Action id
Get Quote by External ID	GET	/rest/public/quotes/externalId/{{externalId}}	conn_mod_def::GK8Pur--D2g::GZmb6wYXRMW1fQgH2HTxFA
Get Quote by ID	GET	/rest/public/quotes/id/{{id}}	conn_mod_def::GK8PurtzgPA::iN8tlt77TEa7Y8ts8Gb8dQ
Filter Quote Details	POST	/rest/public/quotes/filter/details	conn_mod_def::GK8PusQ_p7g::wEIzOeJ1TwCSV4TamQNmNQ
Filter Quotes	POST	/rest/public/quotes/filter	conn_mod_def::GK8PusEVmLg::KvSKc8c-R96gLn182wPw9w
Update Quote by External ID	POST	/rest/public/quotes/externalId/{{externalId}}	conn_mod_def::GK8Pu0_D22A::lYCOlRBGRMmXVrw3PDKf7Q
Update Quote by ID	POST	/rest/public/quotes/id/{{id}}	conn_mod_def::GK8Pu0l9gNA::PtRbBF75RsSeJIxfalSfyg

ConversationMessages

Action	Method	Path	Action id
Get a Conversation Message by External ID	GET	/rest/public/conversation-messages/externalId/{{externalId}}	conn_mod_def::GK8PsrUrKBg::P4sHGiQPSi-yKREit1w4gQ
Create Conversation Message	POST	/rest/public/conversation-messages/	conn_mod_def::GK8Psgw-d3g::-ZO3rYtOQrmLxZjPoy-qqA
Filter Conversation Messages and Get Conversation Message Details	POST	/rest/public/conversation-messages/filter/details	conn_mod_def::GK8PsrmTTMg::u20VvvVTSguw1knmhsPOiQ
Filter Conversation Messages External IDs	POST	/rest/public/conversation-messages/filter	conn_mod_def::GK8PsrfuwKA::Otkglnd3S0mKIxwNIFSW3Q
Update a Conversation Message by External ID	POST	/rest/public/conversation-messages/externalId/{{externalId}}	conn_mod_def::GK8PsrU12mA::18EiQuyRThSrWg-wabDX7A

Conversations

Action	Method	Path	Action id
Get Conversations by External ID	GET	/rest/public/conversations/externalId/{{externalId}}	conn_mod_def::GK8Ps0aBfGg::_5zti0qpSom_O2LwC9G9mg
Create Conversation	POST	/rest/public/conversations/	conn_mod_def::GK8PsqvGT3g::xC3n2MeoQnyG21IAh6W13A
Filter Conversation Details	POST	/rest/public/conversations/filter/details	conn_mod_def::GK8Ps0bA00A::ePDzlL1HTHOqZXjwG1Pj8w
Filter Conversation External IDs	POST	/rest/public/conversations/filter	conn_mod_def::GK8Ps0o2lSg::UrzNzNMWQlGXNxHGqa7uyA
Update a Conversation by External ID	POST	/rest/public/conversations/externalId/{{externalId}}	conn_mod_def::GK8Ps1iM5rg::NXI_FjiTTgOFwluEjgmgSA

Portfolios

Action	Method	Path	Action id
Get Portfolio by External ID	GET	/rest/public/portfolios/externalId/{{externalId}}	conn_mod_def::GK8PuOasMdg::xSO7Fuk-QoGgmxxkzVeksw
Create Portfolio	POST	/rest/public/portfolios/	conn_mod_def::GK8PtvyqGhA::aUrMZoVvQc6jgbjLevdbTw
Filter Portfolio Details	POST	/rest/public/portfolios/filter/details	conn_mod_def::GK8PuOlJJ8A::2w6vzwdkSm6Vt7L3j9l2kA
Filter Portfolios and Get Portfolio External IDs	POST	/rest/public/portfolios/filter	conn_mod_def::GK8PuQ2USwA::HxJ8vtipSGS3cHqz7APsjg
Update Portfolio by External ID	POST	/rest/public/portfolios/externalId/{{externalId}}	conn_mod_def::GK8PuOdKeWA::XcazgEiASUOh_9VVGib4UA

Teams

Action	Method	Path	Action id
Get Team Details by External ID	GET	/rest/public/teams/externalId/{{externalId}}	conn_mod_def::GK8Pu-HBIfg::zdnFZ0xVRemBeYhVJ34FRg
Create User Team	POST	/rest/public/teams/	conn_mod_def::GK8Puz0x-zA::E-BI2FjiTFi7X2fcfpTncA
Filter Teams and Get Team Details	POST	/rest/public/teams/filter/details	conn_mod_def::GK8Pu17GENg::mcLgsj1PRBOX4nmS4kKxPQ
Filter Teams and Get Team External IDs	POST	/rest/public/teams/filter	conn_mod_def::GK8Pu0q-mAg::XaPiOYYQS52PcmBsJgg6gA
Update User Team by External ID	POST	/rest/public/teams/externalId/{{externalId}}	conn_mod_def::GK8Pu_MOURA::AhpddmK6S4-QLuJyEON_yA

CustomerOrganizations

Action	Method	Path	Action id
Get Customer Organization by External ID	GET	/rest/public/customer-organizations/externalId/{{externalId}}	conn_mod_def::GK8Ps-xc1ig::fmj4UTmxS_Cv9aTY8fuD8w
Create Customer Organization	POST	/rest/public/customer-organizations/	conn_mod_def::GK8PszwQ7KA::aCbLTbiuQuCVgZiopkXTKQ
Filter Customer Organization External IDs	POST	/rest/public/customer-organizations/filter	conn_mod_def::GK8PtAnalIg::7om_olP5TqOLU2sT9BDNbw
Update Customer Organization by External ID	POST	/rest/public/customer-organizations/externalId/{{externalId}}	conn_mod_def::GK8Ps-tj47A::hgzZUyQFSxy6ky-xNjrliA

Activities

Action	Method	Path	Action id
Filter Activities and Get Activity Details	POST	/rest/public/activities/filter/details	conn_mod_def::GK8PsWq80xg::aZqWriTES6ya7tRVWx8VbA

CustomerOrganizationAttachments

Action	Method	Path	Action id
Add an Attachment to a Customer Organization	POST	/rest/public/attachments/customer-organization/{{externalId}}	conn_mod_def::GK8PsXvsZCg::7yxp2yrkTD66oGf2rjXoig

CustomerOrganizationDetails

Action	Method	Path	Action id
Filter Customer Organization Details	POST	/rest/public/customer-organizations/filter/details	conn_mod_def::GK8Ps-ei78g::7OsiXUuBQtqJsxAMHILMlQ

OrganizationContainerTypes

Action	Method	Path	Action id
Get Organization Container Types	GET	/rest/public/organization/containerTypes	conn_mod_def::GK8Ptmcd6Cg::dLCXKz_QQP2ucp32nXflUw

OrganizationWorkItemTypes

Action	Method	Path	Action id
Get Organization Work Item Types	GET	/rest/public/organization/itemTypes	conn_mod_def::GK8PtvTXKCg::nRsN23nRRyqaf_mk9sGu_w

This lists 90 of 93 actions. For anything not here, call search_one_platform_actions with platform one-desk. The full catalog is at https://www.withone.ai/knowledge/one-desk.

When a call fails

The error comes from OneDesk, not from One. A 400 or 422 means your parameters do not match the schema, so re-read the knowledge and fix the field. A 401 or 403 means the connection needs re-authorizing, which no retry will fix. A 404 means the id is not on this account. A 429 means slow down. Never retry a write more than once: the first attempt may have landed.

Full catalog: https://www.withone.ai/knowledge/one-desk

Integration knowledge by One (withone.ai), licensed under One-Knowledge-1.0. Attribution must be preserved in derivative works.