{"openapi":"3.0.0","info":{"title":"Purple Suite Community API","version":"1.0.0","description":"\n\n---\n\n**Acting as a user (`X-PS-Impersonate-User`).** Every endpoint accepts an optional `X-PS-Impersonate-User` request header whose value is the email of the instance user to act as. The effective user resolves in this order: the header if present, else the instance's configured default MCP user, else none. User-scoped paths additionally accept the literal `me` in place of an email, and Graph-style apps also serve `/me/…` twins of their `/users/{email}/…` paths that resolve the same way. This header is honored by all operations but is intentionally omitted from each operation's parameter list so it is not surfaced as a per-tool argument by MCP clients; see the `ImpersonateUser` entry under `components.parameters`."},"servers":[{"url":"https://marketplace.moveworks.com/api/purple-suite/community"}],"security":[{"patAuth":[]}],"components":{"securitySchemes":{"patAuth":{"type":"http","scheme":"bearer"}},"parameters":{"InstanceId":{"in":"header","name":"X-Instance-ID","required":true,"schema":{"type":"string"}},"ImpersonateUser":{"in":"header","name":"X-PS-Impersonate-User","required":false,"schema":{"type":"string","format":"email"},"description":"Optional. Act as a specific user in the target instance — the value is that user's email (must exist in the instance). Resolution order for the effective user: (1) this header, if set; (2) the instance's configured default MCP user; (3) otherwise no user is bound. User-scoped paths (e.g. /users/{email}/…) also accept the literal \"me\", and Graph-style apps serve /me/… twins of those paths (Graph: /me ≡ /users/{signed-in-user}) — both resolve to whatever this header (or the default MCP user) points at. An explicit path email always wins over the header. The unified MCP server does not send this header — it relies on the per-instance default — so it is primarily for direct REST/HTTP callers."}},"schemas":{"FeatureRequest":{"type":"object","properties":{"id":{"type":"string","readOnly":true},"name":{"type":"string","example":"Add Dark Mode"},"currentStatus":{"type":"string","enum":["New","Under Review","Planned","In Progress","Delivered","Declined"],"example":"New"},"createdBy":{"type":"string","example":"user1@acme.com"},"moderator":{"type":"string","example":"admin@acme.com"},"productArea":{"type":"string","enum":["UI/UX","Performance","Security","Integrations","API","Analytics","Admin","Notifications"],"example":"UI/UX"},"votes":{"type":"integer","example":42},"createdAt":{"type":"string","format":"date-time","readOnly":true},"updatedAt":{"type":"string","format":"date-time","readOnly":true}}},"LegacyFeatureRequest":{"type":"object","properties":{"id":{"type":"string","example":"abc123","description":"Unique identifier of the feature request within the session"},"current_status":{"type":"string","enum":["New","Existing Functionality/Native Skill","Future Consideration","Not Enough Info to Make Decision","On Roadmap","Delivered","Duplicate","Limited Preview"],"example":"New","description":"Human-readable status mapped from newStatusNumber"}},"additionalProperties":true},"UpdateFeatureRequestStatusBody":{"type":"object","required":["newStatusNumber"],"properties":{"newStatusNumber":{"type":"integer","enum":[1,2,3,6,7,8,9,11],"example":7,"description":"Status code to set. Mapping: 1=New, 2=Existing Functionality/Native Skill, 3=Future Consideration, 6=Not Enough Info to Make Decision, 7=On Roadmap, 8=Delivered, 9=Duplicate, 11=Limited Preview"}}}}},"paths":{"/feature-requests":{"get":{"summary":"List feature requests for a session","description":"Returns the feature_requests array stored on the given session document. Public endpoint — no PAT required.","security":[],"parameters":[{"in":"query","name":"sessionId","required":true,"schema":{"type":"string"},"example":"sess_abc123","description":"The session document ID whose feature_requests array should be returned"}],"responses":{"200":{"description":"Array of feature request objects stored on the session","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/LegacyFeatureRequest"}}}}},"400":{"description":"sessionId query parameter is missing"},"404":{"description":"Session not found"}}}},"/feature-requests/{id}":{"patch":{"summary":"Update the status of a session feature request","description":"Maps newStatusNumber to a human-readable status string and writes it to current_status on the matching feature request in the session's feature_requests array.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"example":"fr-0001","description":"The id of the feature request inside the session's feature_requests array"},{"in":"query","name":"sessionId","required":true,"schema":{"type":"string"},"example":"sess_abc123","description":"The session document ID that owns the feature request"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateFeatureRequestStatusBody"}}}},"responses":{"200":{"description":"Feature request updated","content":{"text/plain":{"schema":{"type":"string","example":"Feature request updated"}}}},"400":{"description":"Missing required parameters or invalid newStatusNumber"},"404":{"description":"Session or feature request not found"}}}},"/feature_requests":{"get":{"summary":"List community feature requests (the customer product-ideas board)","parameters":[{"$ref":"#/components/parameters/InstanceId"},{"in":"query","name":"limit","schema":{"type":"integer","default":50},"description":"Legacy page size (default 50). Prefer $top. Ignored when $top/$skip are used."},{"in":"query","name":"cursor","schema":{"type":"string"},"description":"Legacy keyset cursor — pass the previous response's nextCursor. Prefer $skip/$top."},{"in":"query","name":"$filter","schema":{"type":"string"},"description":"OData filter expression. Comparison operators: eq, ne, gt, ge, lt, le. Logical: and, or, not, with parentheses for grouping. String functions: contains(field,'x'), startswith(field,'x'), endswith(field,'x'). Membership: field in ('a','b'). Case-insensitive matching via tolower(field) / toupper(field). Nested fields use a slash, e.g. pto_balance/vacation_days. String literals use single quotes; dates are ISO-8601. Examples: \"status eq 'active'\"; \"salary gt 50000 and department eq 'Engineering'\"; \"contains(tolower(name),'acme')\"; \"closeDate gt 2026-01-01\"."},{"in":"query","name":"$select","schema":{"type":"string"},"description":"Comma-separated list of fields to return, e.g. \"id,firstName,email\". Nested fields via slash (\"pto_balance/vacation_days\"). The id field is always included."},{"in":"query","name":"$orderby","schema":{"type":"string"},"description":"Sort clause(s), comma-separated, each \"field [asc|desc]\" (asc is the default). Example: \"createdAt desc, lastName asc\". Null values sort last."},{"in":"query","name":"$search","schema":{"type":"string"},"description":"Free-text, case-insensitive substring match across the resource's searchable fields."},{"in":"query","name":"$top","schema":{"type":"integer"},"description":"Maximum number of items to return (page size)."},{"in":"query","name":"$skip","schema":{"type":"integer"},"description":"Number of matching items to skip before returning results (offset paging). Combine with $top."},{"in":"query","name":"$count","schema":{"type":"boolean"},"description":"When true, include @odata.count (total matches after $filter/$search, before paging) in the response."}],"responses":{"200":{"description":"Paginated list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FeatureRequest"}},"nextCursor":{"type":"string","nullable":true,"description":"Cursor for the next page, or null on the last page. With $top/$skip this is the next $skip value; otherwise a keyset cursor."},"total":{"type":"integer","description":"Total documents in the collection."},"@odata.count":{"type":"integer","description":"Present only when $count=true: total matches after $filter/$search."},"@odata.truncated":{"type":"boolean","description":"Present and true only when the collection exceeded the in-memory query cap and results may be incomplete."}}}}}},"400":{"description":"Invalid OData query (e.g. malformed $filter)"}},"description":"Customer-submitted product ideas for this instance, with name, productArea (UI/UX, Performance, Security, Integrations, API, Analytics, Admin, Notifications), currentStatus New → Under Review → Planned → In Progress → Delivered/Declined, vote count, submitter and moderator. This is the public wish-list board — committed delivery plans live in the roadmap app and support tickets in itsm. Supports server-side OData querying — _filter, _orderby, _select, _search, _top, _skip, _count (the spec names these $filter etc.; MCP clients see the _ form because $ is not a legal tool-input key)."},"post":{"summary":"Submit a community feature request (new product idea)","parameters":[{"$ref":"#/components/parameters/InstanceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeatureRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeatureRequest"}}}}},"description":"Adds an idea to the community board with a name, product area, submitter and starting status. Use it for wish-list requests only — bugs and support issues belong in the itsm app."}},"/feature_requests/{id}":{"get":{"summary":"Get feature request","parameters":[{"$ref":"#/components/parameters/InstanceId"},{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeatureRequest"}}}},"404":{"description":"Not found"}}},"patch":{"summary":"Update a community feature request (triage status, votes, moderator)","description":"Partial update of one idea on the board — most often moving currentStatus through triage (New → Under Review → Planned → In Progress → Delivered/Declined), incrementing votes, or assigning a moderator. Send only the fields you want to change.","parameters":[{"$ref":"#/components/parameters/InstanceId"},{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Fields to update (partial)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeatureRequest"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeatureRequest"}}}},"404":{"description":"Not found"}}},"delete":{"summary":"Delete feature request","parameters":[{"$ref":"#/components/parameters/InstanceId"},{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"404":{"description":"Not found"}}}}}}