{"openapi":"3.0.0","info":{"title":"Purple Suite PurpleTalent API","description":"Mock of external talent-intelligence MCP tools. Tool surface includes original 6 confirmed tools plus 15 extended Studio tools. All data is deterministic per instance — see ./evalFixture.ts. See docs/superpowers/specs/2026-07-13-purple-talent-mock-design.md for the original design specs and purple-talent-studio-tool-mocking-reference.md for the extended tools specifications.\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`.","version":"2.1.0"},"servers":[{"url":"https://marketplace.moveworks.com/api/purple-suite/purple-talent"}],"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":{"FieldTerm":{"type":"object","properties":{"term":{"type":"string"},"count":{"type":"integer"},"percentage":{"type":"number"}}},"CompanyRoleFlowHeadline":{"type":"object","properties":{"inflow_joined_in_window_count":{"type":"integer","example":8},"outflow_left_in_window_count":{"type":"integer","example":3},"net_window_flow":{"type":"integer","example":5}}},"Job":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"organization":{"type":"object","properties":{"name":{"type":"string"}}},"work_mode":{"type":"string","enum":["remote","hybrid","onsite"]},"status":{"type":"string","enum":["active","closed"]}}}}},"paths":{"/search_people":{"post":{"summary":"Parse a free-text candidate search into criteria and return a search_parameters_ref (search_people)","x-mcp":false,"x-odata":false,"parameters":[{"$ref":"#/components/parameters/InstanceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"}},"additionalProperties":true},"example":{"query":"Senior product managers in New York with B2B SaaS experience"}}}},"responses":{"200":{"description":"Parse a free-text candidate search into criteria and return a search_parameters_ref (search_people)","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"search_parameters_ref":"ref_...","mode":"generate"}}}},"400":{"description":"Bad request"}}}},"/estimate_people_pool":{"post":{"summary":"Return the candidate pool size for a search_parameters_ref (estimate_people_pool)","x-mcp":false,"x-odata":false,"parameters":[{"$ref":"#/components/parameters/InstanceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"search_parameters_ref":{"type":"string"},"data_source":{"type":"string"}},"additionalProperties":true},"example":{"search_parameters_ref":"ref_from_search_people","data_source":"public_profiles"}}}},"responses":{"200":{"description":"Return the candidate pool size for a search_parameters_ref (estimate_people_pool)","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"pool_size":1240}}}},"400":{"description":"Bad request"}}}},"/analyze_people_pool":{"post":{"summary":"Return a term-frequency breakdown (e.g. skills, titles) over a search_parameters_ref's pool (analyze_people_pool)","x-mcp":false,"x-odata":false,"parameters":[{"$ref":"#/components/parameters/InstanceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"search_parameters_ref":{"type":"string"},"fields":{"type":"array"},"field_analysis_limit":{"type":"number"},"data_source":{"type":"string"}},"additionalProperties":true},"example":{"search_parameters_ref":"ref_from_search_people","fields":["skills","titles"],"field_analysis_limit":10,"data_source":"public_profiles"}}}},"responses":{"200":{"description":"Return a term-frequency breakdown (e.g. skills, titles) over a search_parameters_ref's pool (analyze_people_pool)","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"analysis_results":{"skills":[{"term":"Machine Learning","count":320,"percentage":25.8}]},"total_candidates_count":1240}}}},"400":{"description":"Bad request"}}}},"/analyze_company_role_flow":{"post":{"summary":"Return hire/departure headline + top sources for a company + role scope, synchronously (analyze_company_role_flow)","x-mcp":false,"x-odata":false,"parameters":[{"$ref":"#/components/parameters/InstanceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"target_company":{"type":"string"},"direction":{"type":"string"},"role_scope":{"type":"string"},"title_keywords":{"type":"array"},"window":{"type":"object"},"top_n":{"type":"number"}},"additionalProperties":true},"example":{"target_company":"ExampleCo","direction":"both","role_scope":"title_keywords","title_keywords":["software engineer"],"window":{"lookback_months":18},"top_n":10}}}},"responses":{"200":{"description":"Return hire/departure headline + top sources for a company + role scope, synchronously (analyze_company_role_flow)","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"headline":{"inflow_joined_in_window_count":120,"outflow_left_in_window_count":90,"net_window_flow":30},"top_inflow_sources":[{"company_name":"SourceCo","count":18,"percentage":17.1}],"count_precision":{"mode":"exact_validated"}}}}},"400":{"description":"Bad request"}}}},"/count_global_jobs":{"post":{"summary":"Count global job postings matching company/query/location/status filters (count_global_jobs)","x-mcp":false,"x-odata":false,"parameters":[{"$ref":"#/components/parameters/InstanceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"company_queries":{"type":"array"},"query":{"type":"string"},"location_query":{"type":"string"},"status_codes":{"type":"array"}},"additionalProperties":true},"example":{"company_queries":["OpenAI"],"query":"engineer","location_query":"New York","status_codes":[0]}}}},"responses":{"200":{"description":"Count global job postings matching company/query/location/status filters (count_global_jobs)","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"filters":{"query":"engineer","network_ids":[],"company_ids":[42],"location_query":"New York","status_codes":[0]},"total_count":27}}}},"400":{"description":"Bad request"}}}},"/global_jobs_by_query":{"post":{"summary":"Paginated search over the global job-postings corpus (global_jobs_by_query)","x-mcp":false,"x-odata":false,"parameters":[{"$ref":"#/components/parameters/InstanceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"filters":{"type":"object"},"page":{"type":"number"},"hits_per_page":{"type":"number"},"strict_filter_validation":{"type":"boolean"}},"additionalProperties":true},"example":{"query":"AI engineer machine learning","filters":{"status":"active","work_mode":"remote"},"page":0,"hits_per_page":20,"strict_filter_validation":true}}}},"responses":{"200":{"description":"Paginated search over the global job-postings corpus (global_jobs_by_query)","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"tool":"global_jobs_by_query","jobs":[{"id":123,"title":"Staff Machine Learning Engineer","organization":{"name":"Example Co"},"work_mode":"remote","status":"active"}],"total_count":84,"page":0,"hits_per_page":20,"total_pages":5,"meta":{"filters":{"status":"active","work_mode":"remote"},"unknown_filter_keys":[],"strict_filter_validation":true}}}}},"400":{"description":"Bad request"}}}},"/find_tools":{"post":{"summary":"Search for available tools by name or description (find_tools)","x-mcp":false,"x-odata":false,"parameters":[{"$ref":"#/components/parameters/InstanceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"}},"additionalProperties":true},"example":{"query":"people"}}}},"responses":{"200":{"description":"Search for available tools by name or description (find_tools)","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"query":"people","tools":[{"name":"search_people","description":"Parse a free-text candidate search","category":"discovery","input_schema":{}}]}}}},"400":{"description":"Bad request"}}}},"/list_skills":{"post":{"summary":"Get the skill taxonomy and available skills (list_skills)","x-mcp":false,"x-odata":false,"parameters":[{"$ref":"#/components/parameters/InstanceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"limit":{"type":"number"}},"additionalProperties":true},"example":{"limit":100}}}},"responses":{"200":{"description":"Get the skill taxonomy and available skills (list_skills)","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"skills":[{"skill_id":"skill-product-strategy","name":"Product Strategy","description":"Strategic product planning and vision","builtIn":true}]}}}},"400":{"description":"Bad request"}}}},"/load_skill":{"post":{"summary":"Load details for a specific skill (load_skill)","x-mcp":false,"x-odata":false,"parameters":[{"$ref":"#/components/parameters/InstanceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"skill_id":{"type":"string"}},"additionalProperties":true},"example":{"skill_id":"skill-product-strategy"}}}},"responses":{"200":{"description":"Load details for a specific skill (load_skill)","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"skill_id":"skill-product-strategy","name":"Product Strategy","instructions":"Product Strategy — Strategic product planning and vision","references":[{"ref_id":"skill-roadmapping","description":"Related skill"}]}}}},"400":{"description":"Bad request"}}}},"/resolve_company":{"post":{"summary":"Resolve company information by name or domain (resolve_company)","x-mcp":false,"x-odata":false,"parameters":[{"$ref":"#/components/parameters/InstanceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"companies_info":{"type":"array"}},"additionalProperties":true},"example":{"companies_info":[{"name":"Acme Corp"}]}}}},"responses":{"200":{"description":"Resolve company information by name or domain (resolve_company)","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"resolved_count":1,"total_requested":1,"companies":[{"index":0,"resolved":true,"company_name":"Acme Corp","domain":"acme.com","industry_sub_categories":["Software"],"curr_comp_size":{"count":5200}}]}}}},"400":{"description":"Bad request"}}}},"/scout_people_pool":{"post":{"summary":"Advanced people pool search with filtering (scout_people_pool)","x-mcp":false,"x-odata":false,"parameters":[{"$ref":"#/components/parameters/InstanceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"company_meta_refs":{"type":"array"}},"additionalProperties":true},"example":{"query":"Senior product managers in New York","company_meta_refs":["acme-corp"]}}}},"responses":{"200":{"description":"Advanced people pool search with filtering (scout_people_pool)","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"search_parameters_ref":"SPREF-1691234567890","pool_size":47,"active_sections":["titles","companies"],"analysis":{"titles":[{"term":"Senior Product Manager","count":9,"percentage":19.1}],"companies":[]},"suggested_refinements":["Add skills filter","Filter by seniority"],"followup":{"type":"followup","subtype":"select","message":"How do you want to shape this pool?","options":["Show candidates","Show insights"],"actions":["Show candidates","Show insights"],"context":"discovery_next_step","search_parameters_ref":"SPREF-1691234567890","pool_size":47}}}}},"400":{"description":"Bad request"}}}},"/talent_pool_deep_research":{"post":{"summary":"Comprehensive talent pool analysis (talent_pool_deep_research)","x-mcp":false,"x-odata":false,"parameters":[{"$ref":"#/components/parameters/InstanceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"icp_id":{"type":"string"}},"additionalProperties":true},"example":{"icp_id":"icp-001"}}}},"responses":{"200":{"description":"Comprehensive talent pool analysis (talent_pool_deep_research)","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"project_id":"proj-1691234567890","source_kind":"talent_pool","insights_link":"https://app.purpletalent.local/projects/proj-1691234567890","narrative_summary":"Talent pool analysis complete with 47 profiles analyzed."}}}},"400":{"description":"Bad request"}}}},"/preview_people":{"post":{"summary":"Fetch individual candidate profiles (preview_people)","x-mcp":false,"x-odata":false,"parameters":[{"$ref":"#/components/parameters/InstanceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"search_parameters_ref":{"type":"string"},"limit":{"type":"number"}},"additionalProperties":true},"example":{"search_parameters_ref":"SPREF-...","limit":10}}}},"responses":{"200":{"description":"Fetch individual candidate profiles (preview_people)","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"total_matches":47,"candidates_table":{"id":"SPREF-...","title":"Candidate Pool","columns":[{"key":"name","title":"Name"},{"key":"title","title":"Title"},{"key":"location","title":"Location"},{"key":"skills","title":"Skills"}],"rows":[{"__candidate_id":"FP001","name":"John Doe","title":"Senior Product Manager","location":"New York, NY","skills":"Strategy, Roadmapping"}],"enable_enriched_profile_on_click":true,"allow_multiple_selections_for_actions":true},"candidates_table_markdown":"| Name | Title | Location |\n|------|-------|----------|","candidates_evaluated":10,"candidates_below_threshold":37}}}},"400":{"description":"Bad request"}}}},"/company_metrics":{"post":{"summary":"Get aggregated company statistics (company_metrics)","x-mcp":false,"x-odata":false,"parameters":[{"$ref":"#/components/parameters/InstanceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"company_id":{"type":"string"}},"additionalProperties":true},"example":{"company_id":"acme-corp"}}}},"responses":{"200":{"description":"Get aggregated company statistics (company_metrics)","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"company_metrics":{"company_id":"acme-corp","summary":{"current_employee_count":5200,"current_leadership_count":520,"distribution_by_experience":[{"category":"5+ years","employee_count":2080,"leadership_count":520}],"distribution_by_tenure":[{"category":"3+ years","employee_count":2600,"leadership_count":520}],"distribution_by_department":[{"category":"Engineering","employee_count":1820,"leadership_count":104}]},"timeline":[{"year":2026,"employee_count":5200,"employee_hired":8,"employee_left":3}]}}}}},"400":{"description":"Bad request"}}}},"/analyze_company_workforce_trend":{"post":{"summary":"Time-series workforce trend analysis (analyze_company_workforce_trend)","x-mcp":false,"x-odata":false,"parameters":[{"$ref":"#/components/parameters/InstanceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"company":{"type":"string"},"year_start":{"type":"number"},"year_end":{"type":"number"}},"additionalProperties":true},"example":{"company":"Acme Corp","year_start":2024,"year_end":2026}}}},"responses":{"200":{"description":"Time-series workforce trend analysis (analyze_company_workforce_trend)","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"company":{"company_id":"acme-corp","company_name":"Acme Corp"},"year_start":2024,"year_end":2026,"mode":"active","data_points":[{"year":2024,"total":18},{"year":2025,"total":25},{"year":2026,"total":8}],"yoy_changes":[{"from":2024,"to":2025,"delta":7,"delta_pct":38.9}],"total_growth_pct":-55.6,"chart_spec":{"chart_type":"line","title":"Workforce Trend (2024-2026)","series":[{"name":"Count","data":[18,25,8]}],"x_axis":{"name":"Year","data":[2024,2025,2026]},"y_axis":{"name":"Count","type":"value"}},"kpi_spec":{"title":"Key Metrics (active)","metrics":[{"label":"Total Growth %","value":"-55.6%"},{"label":"Latest Year Total","value":8}]}}}}},"400":{"description":"Bad request"}}}},"/web_search":{"post":{"summary":"Search the web for information (web_search)","x-mcp":false,"x-odata":false,"parameters":[{"$ref":"#/components/parameters/InstanceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"max_searches":{"type":"number"}},"additionalProperties":true},"example":{"query":"talent intelligence market trends","max_searches":2}}}},"responses":{"200":{"description":"Search the web for information (web_search)","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"query":"talent intelligence market trends","answer":"Top findings: This topic has seen increased focus, with trends pointing toward increased investment and adoption.","findings":[{"claim":"Research shows strong market growth in 2026.","source_url":"https://example.com/article-1"},{"claim":"Key players are investing in talent acquisition.","source_url":"https://example.com/article-2"}],"sources":[{"url":"https://example.com/article-1","title":"Industry Insights"},{"url":"https://example.com/article-2","title":"Market Report"}],"model":"mock-web-search-v1","usage":{"searches_performed":2,"results_returned":2},"execution_mode":"interactive"}}}},"400":{"description":"Bad request"}}}},"/create_artifact":{"post":{"summary":"Create and store an analysis artifact (create_artifact)","x-mcp":false,"x-odata":false,"parameters":[{"$ref":"#/components/parameters/InstanceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"artifact_type":{"type":"string"},"data":{"type":"object"}},"additionalProperties":true},"example":{"artifact_type":"talent_analysis","data":{"title":"PM Talent Pool Analysis","insights":[],"metadata":{}}}}}},"responses":{"200":{"description":"Create and store an analysis artifact (create_artifact)","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"artifact_id":"ART-abcd1234"}}}},"400":{"description":"Bad request"}}}},"/create_project_from_search_parameters":{"post":{"summary":"Create a project from search parameters (create_project_from_search_parameters)","x-mcp":false,"x-odata":false,"parameters":[{"$ref":"#/components/parameters/InstanceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"search_parameters_ref":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"}},"additionalProperties":true},"example":{"search_parameters_ref":"SPREF-...","name":"Senior PM Search","description":"Search for senior PMs"}}}},"responses":{"200":{"description":"Create a project from search parameters (create_project_from_search_parameters)","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"project_id":"PROJ-xyz789","project_link":"https://app.purpletalent.local/searches/inst-123?joid=PROJ-xyz789&redirect_joid=PROJ-xyz789","scorecard_ref":"SC-123"}}}},"400":{"description":"Bad request"}}}},"/studio_list_workflows":{"post":{"summary":"List available workflow definitions (studio_list_workflows)","x-mcp":false,"x-odata":false,"parameters":[{"$ref":"#/components/parameters/InstanceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"runnable_only":{"type":"boolean"}},"additionalProperties":true},"example":{"runnable_only":false}}}},"responses":{"200":{"description":"List available workflow definitions (studio_list_workflows)","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"workflows":[{"workflow_id":"wf_mqzeybg6","name":"Succession Planning Workflow","kind":"workflow","visibility":"internal","inputs":[{"key":"company","label":"Company"}],"externally_runnable":true}],"count":2,"render_templates":[]}}}},"400":{"description":"Bad request"}}}},"/studio_run_workflow":{"post":{"summary":"Execute a workflow asynchronously (studio_run_workflow)","x-mcp":false,"x-odata":false,"parameters":[{"$ref":"#/components/parameters/InstanceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"workflow_key":{"type":"string"},"inputs":{"type":"object"}},"additionalProperties":true},"example":{"workflow_key":"wf__succession_planning_workflow_fbf487","inputs":{"company":"Acme Corp"}}}}},"responses":{"200":{"description":"Execute a workflow asynchronously (studio_run_workflow)","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"run_id":"RUN-abc123","status":"complete","workflow_name":"Succession Planning Workflow"}}}},"400":{"description":"Bad request"}}}},"/studio_get_run_status":{"post":{"summary":"Poll the status of an executing workflow (studio_get_run_status)","x-mcp":false,"x-odata":false,"parameters":[{"$ref":"#/components/parameters/InstanceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"run_id":{"type":"string"}},"required":["run_id"]},"example":{"run_id":"RUN-abc123"}}}},"responses":{"200":{"description":"Poll the status of an executing workflow","content":{"application/json":{"schema":{"type":"object"},"example":{"success":true,"run_id":"RUN-abc123","status":"complete"}}}}}}},"/wf__succession_planning_workflow_fbf487":{"post":{"summary":"Execute Succession Planning Workflow","x-mcp":false,"x-odata":false,"parameters":[{"$ref":"#/components/parameters/InstanceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"inputs":{"type":"object"}}},"example":{"inputs":{"company":"Acme Corp","department":"Engineering"}}}}},"responses":{"200":{"description":"Succession Planning Workflow execution result","content":{"application/json":{"schema":{"type":"object"},"example":{"success":true,"run_id":"RUN-fbf487abc","status":"complete"}}}}}}},"/wf__role_talent_inflow_outflow_analysis_e80ffb":{"post":{"summary":"Execute Role Talent Inflow/Outflow Analysis","x-mcp":false,"x-odata":false,"parameters":[{"$ref":"#/components/parameters/InstanceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"inputs":{"type":"object"}}},"example":{"inputs":{"company":"Acme Corp","role":"engineer","timeframe":"12"}}}}},"responses":{"200":{"description":"Role Talent Inflow/Outflow Analysis execution result","content":{"application/json":{"schema":{"type":"object"},"example":{"success":true,"run_id":"RUN-e80ffbabc","status":"complete"}}}}}}}}}