{"swagger": "2.0", "basePath": "/v1", "paths": {"/alerts": {"get": {"responses": {"401": {"description": "Unauthorized - API key missing or invalid"}, "200": {"description": "Success", "schema": {"$ref": "#/definitions/AlertSettings"}}}, "summary": "Get email alert settings", "description": "Get the current email alert settings for the authenticated user.", "operationId": "get_alert_settings", "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["alerts"]}, "put": {"responses": {"401": {"description": "Unauthorized - API key missing or invalid"}, "400": {"description": "Invalid parameters"}, "200": {"description": "Success"}}, "summary": "Update email alert settings", "description": "Update email alert settings. Accepts a JSON body with any of 'enabled' (boolean), 'frequency' (daily | weekly, required when enabled is true) and 'content' (all | no_workflow | new_leads_only); omitted fields stay unchanged.", "operationId": "put_alert_settings", "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["alerts"]}}, "/api-keys": {"get": {"responses": {"400": {"description": "Invalid scope, expiry, owner type or name."}, "403": {"description": "Not allowed: missing api_keys:manage, not an admin, or scope escalation."}, "404": {"description": "No such key."}, "200": {"description": "Success", "schema": {"$ref": "#/definitions/ApiKeys"}}}, "summary": "List API keys", "description": "List your own personal keys. An account owner, admin or superadmin may pass all=true for every key in the account. Never returns a raw key or hash.", "operationId": "get_api_keys_resource", "parameters": [{"description": "true: every key in the account (admins only).", "name": "all", "type": "string", "in": "query"}], "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["api keys"]}, "post": {"responses": {"400": {"description": "Invalid scope, expiry, owner type or name."}, "403": {"description": "Not allowed: missing api_keys:manage, not an admin, or scope escalation."}, "404": {"description": "No such key."}, "201": {"description": "Created", "schema": {"$ref": "#/definitions/ApiKeyWithSecret"}}}, "summary": "Create an API key", "description": "Create a key. The response carries raw_key once; it can't be read again. A key credential needs the api_keys:manage scope and can only create keys with scopes it holds that expire no later than itself.", "operationId": "post_api_keys_resource", "parameters": [{"name": "payload", "required": true, "in": "body", "schema": {"$ref": "#/definitions/ApiKeyCreate"}}], "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["api keys"]}}, "/api-keys/{key_id}": {"parameters": [{"name": "key_id", "in": "path", "required": true, "type": "integer"}], "delete": {"responses": {"400": {"description": "Invalid scope, expiry, owner type or name."}, "403": {"description": "Not allowed: missing api_keys:manage, not an admin, or scope escalation."}, "404": {"description": "No such key."}, "200": {"description": "Success", "schema": {"$ref": "#/definitions/ApiKey"}}}, "summary": "Revoke an API key", "description": "Revoke a key. Repeating the call succeeds. A key can revoke itself; another key needs api_keys:manage.", "operationId": "delete_api_key_resource", "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["api keys"]}}, "/api-keys/{key_id}/rotate": {"parameters": [{"name": "key_id", "in": "path", "required": true, "type": "integer"}], "post": {"responses": {"400": {"description": "Invalid scope, expiry, owner type or name."}, "403": {"description": "Not allowed: missing api_keys:manage, not an admin, or scope escalation."}, "404": {"description": "No such key."}, "200": {"description": "Success", "schema": {"$ref": "#/definitions/ApiKeyWithSecret"}}}, "summary": "Rotate an API key", "description": "Replace a key with a new one that has the same owner and scopes; the old key stops working. The response carries the new raw_key once. Rotating the key you are calling with revokes it mid-request: use the new key from your next call. A key can rotate itself, but another key only with api_keys:manage and only if it holds no broader scopes.", "operationId": "post_api_key_rotate_resource", "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["api keys"]}}, "/companies": {"get": {"responses": {"401": {"description": "Unauthorized - API key missing or invalid"}, "200": {"description": "Success", "schema": {"$ref": "#/definitions/CompanyListResponse"}}}, "summary": "List companies", "description": "List companies for the authenticated tenant. Supports page/per_page pagination, filter/filter_value, search/q, sort_by/sort_dir, workflow_status, category, crm_status, crm_owner, searchterm, flag_deep_search, fit_score_bucket, and DataTables query parameters.", "operationId": "get_companies", "parameters": [{"enum": ["active", "new", "missing_domain", "missing_description", "missing_both", "spiking", "in_crm", "hidden", "all"], "in": "query", "description": "Company filter preset (alias filter_value). spiking: hiring volume well above its recent average. in_crm: has a CRM record, linked or an unlinked candidate (the crm_status=in_crm filter means linked only). hidden: companies the user hid.", "name": "filter", "type": "string"}, {"type": "string", "in": "query", "description": "Employee count facet filter", "name": "employees"}, {"type": "string", "in": "query", "description": "Revenue range facet filter", "name": "revenue"}, {"type": "string", "in": "query", "description": "Industry facet filter", "name": "category_industry"}, {"type": "string", "in": "query", "description": "Industry group facet filter", "name": "category_industry_group"}, {"type": "string", "in": "query", "description": "Filter companies with jobs matching title", "name": "job_title"}, {"type": "string", "in": "query", "description": "Industry sector filter (alias category_sector)", "name": "sector"}, {"type": "string", "in": "query", "description": "Only companies with jobs after date (YYYY-MM-DD)", "name": "found_after"}, {"type": "number", "in": "query", "description": "Minimum ICP match score (0-1)", "name": "min_icp_score"}, {"type": "string", "in": "query", "description": "Quality decision bucket filter", "name": "decision_bucket"}, {"type": "string", "in": "query", "description": "CRM owner filter", "name": "crm_owner"}, {"type": "string", "in": "query", "description": "CRM status filter: in_crm (linked records only; the in_crm filter preset also includes unlinked candidates), crm_candidate, not_in_crm, aliases __new_lead__ and __crm_candidate__, or a CRM stage name", "name": "crm_status"}, {"type": "string", "in": "query", "description": "Job title search term filter", "name": "searchterm"}, {"enum": ["1", "2", "3", "4", "5"], "in": "query", "description": "Fit score bucket (1-5)", "name": "fit_score_bucket", "type": "string"}, {"enum": ["0", "1"], "in": "query", "description": "Deep search flag filter", "name": "flag_deep_search", "type": "string"}, {"type": "string", "in": "query", "description": "Custom category filter", "name": "category"}, {"type": "string", "in": "query", "description": "Workflow status label filter", "name": "workflow_status"}, {"enum": ["asc", "desc"], "in": "query", "description": "Sort direction", "name": "sort_dir", "type": "string"}, {"type": "string", "in": "query", "description": "Column to sort by", "name": "sort_by"}, {"type": "string", "in": "query", "description": "Search query (alias search)", "name": "q"}, {"type": "integer", "in": "query", "description": "Number of results per page", "name": "per_page"}, {"type": "integer", "in": "query", "description": "Page number (1-based)", "name": "page"}], "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["companies"]}}, "/company/feedback": {"post": {"responses": {"401": {"description": "Unauthorized - API key missing or invalid"}, "404": {"description": "Company not found"}, "400": {"description": "Invalid parameters"}, "200": {"description": "Success"}}, "description": "Set like / not_a_fit / clear feedback on a company. Accepts a JSON body with company resolution (id, domain, or name), 'action' (like | not_a_fit | ignore | clear), and optional 'comment'.", "operationId": "post_company_feedback", "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["companies"]}}, "/company/improve-description": {"post": {"responses": {"401": {"description": "Unauthorized - API key missing or invalid"}, "404": {"description": "Company not found"}, "400": {"description": "Invalid parameters"}, "200": {"description": "Success"}}, "description": "Trigger an AI description refresh for a company. Accepts a JSON body with company resolution (id, domain, or name).", "operationId": "post_company_improve_description", "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["companies"]}}, "/company/push-to-crm": {"post": {"responses": {"404": {"description": "Company not found"}, "401": {"description": "Unauthorized - API key missing or invalid"}, "200": {"description": "Success"}}, "description": "Create the company in HubSpot with the calling user as owner (their Wihyu e-mail must match a HubSpot owner). Accepts a JSON body with company resolution (id, domain, or name). Returns 409 no_owner, 400 no_domain or 502 client_error when the push cannot be made.", "operationId": "post_company_push_to_crm", "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["companies"]}}, "/company/workflow-status": {"post": {"responses": {"401": {"description": "Unauthorized - API key missing or invalid"}, "404": {"description": "Company not found"}, "400": {"description": "Invalid parameters"}, "200": {"description": "Success"}}, "description": "Assign or clear a workflow status on a company. Accepts a JSON body with company resolution (id, domain, or name) and 'status' (workflow status label, or empty string to clear).", "operationId": "post_company_workflow_status", "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["companies"]}}, "/company/{id}": {"parameters": [{"name": "id", "in": "path", "required": true, "type": "integer"}], "get": {"responses": {"401": {"description": "Unauthorized - API key missing or invalid"}, "404": {"description": "Company not found", "schema": {"$ref": "#/definitions/ErrorResponse"}}, "200": {"description": "Success", "schema": {"$ref": "#/definitions/CompanyDetail"}}}, "summary": "Get company detail", "description": "Get a tenant-scoped company detail payload. icp.sample_similarity explains any score bump from a close match between the company's postings and the search term's sample job description (null when none).", "operationId": "get_company_detail", "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["companies"]}}, "/design-preferences": {"get": {"responses": {"401": {"description": "Unauthorized - API key missing or invalid"}, "200": {"description": "Success"}}, "summary": "List design preferences", "description": "List every page that has a new design: page_key, label, phase (off, preview, new-default, retired), the design the caller gets now and whether the caller saved a choice.", "operationId": "get_design_preferences", "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["design preferences"]}}, "/design-preferences/{page_key}": {"parameters": [{"name": "page_key", "in": "path", "required": true, "type": "string"}], "put": {"responses": {"409": {"description": "The page's design cannot be chosen in its current phase"}, "404": {"description": "Unknown page"}, "401": {"description": "Unauthorized - API key missing or invalid"}, "400": {"description": "Invalid design"}, "200": {"description": "Success"}}, "summary": "Set the design for one page", "description": "Save the caller's design for one page. Body: design (classic | new). Returns the updated item. 404 for an unknown page, 400 for another design value, 409 while the page's phase is off or retired.", "operationId": "put_design_preference", "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["design preferences"]}}, "/icp": {"get": {"responses": {"401": {"description": "Unauthorized - API key missing or invalid"}, "200": {"description": "Success", "schema": {"$ref": "#/definitions/IcpDefinition"}}}, "summary": "Get the current ICP definition", "description": "Get the current Ideal Customer Profile definition including natural language guidance, search terms, and user context notes.", "operationId": "get_icp_definition", "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["Ideal Customer Profile"]}, "put": {"responses": {"409": {"description": "A search term matches a turned-off term (inactive_duplicate_term); resend with reactivate_term_ids"}, "403": {"description": "Caller is not the owner or an admin, or the key lacks icp:approve"}, "401": {"description": "Unauthorized - API key missing or invalid"}, "400": {"description": "Invalid parameters"}, "200": {"description": "Success"}}, "summary": "Update the ICP definition", "description": "Update the ICP natural language guidance, search terms, and/or context notes. Accepts a JSON body with optional 'natural_language_guidance', 'search_terms' (list), 'job_postings_by_term' (map), 'reactivate_term_ids' (list of ids), 'note', and 'note_mode' (append | replace). Only the account owner, a tenant admin or a superadmin may update; the key needs the icp:approve scope.", "operationId": "put_icp_definition", "parameters": [{"name": "payload", "required": true, "in": "body", "schema": {"$ref": "#/definitions/IcpDefinitionUpdate"}}], "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["Ideal Customer Profile"]}}, "/icp/examples/activate": {"post": {"responses": {"422": {"description": "validation_error"}, "403": {"description": "Not allowed to change this account's ICP"}, "200": {"description": "Activated, or nothing was waiting"}}, "summary": "Activate pending example changes", "description": "Activate the example-company changes waiting on your live ICP: one new ICP version whose example snapshot matches your confirmed examples, then your companies are rescored over the next few hours. Returns status already_active when nothing is waiting. Only the account owner, a tenant admin or a superadmin may activate.", "operationId": "post_icp_examples_activate", "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["Ideal Customer Profile"]}}, "/icp/feedback-summary": {"get": {"responses": {"403": {"description": "Not allowed to read this account's feedback summary"}, "200": {"description": "Success", "schema": {"$ref": "#/definitions/IcpFeedbackSummary"}}}, "summary": "Get the feedback summary", "description": "What your team has rated (Good fit and Not a fit, all time and the last 30 days), the 10 newest ratings with comments, the learned rules and their progress toward the next rewrite. Only the account owner, a tenant admin or a superadmin may read it. Read-only: it never rescores or invalidates anything.", "operationId": "get_icp_feedback_summary", "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["Ideal Customer Profile"]}}, "/icp/proposals": {"post": {"responses": {"409": {"description": "already_running, daily_limit, no_website, website_research_off, unavailable, busy or tenant_not_active"}, "403": {"description": "Not allowed to change this account's ICP"}, "202": {"description": "Research started"}}, "summary": "Request website research", "description": "Start researching your website for suggested ICP changes. Returns 202 with proposal_id and poll_after_seconds. Nothing live changes until you apply. Not available for job_intelligence accounts (409 website_research_off). Loop: request_icp_proposal, poll get_icp_proposal until status is no longer 'researching' (wait poll_after_seconds between polls), read the diff, then apply_icp_proposal a chosen subset or discard_icp_proposal. Apply is asynchronous: poll get_icp_proposal(proposal_id) every poll_after_seconds until status leaves 'applying'. Limits: 3 manual research requests per account per 24 hours (superadmin exempt); research times out after 30 minutes; 9 sample-posting preview searches per account per day by default (ICP_PREVIEW_DAILY_SEARCH_CAP; this only limits how many samples are filled and never refuses a request); field caps: industries 5, not a fit 5; at most 3 added search terms are offered; at most 20 confirmed example companies. Only the account owner, a tenant admin or a superadmin may request, apply or discard; any user may read.", "operationId": "post_icp_proposals", "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["Ideal Customer Profile"]}}, "/icp/proposals/latest": {"get": {"responses": {"200": {"description": "Success", "schema": {"$ref": "#/definitions/IcpProposal"}}}, "summary": "Get the latest suggested ICP change", "description": "Read the latest suggested ICP change for your account: its status, the diff against the live ICP, sample postings and example companies. Loop: request_icp_proposal, poll get_icp_proposal until status is no longer 'researching' (wait poll_after_seconds between polls), read the diff, then apply_icp_proposal a chosen subset or discard_icp_proposal. Apply is asynchronous: poll get_icp_proposal(proposal_id) every poll_after_seconds until status leaves 'applying'. Limits: 3 manual research requests per account per 24 hours (superadmin exempt); research times out after 30 minutes; 9 sample-posting preview searches per account per day by default (ICP_PREVIEW_DAILY_SEARCH_CAP; this only limits how many samples are filled and never refuses a request); field caps: industries 5, not a fit 5; at most 3 added search terms are offered; at most 20 confirmed example companies. Only the account owner, a tenant admin or a superadmin may request, apply or discard; any user may read.", "operationId": "get_icp_proposal_latest", "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["Ideal Customer Profile"]}}, "/icp/proposals/sample-edits/apply": {"post": {"responses": {"409": {"description": "nothing_ready, already_applying or busy"}, "403": {"description": "Not allowed to change this account's ICP"}, "202": {"description": "Accepted: status applying (or applied)"}}, "summary": "Apply all ready sample changes", "description": "Apply every ready, non-stale sample change as one new ICP version in one background job. Asynchronous: returns 202 at once with the proposal_ids being applied (poll GET /v1/icp/proposals/{id}). A change that went stale or was refused returns to ready with its message; the others still apply. Needs the icp:approve scope. Loop: request_icp_proposal, poll get_icp_proposal until status is no longer 'researching' (wait poll_after_seconds between polls), read the diff, then apply_icp_proposal a chosen subset or discard_icp_proposal. Apply is asynchronous: poll get_icp_proposal(proposal_id) every poll_after_seconds until status leaves 'applying'. Limits: 3 manual research requests per account per 24 hours (superadmin exempt); research times out after 30 minutes; 9 sample-posting preview searches per account per day by default (ICP_PREVIEW_DAILY_SEARCH_CAP; this only limits how many samples are filled and never refuses a request); field caps: industries 5, not a fit 5; at most 3 added search terms are offered; at most 20 confirmed example companies. Only the account owner, a tenant admin or a superadmin may request, apply or discard; any user may read.", "operationId": "post_icp_sample_edits_apply", "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["Ideal Customer Profile"]}}, "/icp/proposals/{proposal_id}": {"parameters": [{"name": "proposal_id", "in": "path", "required": true, "type": "integer"}], "get": {"responses": {"404": {"description": "Not found"}, "200": {"description": "Success", "schema": {"$ref": "#/definitions/IcpProposal"}}}, "summary": "Get one suggested ICP change", "description": "Read one of your own suggested ICP changes by id, including an applied, discarded or superseded one. Another account's id is 404.", "operationId": "get_icp_proposal_by_id", "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["Ideal Customer Profile"]}}, "/icp/proposals/{proposal_id}/apply": {"parameters": [{"name": "proposal_id", "in": "path", "required": true, "type": "integer"}], "post": {"responses": {"422": {"description": "invalid_selection or validation_error"}, "409": {"description": "stale, not_ready, already_applying or busy"}, "404": {"description": "Not found"}, "403": {"description": "Not allowed to change this account's ICP"}, "202": {"description": "Accepted: status applying (or applied)"}}, "summary": "Apply a suggested ICP change", "description": "Apply a chosen, edited subset of a ready proposal as one new ICP version. Asynchronous: returns 202 at once with status applying (poll GET /v1/icp/proposals/{id} until it is applied, or ready with an error). Needs the icp:approve scope. Loop: request_icp_proposal, poll get_icp_proposal until status is no longer 'researching' (wait poll_after_seconds between polls), read the diff, then apply_icp_proposal a chosen subset or discard_icp_proposal. Apply is asynchronous: poll get_icp_proposal(proposal_id) every poll_after_seconds until status leaves 'applying'. Limits: 3 manual research requests per account per 24 hours (superadmin exempt); research times out after 30 minutes; 9 sample-posting preview searches per account per day by default (ICP_PREVIEW_DAILY_SEARCH_CAP; this only limits how many samples are filled and never refuses a request); field caps: industries 5, not a fit 5; at most 3 added search terms are offered; at most 20 confirmed example companies. Only the account owner, a tenant admin or a superadmin may request, apply or discard; any user may read.", "operationId": "post_icp_proposal_apply", "parameters": [{"name": "payload", "required": true, "in": "body", "schema": {"$ref": "#/definitions/IcpProposalApply"}}], "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["Ideal Customer Profile"]}}, "/icp/proposals/{proposal_id}/discard": {"parameters": [{"name": "proposal_id", "in": "path", "required": true, "type": "integer"}], "post": {"responses": {"409": {"description": "not_ready or busy"}, "404": {"description": "Not found"}, "403": {"description": "Not allowed to change this account's ICP"}, "200": {"description": "Discarded"}}, "summary": "Discard a suggested ICP change", "description": "Discard a ready, no_change or failed proposal. Your live ICP is unchanged.", "operationId": "post_icp_proposal_discard", "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["Ideal Customer Profile"]}}, "/icp/purpose": {"get": {"responses": {"200": {"description": "Success", "schema": {"$ref": "#/definitions/IcpPurpose"}}}, "summary": "Get the account purpose", "description": "Get what your account uses Wihyu for: find_buyers or job_intelligence.", "operationId": "get_icp_purpose", "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["Ideal Customer Profile"]}, "put": {"responses": {"403": {"description": "Not allowed to change this account's purpose"}, "400": {"description": "invalid_purpose or invalid_request"}, "200": {"description": "Saved", "schema": {"$ref": "#/definitions/IcpPurpose"}}}, "summary": "Set the account purpose", "description": "Set what your account uses Wihyu for. job_intelligence turns off website research and suggested changes. This never changes your ICP, search terms or scores. Other body keys are ignored. Only the account owner, a tenant admin or a superadmin may save; the key needs the icp:approve scope.", "operationId": "put_icp_purpose", "parameters": [{"name": "payload", "required": true, "in": "body", "schema": {"$ref": "#/definitions/IcpPurposeUpdate"}}], "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["Ideal Customer Profile"]}}, "/icp/search-term-health/digest": {"get": {"responses": {"400": {"description": "Invalid request"}, "401": {"description": "Unauthorized - API key missing or invalid"}, "403": {"description": "Caller is not the owner or an admin, or the key lacks icp:approve"}, "404": {"description": "Suggestion, search term or allowed title not found for this account"}, "409": {"description": "Suggestion no longer open or out of date, cap reached, or the account is busy"}, "200": {"description": "Success"}}, "summary": "Get the digest setting", "description": "The weekly search-term health digest setting as the caller sees it: `mode` is owner (with `enabled`), admin (with the owner's name, no switch) or none. Any user of the account may read.", "operationId": "get_icp_search_term_health_digest", "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["Ideal Customer Profile"]}, "put": {"responses": {"400": {"description": "Invalid request"}, "401": {"description": "Unauthorized - API key missing or invalid"}, "403": {"description": "Caller is not the owner or an admin, or the key lacks icp:approve"}, "404": {"description": "Suggestion, search term or allowed title not found for this account"}, "409": {"description": "Suggestion no longer open or out of date, cap reached, or the account is busy"}, "200": {"description": "Saved"}}, "summary": "Turn the digest on or off", "description": "Turn the Monday digest on or off. Only the account owner has the setting (another admin gets 403 forbidden). It does not change the recommendations e-mail setting; the key needs the icp:approve scope.", "operationId": "put_icp_search_term_health_digest", "parameters": [{"name": "payload", "required": true, "in": "body", "schema": {"$ref": "#/definitions/SearchTermDigestSetting"}}], "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["Ideal Customer Profile"]}}, "/icp/search-term-health/snooze": {"get": {"responses": {"400": {"description": "Invalid request"}, "401": {"description": "Unauthorized - API key missing or invalid"}, "403": {"description": "Caller is not the owner or an admin, or the key lacks icp:approve"}, "404": {"description": "Suggestion, search term or allowed title not found for this account"}, "409": {"description": "Suggestion no longer open or out of date, cap reached, or the account is busy"}, "200": {"description": "Success"}}, "summary": "Get the caller's banner snooze", "description": "Whether the Recommendations banner shows for the caller, and the end of their snooze if any. Any user of the account may read.", "operationId": "get_icp_search_term_health_snooze", "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["Ideal Customer Profile"]}, "post": {"responses": {"400": {"description": "Invalid request"}, "401": {"description": "Unauthorized - API key missing or invalid"}, "403": {"description": "Caller is not the owner or an admin, or the key lacks icp:approve"}, "404": {"description": "Suggestion, search term or allowed title not found for this account"}, "409": {"description": "Suggestion no longer open or out of date, cap reached, or the account is busy"}, "200": {"description": "Snoozed"}}, "summary": "Hide the banner for a week", "description": "Hide the search-term health banner for the caller for 7 days. Badges, the bell and the digest are unaffected. Only the account owner, a tenant admin or a superadmin may call it; the key needs the icp:approve scope.", "operationId": "post_icp_search_term_health_snooze", "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["Ideal Customer Profile"]}}, "/icp/search-term-suggestions/accept": {"post": {"responses": {"400": {"description": "Invalid request"}, "401": {"description": "Unauthorized - API key missing or invalid"}, "403": {"description": "Caller is not the owner or an admin, or the key lacks icp:approve"}, "404": {"description": "Suggestion, search term or allowed title not found for this account"}, "409": {"description": "Suggestion no longer open or out of date, cap reached, or the account is busy"}, "200": {"description": "Accepted"}}, "summary": "Accept several title suggestions", "description": "Accept several allowed_variant suggestions together, all or nothing (the 'Allow all' action). A call that would take any term past 5 allowed titles is refused whole with cap_reached. Only the account owner, a tenant admin or a superadmin may call it; the key needs the icp:approve scope.", "operationId": "post_icp_search_term_suggestions_accept", "parameters": [{"name": "payload", "required": true, "in": "body", "schema": {"$ref": "#/definitions/SearchTermSuggestionsAccept"}}], "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["Ideal Customer Profile"]}}, "/icp/search-term-suggestions/{suggestion_id}/accept": {"parameters": [{"name": "suggestion_id", "in": "path", "required": true, "type": "integer"}], "post": {"responses": {"400": {"description": "Invalid request"}, "401": {"description": "Unauthorized - API key missing or invalid"}, "403": {"description": "Caller is not the owner or an admin, or the key lacks icp:approve"}, "404": {"description": "Suggestion, search term or allowed title not found for this account"}, "409": {"description": "Suggestion no longer open or out of date, cap reached, or the account is busy"}, "200": {"description": "Accepted"}}, "summary": "Accept a suggestion", "description": "Accept one open suggestion; the kind decides what happens. allowed_variant: keep titles with that phrase under the term (max 5 per term, no extra search term, no rescore). disable_must_contain: allow similar titles; show the user this first: Allowing similar titles will likely return a broad set of job titles. The job search sites use semantic search, which returns many unrelated titles along with the ones you want. As a result, you may need to give more feedback (Good fit / Not a fit) on the companies that are found to help guide the results. require_must_contain: require the term in titles; show the user this first: Require job titles to contain this term? Wihyu will only keep jobs whose title contains the term. Jobs this term already found whose title doesn't contain it will be removed the next time Wihyu cleans up your account's jobs. Send apply_variant_ids to accept title suggestions in the same step. replacement_term: swap the term for the suggested one in one ICP version. Only the account owner, a tenant admin or a superadmin may call it; the key needs the icp:approve scope.", "operationId": "post_icp_search_term_suggestion_accept", "parameters": [{"name": "payload", "required": true, "in": "body", "schema": {"$ref": "#/definitions/SearchTermSuggestionAccept"}}], "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["Ideal Customer Profile"]}}, "/icp/search-term-suggestions/{suggestion_id}/dismiss": {"parameters": [{"name": "suggestion_id", "in": "path", "required": true, "type": "integer"}], "post": {"responses": {"400": {"description": "Invalid request"}, "401": {"description": "Unauthorized - API key missing or invalid"}, "403": {"description": "Caller is not the owner or an admin, or the key lacks icp:approve"}, "404": {"description": "Suggestion, search term or allowed title not found for this account"}, "409": {"description": "Suggestion no longer open or out of date, cap reached, or the account is busy"}, "200": {"description": "Dismissed"}}, "summary": "Dismiss a suggestion", "description": "Dismiss one open suggestion. It is not offered again for 30 days unless its evidence count doubles. Only the account owner, a tenant admin or a superadmin may call it; the key needs the icp:approve scope.", "operationId": "post_icp_search_term_suggestion_dismiss", "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["Ideal Customer Profile"]}}, "/icp/search-terms": {"post": {"responses": {"409": {"description": "Duplicate term, or the account is busy"}, "403": {"description": "Caller is not the owner or an admin, or the key lacks icp:approve"}, "401": {"description": "Unauthorized - API key missing or invalid"}, "400": {"description": "Invalid, covered or over-cap term"}, "201": {"description": "Search term added"}}, "summary": "Add a search term", "description": "Add one search term and activate a new ICP version. JSON body: {'term': str, 'match_mode': 'exact' | 'similar' (default exact), 'reactivate_term_id': int (optional)}. The term is stored as typed (trimmed, whitespace collapsed, lowercased). Refused when the text already exists (409 duplicate_term; 409 inactive_duplicate_term with its term_id: resend with reactivate_term_id), when the account is at the term cap (cap_reached) or when an active broader term already covers it (covered_term). Only the account owner, a tenant admin or a superadmin may add; the key needs the icp:approve scope.", "operationId": "post_icp_search_terms", "parameters": [{"name": "payload", "required": true, "in": "body", "schema": {"$ref": "#/definitions/SearchTermAdd"}}], "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["Ideal Customer Profile"]}}, "/icp/search-terms/health": {"get": {"responses": {"401": {"description": "Unauthorized - API key missing or invalid"}, "200": {"description": "Success"}}, "summary": "Get search-term health", "description": "Health of every active search term: status (healthy, zero_yield, low_yield, near_miss, checking), 30-day counts, open suggestions with real posting counts, titles left out as off-target and the allowed titles already accepted. Also the caller's banner state and the two notices to show before accepting: similar_titles_warning (disable_must_contain) and exact_title_notice (require_must_contain). Any user of the account may read.", "operationId": "get_icp_search_term_health", "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["Ideal Customer Profile"]}}, "/icp/search-terms/{term_id}": {"parameters": [{"name": "term_id", "in": "path", "required": true, "type": "integer"}], "delete": {"responses": {"409": {"description": "The account is busy; retry shortly"}, "404": {"description": "Search term not found or not active"}, "403": {"description": "Caller is not the owner or an admin, or the key lacks icp:approve"}, "401": {"description": "Unauthorized - API key missing or invalid"}, "400": {"description": "last_active_term"}, "200": {"description": "Search term removed"}}, "summary": "Remove a search term", "description": "Turn off one active search term and activate a new ICP version. Get term ids from GET /v1/icp 'search_terms'. The last active term can't be removed. Only the account owner, a tenant admin or a superadmin may remove; the key needs the icp:approve scope.", "operationId": "delete_icp_search_term", "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["Ideal Customer Profile"]}}, "/icp/search-terms/{term_id}/dismiss-open-suggestions": {"parameters": [{"name": "term_id", "in": "path", "required": true, "type": "integer"}], "post": {"responses": {"400": {"description": "Invalid request"}, "401": {"description": "Unauthorized - API key missing or invalid"}, "403": {"description": "Caller is not the owner or an admin, or the key lacks icp:approve"}, "404": {"description": "Suggestion, search term or allowed title not found for this account"}, "409": {"description": "Suggestion no longer open or out of date, cap reached, or the account is busy"}, "200": {"description": "Dismissed"}}, "summary": "Dismiss all of a term's open suggestions", "description": "'Done reviewing': dismiss every open suggestion of the term at once. Each is not offered again for 30 days unless its evidence count doubles. Only the account owner, a tenant admin or a superadmin may call it; the key needs the icp:approve scope.", "operationId": "post_icp_search_term_dismiss_open", "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["Ideal Customer Profile"]}}, "/icp/search-terms/{term_id}/keep": {"parameters": [{"name": "term_id", "in": "path", "required": true, "type": "integer"}], "post": {"responses": {"400": {"description": "Invalid request"}, "401": {"description": "Unauthorized - API key missing or invalid"}, "403": {"description": "Caller is not the owner or an admin, or the key lacks icp:approve"}, "404": {"description": "Suggestion, search term or allowed title not found for this account"}, "409": {"description": "Suggestion no longer open or out of date, cap reached, or the account is busy"}, "200": {"description": "Kept"}}, "summary": "Keep a search term as is", "description": "Keep a flagged term as it is: dismiss its open suggestions and stop flagging it in the banner, badges and digest for 30 days. Only the account owner, a tenant admin or a superadmin may call it; the key needs the icp:approve scope.", "operationId": "post_icp_search_term_keep", "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["Ideal Customer Profile"]}}, "/icp/search-terms/{term_id}/match-mode": {"parameters": [{"name": "term_id", "in": "path", "required": true, "type": "integer"}], "put": {"responses": {"404": {"description": "Search term not found for this account"}, "403": {"description": "Caller is not the owner or an admin, or the key lacks icp:approve"}, "401": {"description": "Unauthorized - API key missing or invalid"}, "400": {"description": "Invalid mode"}, "200": {"description": "Success"}}, "summary": "Set a search term's match mode", "description": "Set an active search term's match mode. JSON body: {'mode': 'exact' | 'similar'}. Get term ids from GET /v1/icp 'search_terms'. The response carries the similar-titles warning (mode similar) or the removal notice (mode exact); show it to the user before calling. Only the account owner, a tenant admin or a superadmin may change it; the key needs the icp:approve scope.", "operationId": "put_icp_search_term_match_mode", "parameters": [{"name": "payload", "required": true, "in": "body", "schema": {"$ref": "#/definitions/SearchTermMatchModeUpdate"}}], "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["Ideal Customer Profile"]}}, "/icp/search-terms/{term_id}/variants/{variant_id}": {"parameters": [{"name": "term_id", "in": "path", "required": true, "type": "integer"}, {"name": "variant_id", "in": "path", "required": true, "type": "integer"}], "delete": {"responses": {"400": {"description": "Invalid request"}, "401": {"description": "Unauthorized - API key missing or invalid"}, "403": {"description": "Caller is not the owner or an admin, or the key lacks icp:approve"}, "404": {"description": "Suggestion, search term or allowed title not found for this account"}, "409": {"description": "Suggestion no longer open or out of date, cap reached, or the account is busy"}, "200": {"description": "Removed"}}, "summary": "Remove an allowed title", "description": "Turn one allowed title off. From the next search spiders stop keeping new jobs with that title. No re-run is queued: jobs already kept keep their current match until the tenant's jobs are next reclassified, and stay until normal cleanup. Only the account owner, a tenant admin or a superadmin may call it; the key needs the icp:approve scope.", "operationId": "delete_icp_search_term_variant", "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["Ideal Customer Profile"]}}, "/integrations/chat-links": {"get": {"responses": {"400": {"description": "Invalid or expired token."}, "403": {"description": "Another account's token, or not allowed to manage that link."}, "404": {"description": "Link not found."}, "409": {"description": "The chat account belongs to another user; repeat with replace=true."}, "200": {"description": "Success", "schema": {"$ref": "#/definitions/ChatLinks"}}}, "summary": "List linked chat accounts", "description": "List your linked Slack and Discord accounts. The account owner, an admin or a superadmin may pass all=true for every link in the account.", "operationId": "get_chat_links_resource", "parameters": [{"description": "true: list every link in the account (admins only).", "name": "all", "type": "string", "in": "query"}], "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["integrations"]}, "post": {"responses": {"400": {"description": "Invalid or expired token."}, "403": {"description": "Another account's token, or not allowed to manage that link."}, "404": {"description": "Link not found."}, "409": {"description": "The chat account belongs to another user; repeat with replace=true."}}, "summary": "Confirm a chat link token", "description": "Link the chat account named by a bot link token to you. Returns 409 with linked_user_email when it belongs to someone else.", "operationId": "post_chat_links_resource", "parameters": [{"name": "payload", "required": true, "in": "body", "schema": {"$ref": "#/definitions/ChatLinkConfirm"}}], "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["integrations"]}}, "/integrations/chat-links/{link_id}": {"parameters": [{"name": "link_id", "in": "path", "required": true, "type": "integer"}], "delete": {"responses": {"400": {"description": "Invalid or expired token."}, "403": {"description": "Another account's token, or not allowed to manage that link."}, "404": {"description": "Link not found."}, "409": {"description": "The chat account belongs to another user; repeat with replace=true."}}, "summary": "Unlink a chat account", "description": "Remove a linked chat account: your own, or any in the account for the owner, an admin or a superadmin.", "operationId": "delete_chat_link_resource", "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["integrations"]}}, "/integrations/discord": {"get": {"responses": {"400": {"description": "Invalid channel or content type."}, "403": {"description": "Not the account owner, an admin or a superadmin."}, "409": {"description": "Not connected, or Discord refused the post."}, "502": {"description": "Discord could not be reached."}, "503": {"description": "Discord is not set up for Wihyu."}, "200": {"description": "Success", "schema": {"$ref": "#/definitions/DiscordConnection"}}}, "summary": "Get the Discord connection status", "description": "Read the Discord connection: server, alert channel, content type and the last post error.", "operationId": "get_discord_connection_resource", "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["integrations"]}, "put": {"responses": {"400": {"description": "Invalid channel or content type."}, "403": {"description": "Not the account owner, an admin or a superadmin."}, "409": {"description": "Not connected, or Discord refused the post."}, "502": {"description": "Discord could not be reached."}, "503": {"description": "Discord is not set up for Wihyu."}, "200": {"description": "Success", "schema": {"$ref": "#/definitions/DiscordConnection"}}}, "summary": "Save the Discord alert channel and content type", "description": "Choose the alert channel and content type. Posts a confirmation message there; if Discord answers 403/404 the previous setting is kept and the call returns 409.", "operationId": "put_discord_connection_resource", "parameters": [{"name": "payload", "required": true, "in": "body", "schema": {"$ref": "#/definitions/DiscordConfigure"}}], "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["integrations"]}, "delete": {"responses": {"400": {"description": "Invalid channel or content type."}, "403": {"description": "Not the account owner, an admin or a superadmin."}, "409": {"description": "Not connected, or Discord refused the post."}, "502": {"description": "Discord could not be reached."}, "503": {"description": "Discord is not set up for Wihyu."}, "200": {"description": "Success", "schema": {"$ref": "#/definitions/DiscordConnection"}}}, "summary": "Disconnect Discord", "description": "Remove the Discord connection. The bot leaves the server (best effort) and the channel and content type are cleared.", "operationId": "delete_discord_connection_resource", "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["integrations"]}}, "/integrations/discord/channels": {"get": {"responses": {"400": {"description": "Invalid channel or content type."}, "403": {"description": "Not the account owner, an admin or a superadmin."}, "409": {"description": "Not connected, or Discord refused the post."}, "502": {"description": "Discord could not be reached."}, "503": {"description": "Discord is not set up for Wihyu."}, "200": {"description": "Success", "schema": {"$ref": "#/definitions/DiscordChannels"}}}, "summary": "List Discord channels", "description": "List the connected server's text and announcement channels.", "operationId": "get_discord_channels_resource", "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["integrations"]}}, "/integrations/discord/install-url": {"post": {"responses": {"400": {"description": "Invalid channel or content type."}, "403": {"description": "Not the account owner, an admin or a superadmin."}, "409": {"description": "Not connected, or Discord refused the post."}, "502": {"description": "Discord could not be reached."}, "503": {"description": "Discord is not set up for Wihyu."}, "200": {"description": "Success", "schema": {"$ref": "#/definitions/DiscordInstallUrl"}}}, "summary": "Get the Discord install URL", "description": "Start the install: returns a signed Discord authorize URL for the user to open in a browser.", "operationId": "post_discord_install_url_resource", "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["integrations"]}}, "/integrations/discord/test": {"post": {"responses": {"400": {"description": "Invalid channel or content type."}, "403": {"description": "Not the account owner, an admin or a superadmin."}, "409": {"description": "Not connected, or Discord refused the post."}, "502": {"description": "Discord could not be reached."}, "503": {"description": "Discord is not set up for Wihyu."}}, "summary": "Send a Discord test message", "description": "Post a test message in the saved Discord alert channel.", "operationId": "post_discord_test_resource", "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["integrations"]}}, "/integrations/hubspot": {"get": {"responses": {"403": {"description": "Not the account owner, an admin or a superadmin."}, "503": {"description": "HubSpot is not set up for Wihyu."}, "200": {"description": "Success", "schema": {"$ref": "#/definitions/HubSpotConnection"}}}, "summary": "Get the HubSpot connection status", "description": "Read the HubSpot connection: portal, whether the saved token still works and the last sync. Open to every user of the account. Never returns tokens.", "operationId": "get_hub_spot_connection_resource", "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["integrations"]}, "delete": {"responses": {"403": {"description": "Not the account owner, an admin or a superadmin."}, "503": {"description": "HubSpot is not set up for Wihyu."}, "200": {"description": "Success", "schema": {"$ref": "#/definitions/HubSpotConnection"}}}, "summary": "Disconnect HubSpot", "description": "Remove the HubSpot connection from Wihyu (the saved tokens are deleted). Repeating the call succeeds.", "operationId": "delete_hub_spot_connection_resource", "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["integrations"]}}, "/integrations/hubspot/install-url": {"post": {"responses": {"403": {"description": "Not the account owner, an admin or a superadmin."}, "503": {"description": "HubSpot is not set up for Wihyu."}, "200": {"description": "Success", "schema": {"$ref": "#/definitions/HubSpotInstallUrl"}}}, "summary": "Get the HubSpot install URL", "description": "Start the install: returns a signed HubSpot authorize URL. The user must open it in a browser signed in to Wihyu as the same user who asked for it, or the connection is refused (state_mismatch).", "operationId": "post_hub_spot_install_url_resource", "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["integrations"]}}, "/integrations/slack": {"get": {"responses": {"400": {"description": "Invalid content type."}, "403": {"description": "Not the account owner, an admin or a superadmin."}, "409": {"description": "Slack is not connected."}, "503": {"description": "Slack is not set up for Wihyu."}, "200": {"description": "Success", "schema": {"$ref": "#/definitions/SlackConnection"}}}, "summary": "Get the Slack connection status", "description": "Read the Slack connection: workspace, alert channel and content type. Never returns tokens or the webhook URL.", "operationId": "get_slack_connection_resource", "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["integrations"]}, "put": {"responses": {"400": {"description": "Invalid content type."}, "403": {"description": "Not the account owner, an admin or a superadmin."}, "409": {"description": "Slack is not connected."}, "503": {"description": "Slack is not set up for Wihyu."}, "200": {"description": "Success", "schema": {"$ref": "#/definitions/SlackConnection"}}}, "summary": "Save the Slack alert content type", "description": "Choose the alert content type. The alert channel is the one picked when Slack was installed.", "operationId": "put_slack_connection_resource", "parameters": [{"name": "payload", "required": true, "in": "body", "schema": {"$ref": "#/definitions/SlackConfigure"}}], "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["integrations"]}, "delete": {"responses": {"400": {"description": "Invalid content type."}, "403": {"description": "Not the account owner, an admin or a superadmin."}, "409": {"description": "Slack is not connected."}, "503": {"description": "Slack is not set up for Wihyu."}, "200": {"description": "Success", "schema": {"$ref": "#/definitions/SlackConnection"}}}, "summary": "Disconnect Slack", "description": "Remove the Slack connection from Wihyu. The Slack app itself stays installed in the workspace.", "operationId": "delete_slack_connection_resource", "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["integrations"]}}, "/integrations/slack/install-url": {"post": {"responses": {"400": {"description": "Invalid content type."}, "403": {"description": "Not the account owner, an admin or a superadmin."}, "409": {"description": "Slack is not connected."}, "503": {"description": "Slack is not set up for Wihyu."}, "200": {"description": "Success", "schema": {"$ref": "#/definitions/SlackInstallUrl"}}}, "summary": "Get the Slack install URL", "description": "Start the install: returns a signed Slack authorize URL for the user to open in a browser.", "operationId": "post_slack_install_url_resource", "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["integrations"]}}, "/recommendations": {"get": {"responses": {"401": {"description": "Unauthorized - API key missing or invalid"}, "200": {"description": "Success", "schema": {"$ref": "#/definitions/CompanyListResponse"}}}, "summary": "List recommended companies", "description": "List recommended companies using the same base criteria and KPI filters as the recommendations dashboard. Supports filter values all, new_leads, crm_candidates, in_crm, and actively_hiring, plus shared company filters and pagination.", "operationId": "get_recommendations", "parameters": [{"enum": ["all", "new_leads", "crm_candidates", "in_crm", "actively_hiring"], "in": "query", "description": "Recommendation filter preset", "name": "filter", "type": "string"}, {"type": "string", "in": "query", "description": "Employee count facet filter", "name": "employees"}, {"type": "string", "in": "query", "description": "Revenue range facet filter", "name": "revenue"}, {"type": "string", "in": "query", "description": "Industry facet filter", "name": "category_industry"}, {"type": "string", "in": "query", "description": "Industry group facet filter", "name": "category_industry_group"}, {"type": "string", "in": "query", "description": "Filter companies with jobs matching title", "name": "job_title"}, {"type": "string", "in": "query", "description": "Industry sector filter (alias category_sector)", "name": "sector"}, {"type": "string", "in": "query", "description": "Only companies with jobs after date (YYYY-MM-DD)", "name": "found_after"}, {"type": "number", "in": "query", "description": "Minimum ICP match score (0-1)", "name": "min_icp_score"}, {"type": "string", "in": "query", "description": "Quality decision bucket filter", "name": "decision_bucket"}, {"type": "string", "in": "query", "description": "CRM owner filter", "name": "crm_owner"}, {"type": "string", "in": "query", "description": "CRM status filter: in_crm (linked records only; the in_crm filter preset also includes unlinked candidates), crm_candidate, not_in_crm, aliases __new_lead__ and __crm_candidate__, or a CRM stage name", "name": "crm_status"}, {"type": "string", "in": "query", "description": "Job title search term filter", "name": "searchterm"}, {"enum": ["1", "2", "3", "4", "5"], "in": "query", "description": "Fit score bucket (1-5)", "name": "fit_score_bucket", "type": "string"}, {"enum": ["0", "1"], "in": "query", "description": "Deep search flag filter", "name": "flag_deep_search", "type": "string"}, {"type": "string", "in": "query", "description": "Custom category filter", "name": "category"}, {"type": "string", "in": "query", "description": "Workflow status label filter", "name": "workflow_status"}, {"enum": ["asc", "desc"], "in": "query", "description": "Sort direction", "name": "sort_dir", "type": "string"}, {"type": "string", "in": "query", "description": "Column to sort by", "name": "sort_by"}, {"type": "string", "in": "query", "description": "Search query (alias search)", "name": "q"}, {"type": "integer", "in": "query", "description": "Number of results per page", "name": "per_page"}, {"type": "integer", "in": "query", "description": "Page number (1-based)", "name": "page"}], "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["companies"]}}, "/tenant-requests": {"post": {"responses": {"200": {"description": "Success"}}, "operationId": "post_tenant_requests_create", "tags": ["tenant requests"]}}, "/tenant-requests/{request_id}": {"parameters": [{"name": "request_id", "in": "path", "required": true, "type": "integer"}], "get": {"responses": {"200": {"description": "Success"}}, "operationId": "get_tenant_request_status", "tags": ["tenant requests"]}}, "/tenant-requests/{request_id}/code": {"parameters": [{"name": "request_id", "in": "path", "required": true, "type": "integer"}], "post": {"responses": {"200": {"description": "Success"}}, "operationId": "post_tenant_request_code", "tags": ["tenant requests"]}}, "/tenant-setups/{tenant_id}": {"parameters": [{"name": "tenant_id", "in": "path", "required": true, "type": "integer"}], "get": {"responses": {"404": {"description": "Tenant not found"}, "401": {"description": "Unauthorized - API key missing or invalid"}, "200": {"description": "Success"}}, "summary": "Get tenant setup status for one tenant", "description": "Get tenant setup status, progress, requirements, next_actions and results_preview (CORE-2) for the caller's own tenant. The path tenant_id must match the authenticated credential's tenant, or any other tenant (including one that doesn't exist) returns 404 (AGT-9) rather than 401/403, so a caller can't distinguish 'not yours' from 'doesn't exist'.", "operationId": "get_tenant_setup_status", "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["tenant setups"]}}, "/tenant-setups/{tenant_id}/approve-icp": {"parameters": [{"name": "tenant_id", "in": "path", "required": true, "type": "integer"}], "post": {"responses": {"200": {"description": "Success"}}, "operationId": "post_tenant_approve_icp", "tags": ["tenant setups"]}}, "/tenant-setups/{tenant_id}/example-companies": {"parameters": [{"name": "tenant_id", "in": "path", "required": true, "type": "integer"}], "put": {"responses": {"200": {"description": "Success"}}, "operationId": "put_tenant_example_companies", "tags": ["tenant setups"]}}, "/tenant-setups/{tenant_id}/feedback": {"parameters": [{"name": "tenant_id", "in": "path", "required": true, "type": "integer"}], "post": {"responses": {"200": {"description": "Success"}}, "operationId": "post_tenant_feedback", "tags": ["tenant setups"]}}, "/tenant-setups/{tenant_id}/icp-draft": {"parameters": [{"name": "tenant_id", "in": "path", "required": true, "type": "integer"}], "get": {"responses": {"200": {"description": "Success"}}, "operationId": "get_tenant_icp_draft", "tags": ["tenant setups"]}, "patch": {"responses": {"200": {"description": "Success"}}, "operationId": "patch_tenant_icp_draft", "tags": ["tenant setups"]}}, "/tenant-setups/{tenant_id}/results-preview": {"parameters": [{"name": "tenant_id", "in": "path", "required": true, "type": "integer"}], "get": {"responses": {"200": {"description": "Success"}}, "operationId": "get_tenant_results_preview", "tags": ["tenant setups"]}}, "/tenant-setups/{tenant_id}/retry-step": {"parameters": [{"name": "tenant_id", "in": "path", "required": true, "type": "integer"}], "post": {"responses": {"409": {"description": "No retryable step in the current state."}, "404": {"description": "Tenant not found."}, "403": {"description": "Not the account owner or a superadmin."}}, "summary": "Retry the current setup step", "description": "Retry the tenant's failed or stalled setup step (the web 'Try again'). Only the account owner or a superadmin; 409 when no step can be retried from the current setup state.", "operationId": "post_tenant_retry_step", "tags": ["tenant setups"]}}, "/tenant-setups/{tenant_id}/search-terms": {"parameters": [{"name": "tenant_id", "in": "path", "required": true, "type": "integer"}], "post": {"responses": {"200": {"description": "Success"}}, "summary": "WIH-1589: add one search term during setup", "operationId": "post_tenant_search_terms", "tags": ["tenant setups"]}, "put": {"responses": {"200": {"description": "Success"}}, "operationId": "put_tenant_search_terms", "tags": ["tenant setups"]}}, "/tenant-setups/{tenant_id}/search-terms/{term_id}": {"parameters": [{"name": "tenant_id", "in": "path", "required": true, "type": "integer"}, {"name": "term_id", "in": "path", "required": true, "type": "integer"}], "delete": {"responses": {"200": {"description": "Success"}}, "summary": "WIH-1589: drop one search term during setup", "operationId": "delete_tenant_search_term", "tags": ["tenant setups"]}}, "/tenant-setups/{tenant_id}/terms/{term_id}/examples": {"parameters": [{"name": "tenant_id", "in": "path", "required": true, "type": "integer"}, {"name": "term_id", "in": "path", "required": true, "type": "integer"}], "get": {"responses": {"200": {"description": "Success"}}, "summary": "Up to 3 matching postings for a term: the latest first run's during", "description": "setup, the newest collected jobs for the term once the account is live.", "operationId": "get_tenant_term_examples", "tags": ["tenant setups"]}}, "/tenant-setups/{tenant_id}/terms/{term_id}/sample": {"parameters": [{"name": "tenant_id", "in": "path", "required": true, "type": "integer"}, {"name": "term_id", "in": "path", "required": true, "type": "integer"}], "put": {"responses": {"202": {"description": "Submitted for approval (active account)"}, "200": {"description": "Saved (during setup)"}}, "summary": "Paste a sample job description for a term", "description": "Paste a job description as this search term's sample. It becomes the active sample (the last action wins); confirmed postings are kept. Pasted text is trimmed and must be 60 to 20,000 characters. During setup the change is saved at once (200, applied true). For an active account it is stored as a suggested change (202, applied false, with a proposal block) and applied with apply_icp_proposal / POST /v1/icp/proposals/{id}/apply. Errors: sample_empty, sample_too_short, sample_too_long, invalid_request (400); forbidden (403); term_not_found (404); term_not_active, no_pasted_sample, posting_not_confirmed, posting_not_candidate, posting_rejected (409). A pending change that has gone out of date is returned with stale_reason (term_removed, posting_missing, posting_rejected, sample_changed).", "operationId": "put_tenant_term_sample", "parameters": [{"name": "payload", "required": true, "in": "body", "schema": {"$ref": "#/definitions/TermSampleSet"}}], "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["tenant setups"]}, "delete": {"responses": {"202": {"description": "Submitted for approval (active account)"}, "200": {"description": "Removed (during setup)"}}, "summary": "Remove the pasted sample for a term", "description": "Delete the pasted sample. If it was active, the most recently confirmed posting becomes the sample. Pasted text is trimmed and must be 60 to 20,000 characters. During setup the change is saved at once (200, applied true). For an active account it is stored as a suggested change (202, applied false, with a proposal block) and applied with apply_icp_proposal / POST /v1/icp/proposals/{id}/apply. Errors: sample_empty, sample_too_short, sample_too_long, invalid_request (400); forbidden (403); term_not_found (404); term_not_active, no_pasted_sample, posting_not_confirmed, posting_not_candidate, posting_rejected (409). A pending change that has gone out of date is returned with stale_reason (term_removed, posting_missing, posting_rejected, sample_changed).", "operationId": "delete_tenant_term_sample", "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["tenant setups"]}}, "/tenant-setups/{tenant_id}/terms/{term_id}/sample/confirm": {"parameters": [{"name": "tenant_id", "in": "path", "required": true, "type": "integer"}, {"name": "term_id", "in": "path", "required": true, "type": "integer"}], "post": {"responses": {"202": {"description": "Submitted for approval (active account)"}, "200": {"description": "Confirmed (during setup)"}}, "summary": "Confirm a matching posting as the term's sample", "description": "Confirm one of the term's matching postings (from the term's examples) as its sample, like the owner's \"This kind of job\" button. Pasted text is trimmed and must be 60 to 20,000 characters. During setup the change is saved at once (200, applied true). For an active account it is stored as a suggested change (202, applied false, with a proposal block) and applied with apply_icp_proposal / POST /v1/icp/proposals/{id}/apply. Errors: sample_empty, sample_too_short, sample_too_long, invalid_request (400); forbidden (403); term_not_found (404); term_not_active, no_pasted_sample, posting_not_confirmed, posting_not_candidate, posting_rejected (409). A pending change that has gone out of date is returned with stale_reason (term_removed, posting_missing, posting_rejected, sample_changed).", "operationId": "post_tenant_term_sample_confirm", "parameters": [{"name": "payload", "required": true, "in": "body", "schema": {"$ref": "#/definitions/TermSampleConfirm"}}], "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["tenant setups"]}}, "/tenant-setups/{tenant_id}/terms/{term_id}/sample/reject": {"parameters": [{"name": "tenant_id", "in": "path", "required": true, "type": "integer"}, {"name": "term_id", "in": "path", "required": true, "type": "integer"}], "post": {"responses": {"202": {"description": "Submitted for approval (active account)"}, "200": {"description": "Rejected (during setup)"}}, "summary": "Mark a matching posting \"Not this\" for the term", "description": "Mark one of the term's matching postings as not the kind of job meant, like the owner's \"Not this\" button. It is hidden for the term and the next matching posting takes its place. Pasted text is trimmed and must be 60 to 20,000 characters. During setup the change is saved at once (200, applied true). For an active account it is stored as a suggested change (202, applied false, with a proposal block) and applied with apply_icp_proposal / POST /v1/icp/proposals/{id}/apply. Errors: sample_empty, sample_too_short, sample_too_long, invalid_request (400); forbidden (403); term_not_found (404); term_not_active, no_pasted_sample, posting_not_confirmed, posting_not_candidate, posting_rejected (409). A pending change that has gone out of date is returned with stale_reason (term_removed, posting_missing, posting_rejected, sample_changed).", "operationId": "post_tenant_term_sample_reject", "parameters": [{"name": "payload", "required": true, "in": "body", "schema": {"$ref": "#/definitions/TermSampleReject"}}], "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["tenant setups"]}}, "/tenant-setups/{tenant_id}/terms/{term_id}/sample/use": {"parameters": [{"name": "tenant_id", "in": "path", "required": true, "type": "integer"}, {"name": "term_id", "in": "path", "required": true, "type": "integer"}], "post": {"responses": {"202": {"description": "Submitted for approval (active account)"}, "200": {"description": "Switched (during setup)"}}, "summary": "Use a confirmed posting or the pasted text as the sample", "description": "Switch which sample the term uses: a confirmed posting (source 'posting' with job_id) or the pasted text (source 'pasted'). Pasted text is trimmed and must be 60 to 20,000 characters. During setup the change is saved at once (200, applied true). For an active account it is stored as a suggested change (202, applied false, with a proposal block) and applied with apply_icp_proposal / POST /v1/icp/proposals/{id}/apply. Errors: sample_empty, sample_too_short, sample_too_long, invalid_request (400); forbidden (403); term_not_found (404); term_not_active, no_pasted_sample, posting_not_confirmed, posting_not_candidate, posting_rejected (409). A pending change that has gone out of date is returned with stale_reason (term_removed, posting_missing, posting_rejected, sample_changed).", "operationId": "post_tenant_term_sample_use", "parameters": [{"name": "payload", "required": true, "in": "body", "schema": {"$ref": "#/definitions/TermSampleUse"}}], "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["tenant setups"]}}, "/workflow-statuses": {"get": {"responses": {"401": {"description": "Unauthorized - API key missing or invalid"}, "200": {"description": "Success", "schema": {"$ref": "#/definitions/WorkflowStatusesResponse"}}}, "summary": "List workflow statuses", "description": "List all workflow statuses defined for this account.", "operationId": "get_workflow_statuses", "security": [{"Bearer": []}, {"ApiKey": []}], "tags": ["companies"]}}}, "info": {"title": "Wihyu API", "version": "1.0", "description": "REST API for the Wihyu.com business intelligence platform. Authenticate with your API key from the Wihyu profile page using `Authorization: Bearer <key>` or `X-API-Key: <key>`.\n\nThe MCP server at `/v1/mcp` uses the Model Context Protocol (Streamable HTTP, spec 2025-11-25) and is not documented here. See the MCP setup guide for connection instructions."}, "produces": ["application/json"], "consumes": ["application/json"], "securityDefinitions": {"Bearer": {"type": "apiKey", "in": "header", "name": "Authorization", "description": "Enter: **Bearer &lt;your-api-key&gt;**. Get your key from Settings &gt; API Key on your Wihyu profile page."}, "ApiKey": {"type": "apiKey", "in": "header", "name": "X-API-Key"}}, "security": [{"Bearer": []}], "tags": [{"name": "companies", "description": "Company search, recommendations, and company detail endpoints."}, {"name": "Ideal Customer Profile", "description": "Ideal Customer Profile definition endpoints."}, {"name": "alerts", "description": "Email alert settings endpoints."}, {"name": "design preferences", "description": "Classic/new page design choices (WIH-1882)."}, {"name": "tenant setups", "description": "Tenant setup progress endpoints (WIH-1162 CORE-2)."}, {"name": "integrations", "description": "Chat integration endpoints (Discord connection, WIH-1645)."}, {"name": "api keys", "description": "API key management endpoints (WIH-1765)."}, {"name": "tenant requests", "description": "Public tenant-request intake (WIH-1162/1169): create a pending tenant-setup request and poll its status. Anonymous or the wihyu.com form key (FORM_API_KEY)."}], "definitions": {"CompanyListResponse": {"properties": {"data": {"type": "array", "items": {"$ref": "#/definitions/CompanyListItem"}}, "pagination": {"$ref": "#/definitions/Pagination"}, "recordsFiltered": {"type": "integer", "description": "DataTables-compatible filtered count"}, "recordsTotal": {"type": "integer", "description": "DataTables-compatible total count"}, "draw": {"type": "integer", "description": "DataTables draw counter"}}, "type": "object"}, "CompanyListItem": {"properties": {"id": {"type": "integer", "description": "Internal company ID"}, "name": {"type": "string", "description": "Company name"}, "displayname": {"type": "string", "description": "Display name"}, "legalname": {"type": "string", "description": "Legal name"}, "domain": {"type": "string", "description": "Primary domain"}, "website_url": {"type": "string", "description": "Canonical reachable website URL"}, "linkedin_page": {"type": "string", "description": "LinkedIn URL"}, "twitter_page": {"type": "string", "description": "Twitter/X URL"}, "facebook_page": {"type": "string", "description": "Facebook URL"}, "category": {"type": "string", "description": "Custom category label"}, "category_sector": {"type": "string", "description": "Industry sector"}, "category_industry_group": {"type": "string", "description": "Industry group"}, "category_industry": {"type": "string", "description": "Industry"}, "category_subindustry": {"type": "string", "description": "Subindustry"}, "revenue": {"type": "string", "description": "Revenue range"}, "employees": {"type": "string", "description": "Employee count range"}, "m_jobs_count": {"type": "integer", "description": "Total matching jobs"}, "m_jobs_count_30": {"type": "integer", "description": "Matching jobs in last 30 days"}, "m_jobs_count_7": {"type": "integer", "description": "Matching jobs in last 7 days"}, "m_jobs_latest": {"type": "string", "description": "Most recent matching job date"}, "evidence_strength_score": {"type": "number", "description": "Fit score from 0-100"}, "fit_score": {"type": "integer", "description": "Rounded fit score"}, "score_level": {"type": "integer", "description": "Fit score display level from 0-5"}, "score_emoji": {"type": "string", "description": "Fit score display marker"}, "fit_score_tooltip": {"type": "string", "description": "Fit score detail text"}, "fit_reasons": {"type": "array", "description": "Match reason bullets", "items": {"type": "string"}}, "icp_match_score": {"type": "number", "description": "ICP match score from 0-1"}, "icp_confidence": {"type": "number", "description": "ICP confidence from 0-1"}, "decision_bucket": {"type": "string", "description": "Quality decision bucket"}, "supporting_evidence_flags": {"type": "array", "description": "Positive evidence flags used in company quality gating (DM-012)", "items": {"type": "string"}}, "intermediary_reason_codes": {"type": "array", "description": "Human-readable reasons when postings appear intermediary-led (DM-013)", "items": {"type": "string"}}, "relevant_jobs_60d_count": {"type": "integer", "description": "Relevant jobs in the last 60 days"}, "is_probable_intermediary_posting": {"type": "boolean", "description": "Whether postings likely came through an intermediary"}, "stale_job_ratio": {"type": "number", "description": "Ratio of stale jobs"}, "flag_hidden": {"type": "boolean", "description": "Whether company is hidden"}, "flag_deep_search": {"type": "boolean", "description": "Whether deep search is enabled"}, "workflow_status_id": {"type": "integer", "description": "Workflow status ID"}, "status": {"type": "string", "description": "Workflow status label"}, "category_custom_id": {"type": "integer", "description": "Custom category ID"}, "notes": {"type": "string", "description": "Company notes"}, "crm_status": {"type": "string", "description": "CRM status: in_crm, crm_candidate, not_in_crm"}, "crm_stage": {"type": "string", "description": "CRM stage label"}, "crm_owner": {"type": "string", "description": "CRM owner"}, "feedback_action": {"type": "string", "description": "Company feedback action"}, "feedback_comment": {"type": "string", "description": "Company feedback comment"}, "created": {"type": "string", "description": "Record created timestamp"}, "modified": {"type": "string", "description": "Record last modified timestamp"}}, "type": "object"}, "Pagination": {"properties": {"page": {"type": "integer", "description": "Current page number"}, "per_page": {"type": "integer", "description": "Page size"}, "total": {"type": "integer", "description": "Total records after filtering"}, "total_pages": {"type": "integer", "description": "Total page count after filtering"}}, "type": "object"}, "ErrorResponse": {"required": ["error"], "properties": {"error": {"$ref": "#/definitions/ErrorDetail"}}, "type": "object"}, "ErrorDetail": {"required": ["code", "message"], "properties": {"code": {"type": "string", "description": "Stable snake_case code"}, "message": {"type": "string", "description": "Human-readable message"}, "next_action": {"type": "string", "description": "The call that unblocks the caller, or null"}}, "type": "object"}, "CompanyDetail": {"properties": {"id": {"type": "integer", "description": "Internal company ID"}, "name": {"type": "string", "description": "Company name"}, "displayname": {"type": "string", "description": "Display name"}, "legalname": {"type": "string", "description": "Legal name"}, "domain": {"type": "string", "description": "Primary domain"}, "website_url": {"type": "string", "description": "Canonical reachable website URL"}, "linkedin_page": {"type": "string", "description": "LinkedIn URL"}, "twitter_page": {"type": "string", "description": "Twitter/X URL"}, "facebook_page": {"type": "string", "description": "Facebook URL"}, "category": {"type": "string", "description": "Custom category label"}, "category_sector": {"type": "string", "description": "Industry sector"}, "category_industry_group": {"type": "string", "description": "Industry group"}, "category_industry": {"type": "string", "description": "Industry"}, "category_subindustry": {"type": "string", "description": "Subindustry"}, "revenue": {"type": "string", "description": "Revenue range"}, "employees": {"type": "string", "description": "Employee count range"}, "m_jobs_count": {"type": "integer", "description": "Total matching jobs"}, "m_jobs_count_30": {"type": "integer", "description": "Matching jobs in last 30 days"}, "m_jobs_count_7": {"type": "integer", "description": "Matching jobs in last 7 days"}, "m_jobs_latest": {"type": "string", "description": "Most recent matching job date"}, "evidence_strength_score": {"type": "number", "description": "Fit score from 0-100"}, "fit_score": {"type": "integer", "description": "Rounded fit score"}, "score_level": {"type": "integer", "description": "Fit score display level from 0-5"}, "score_emoji": {"type": "string", "description": "Fit score display marker"}, "fit_score_tooltip": {"type": "string", "description": "Fit score detail text"}, "fit_reasons": {"type": "array", "description": "Match reason bullets", "items": {"type": "string"}}, "icp_match_score": {"type": "number", "description": "ICP match score from 0-1"}, "icp_confidence": {"type": "number", "description": "ICP confidence from 0-1"}, "decision_bucket": {"type": "string", "description": "Quality decision bucket"}, "supporting_evidence_flags": {"type": "array", "description": "Positive evidence flags used in company quality gating (DM-012)", "items": {"type": "string"}}, "intermediary_reason_codes": {"type": "array", "description": "Human-readable reasons when postings appear intermediary-led (DM-013)", "items": {"type": "string"}}, "relevant_jobs_60d_count": {"type": "integer", "description": "Relevant jobs in the last 60 days"}, "is_probable_intermediary_posting": {"type": "boolean", "description": "Whether postings likely came through an intermediary"}, "stale_job_ratio": {"type": "number", "description": "Ratio of stale jobs"}, "flag_hidden": {"type": "boolean", "description": "Whether company is hidden"}, "flag_deep_search": {"type": "boolean", "description": "Whether deep search is enabled"}, "workflow_status_id": {"type": "integer", "description": "Workflow status ID"}, "status": {"type": "string", "description": "Workflow status label"}, "category_custom_id": {"type": "integer", "description": "Custom category ID"}, "notes": {"type": "string", "description": "Company notes"}, "crm_status": {"type": "string", "description": "CRM status: in_crm, crm_candidate, not_in_crm"}, "crm_stage": {"type": "string", "description": "CRM stage label"}, "crm_owner": {"type": "string", "description": "CRM owner"}, "feedback_action": {"type": "string", "description": "Company feedback action"}, "feedback_comment": {"type": "string", "description": "Company feedback comment"}, "created": {"type": "string", "description": "Record created timestamp"}, "modified": {"type": "string", "description": "Record last modified timestamp"}, "description": {"type": "string", "description": "Company description"}, "description_source": {"type": "string", "description": "Company description source"}, "description_updated_at": {"type": "string", "description": "Description update timestamp"}, "logo": {"type": "string", "description": "Logo URL"}, "reference_url": {"type": "string", "description": "Reference URL"}, "stock_symbol": {"type": "string", "description": "Stock symbol"}, "address": {"type": "string", "description": "Company address"}, "lat": {"type": "number", "description": "Latitude"}, "long": {"type": "number", "description": "Longitude"}, "flags": {"type": "object", "description": "Company flag values"}, "quality": {"type": "object", "description": "Company quality metadata"}, "icp": {"type": "object", "description": "ICP scoring metadata"}, "domain_resolution": {"type": "object", "description": "Domain resolution metadata"}, "aliases": {"type": "object", "description": "Company aliases"}, "domain_aliases": {"type": "object", "description": "Domain aliases"}, "crm_links": {"type": "object", "description": "CRM link rows"}, "recent_jobs": {"type": "array", "description": "Up to 100 recent tenant-scoped job rows", "items": {"$ref": "#/definitions/CompanyRecentJob"}}, "job_activity_score": {"type": "object", "description": "Latest job activity score"}}, "type": "object"}, "CompanyRecentJob": {"properties": {"id": {"type": "integer", "description": "Internal job row ID"}, "job_id": {"type": "string", "description": "Source job identifier"}, "found_date": {"type": "string", "description": "Job discovery date"}, "title": {"type": "string", "description": "Job title"}, "normalized_title": {"type": "string", "description": "Normalized job title"}, "normalization_status": {"type": "string", "description": "Title normalization status"}, "location": {"type": "string", "description": "Job location"}, "summary": {"type": "string", "description": "Best available job-description text collected for the posting"}, "description_truncated": {"type": "boolean", "description": "True when the text is known partial, false when known complete, or null when completeness is unknown"}, "description_source": {"type": "string", "description": "How the description was obtained: detail, card, feed or prior; null for older postings. card means the posting was saved from search results alone, so summary is empty"}, "description_notice": {"type": "string", "description": "Shown in place of an empty description: set only when description_source is card and summary is empty; null otherwise"}, "link": {"type": "string", "description": "Posting URL"}, "via": {"type": "string", "description": "Listing provider"}, "source": {"type": "string", "description": "Collector source"}, "source_label": {"type": "string", "description": "Source text to display. Headcount Labs jobs read 'Headcount Labs, via {platform}'; other jobs repeat via"}, "attribution": {"description": "Licence attribution notice to show next to the source; null when the posting needs none", "allOf": [{"$ref": "#/definitions/JobAttribution"}]}, "searched_title": {"type": "string", "description": "Search term that found the job"}, "show_link": {"type": "boolean", "description": "Whether the posting link is current"}}, "type": "object"}, "JobAttribution": {"properties": {"text": {"type": "string", "description": "Attribution text to display"}, "link": {"type": "string", "description": "Absolute http(s) URL for the text, or null"}}, "type": "object"}, "WorkflowStatusesResponse": {"properties": {"workflow_statuses": {"type": "array", "description": "Workflow statuses defined for the authenticated tenant", "items": {"$ref": "#/definitions/WorkflowStatusItem"}}}, "type": "object"}, "WorkflowStatusItem": {"properties": {"id": {"type": "integer", "description": "Workflow status ID"}, "status": {"type": "string", "description": "Workflow status label"}}, "type": "object"}, "IcpDefinitionUpdate": {"properties": {"natural_language_guidance": {"type": "string", "description": "Editable guidance; an explicit empty string clears it."}, "search_terms": {"type": "array", "description": "Editable search terms, canonicalized and capped by the live tenant setting.", "items": {"type": "string"}}, "job_postings_by_term": {"type": "object", "description": "Editable string-to-string evidence map; every active term requires a sample."}, "industries": {"type": "array", "description": "Target industries; replaces the current list (max 5).", "items": {"type": "string"}}, "company_size": {"type": "string", "description": "Target company size."}, "geography": {"type": "array", "description": "Target geographies; replaces the current list (max 50).", "items": {"type": "string"}}, "target_job_titles": {"type": "array", "description": "Target job titles; replaces the current list (max 50).", "items": {"type": "string"}}, "negative_traits": {"type": "array", "description": "Poor-fit traits; replaces the current list (max 5).", "items": {"type": "string"}}, "reactivate_term_ids": {"type": "array", "description": "Ids of turned-off search terms to turn back on. A term in search_terms that matches a turned-off term is refused with 409 inactive_duplicate_term (its term_id is in the error) unless its id is listed here.", "items": {"type": "integer"}}, "note": {"type": "string", "description": "Optional ICP context note."}, "note_mode": {"type": "string", "description": "Note update mode; defaults to append.", "example": "append", "enum": ["append", "replace"]}}, "type": "object"}, "IcpDefinition": {"properties": {"id": {"type": "integer", "description": "ICP profile ID"}, "name": {"type": "string", "description": "ICP profile name"}, "natural_language_guidance": {"type": "string", "description": "ICP natural language description"}, "primary_search_term": {"type": "string", "description": "Primary job title search term"}, "active_search_terms": {"type": "array", "description": "Active job title search terms", "items": {"type": "string"}}, "search_terms": {"type": "array", "description": "Active search terms with their match mode", "items": {"$ref": "#/definitions/SearchTermMatchMode"}}, "sample_target_job_posting": {"type": "string", "description": "Sample target job posting text"}, "job_postings_by_term": {"type": "object", "description": "Canonical per-term sample job postings"}, "structured_definition": {"type": "object", "description": "Read-only structured ICP projection"}, "user_notes": {"type": "string", "description": "User-authored context notes"}, "updated_at": {"type": "string", "description": "Last updated timestamp"}}, "type": "object"}, "SearchTermMatchMode": {"properties": {"term_id": {"type": "integer", "description": "Search term ID"}, "term": {"type": "string", "description": "Search term text"}, "match_mode": {"type": "string", "description": "exact (title must contain the term) or similar"}, "flag_must_contain": {"type": "boolean", "description": "True in exact mode"}, "similar_titles_recent": {"type": "array", "description": "Recent job titles found only through similar-title matching", "items": {"type": "string"}}}, "type": "object"}, "SearchTermMatchModeUpdate": {"required": ["mode"], "properties": {"mode": {"type": "string", "description": "New match mode", "example": "exact", "enum": ["exact", "similar"]}}, "type": "object"}, "SearchTermAdd": {"required": ["term"], "properties": {"term": {"type": "string", "description": "Search term text. Stored as typed, trimmed, with whitespace collapsed and lowercased; nothing else is changed."}, "match_mode": {"type": "string", "description": "exact (title must contain the term) or similar", "default": "exact", "example": "exact", "enum": ["exact", "similar"]}, "reactivate_term_id": {"type": "integer", "description": "Id of the turned-off term this text matches, to turn it back on"}}, "type": "object"}, "IcpProposal": {"properties": {"proposal_id": {"type": "integer", "description": "Null when there is no proposal."}, "trigger": {"type": "string", "description": "manual (website research) or sample_edit (a pasted-sample change waiting for approval)."}, "status": {"type": "string", "description": "none | researching | applying | failed | no_change | ready | stale (applied, discarded or superseded when read by id). applying: an apply is running; poll until it leaves applying. A ready proposal with an error means the last apply did not go through."}, "requested_at": {"type": "string", "description": "ISO 8601."}, "finished_at": {"type": "string", "description": "ISO 8601."}, "base_version_number": {"type": "integer"}, "live_version_number": {"type": "integer"}, "message": {"type": "string", "description": "Owner-facing wording."}, "limits": {"type": "object", "description": "Manual-request and preview-search limits."}, "next_actions": {"type": "array", "items": {"type": "string"}}, "diff": {"type": "object", "description": "Present when status is ready or stale: fields, terms, samples, examples, notes and item_keys; for a sample_edit, sample_changes."}}, "type": "object"}, "IcpProposalApply": {"properties": {"add_terms": {"type": "array", "description": "Added terms to apply.", "items": {"type": "string"}}, "remove_terms": {"type": "array", "description": "Terms to stop.", "items": {"type": "string"}}, "fields": {"type": "array", "description": "Fields to apply as suggested.", "items": {"type": "string"}}, "field_values": {"type": "object", "description": "Field name to edited value (text, or a list or newline-separated text for list fields)."}, "term_edits": {"type": "object", "description": "Added term to reworded text."}, "sample_verdicts": {"type": "object", "description": "Sample key to 'yes' or 'no'."}, "example_keys": {"type": "array", "description": "Candidates to confirm.", "items": {"type": "string"}}, "custom_examples": {"type": "array", "description": "Company websites you typed.", "items": {"type": "string"}}}, "type": "object"}, "IcpFeedbackSummary": {"properties": {"counts": {"$ref": "#/definitions/IcpFeedbackCounts"}, "crm": {"type": "object", "description": "Companies marked from CRM deal stages (not team ratings): {like, not_a_fit}."}, "recent_ratings": {"type": "array", "description": "The 10 newest ratings: company_id, company_name, company_url, outcome (like|not_a_fit), comment, rated_at. No rater.", "items": {"type": "object"}}, "learned_rules": {"type": "object", "description": "Null until rules are written: prefer, avoid, text, generated_at, built_from."}, "regeneration": {"type": "object", "description": "new_since (ratings since the rules) and threshold."}, "usage": {"type": "object", "description": "has_ratings and has_learned_rules."}}, "type": "object"}, "IcpFeedbackCounts": {"properties": {"like": {"type": "integer", "description": "Good fit ratings, all time."}, "not_a_fit": {"type": "integer", "description": "Not a fit ratings, all time."}, "like_30d": {"type": "integer", "description": "Good fit ratings, last 30 days."}, "not_a_fit_30d": {"type": "integer", "description": "Not a fit ratings, last 30 days."}}, "type": "object"}, "IcpPurposeUpdate": {"required": ["purpose"], "properties": {"purpose": {"type": "string", "description": "find_buyers | job_intelligence"}}, "type": "object"}, "IcpPurpose": {"properties": {"purpose": {"type": "string", "description": "find_buyers (Wihyu can research your website and suggest ICP changes) or job_intelligence (Wihyu uses your ICP as written and never researches your website)."}}, "type": "object"}, "SearchTermSuggestionAccept": {"properties": {"apply_variant_ids": {"type": "array", "description": "With a require_must_contain suggestion: allowed_variant suggestion ids of the same term to accept in the same step.", "items": {"type": "integer"}}}, "type": "object"}, "SearchTermSuggestionsAccept": {"required": ["ids"], "properties": {"ids": {"type": "array", "description": "allowed_variant suggestion ids to accept together, all or nothing.", "items": {"type": "integer"}}}, "type": "object"}, "SearchTermDigestSetting": {"required": ["enabled"], "properties": {"enabled": {"type": "boolean", "description": "Receive the Monday digest."}}, "type": "object"}, "AlertSettings": {"properties": {"notifications_enabled": {"type": "boolean", "description": "Whether email alerts are enabled"}, "notification_frequency": {"type": "string", "description": "Alert frequency: daily or weekly"}, "notification_content": {"type": "string", "description": "Which companies the alert email lists", "example": "all", "enum": ["all", "no_workflow", "new_leads_only"]}}, "type": "object"}, "TermSampleSet": {"required": ["text"], "properties": {"text": {"type": "string", "description": "The job description, 60 to 20,000 characters."}}, "type": "object"}, "TermSampleUse": {"required": ["source"], "properties": {"source": {"type": "string", "description": "Which sample.", "example": "posting", "enum": ["posting", "pasted"]}, "job_id": {"type": "integer", "description": "Required when source is 'posting'."}}, "type": "object"}, "TermSampleConfirm": {"required": ["job_id"], "properties": {"job_id": {"type": "integer", "description": "A posting from the term's examples (get_term_examples)."}}, "type": "object"}, "TermSampleReject": {"required": ["job_id"], "properties": {"job_id": {"type": "integer", "description": "A posting from the term's examples (get_term_examples)."}}, "type": "object"}, "DiscordConfigure": {"required": ["channel_id"], "properties": {"channel_id": {"type": "string"}, "content_type": {"type": "string", "description": "all (default) | no_workflow | new_leads_only"}}, "type": "object"}, "DiscordConnection": {"properties": {"configured": {"type": "boolean", "description": "Wihyu's Discord app is set up."}, "connected": {"type": "boolean"}, "guild_id": {"type": "string"}, "guild_name": {"type": "string"}, "channel_id": {"type": "string"}, "channel_name": {"type": "string"}, "content_type": {"type": "string", "description": "all | no_workflow | new_leads_only"}, "last_error": {"type": "string", "description": "Why the last post failed; cleared by the next success."}, "last_error_at": {"type": "string", "description": "ISO 8601."}}, "type": "object"}, "DiscordInstallUrl": {"properties": {"url": {"type": "string", "description": "Open in a browser to add the Wihyu bot."}, "expires_at": {"type": "string", "description": "ISO 8601; valid 15 minutes."}}, "type": "object"}, "DiscordChannels": {"properties": {"channels": {"type": "array", "description": "[{id, name, type}] in server order.", "items": {"type": "object"}}}, "type": "object"}, "ChatLinkConfirm": {"required": ["token"], "properties": {"token": {"type": "string", "description": "Token from the chat Link account link."}, "replace": {"type": "boolean", "description": "Take over a chat account linked to another user."}}, "type": "object"}, "ChatLinks": {"properties": {"links": {"type": "array", "items": {"$ref": "#/definitions/ChatLink"}}}, "type": "object"}, "ChatLink": {"properties": {"id": {"type": "integer"}, "user_id": {"type": "integer"}, "user_email": {"type": "string"}, "platform": {"type": "string", "description": "slack | discord"}, "workspace_id": {"type": "string", "description": "Slack team id / Discord server id."}, "chat_user_id": {"type": "string"}, "chat_display_name": {"type": "string"}, "created_at": {"type": "string", "description": "ISO 8601."}}, "type": "object"}, "SlackConfigure": {"properties": {"content_type": {"type": "string", "description": "all (default) | no_workflow | new_leads_only"}}, "type": "object"}, "SlackConnection": {"properties": {"configured": {"type": "boolean", "description": "Wihyu's Slack app is set up."}, "connected": {"type": "boolean"}, "team_id": {"type": "string"}, "team_name": {"type": "string"}, "channel_id": {"type": "string"}, "channel_name": {"type": "string"}, "content_type": {"type": "string", "description": "all | no_workflow | new_leads_only"}}, "type": "object"}, "SlackInstallUrl": {"properties": {"url": {"type": "string", "description": "Open in a browser to add Wihyu to Slack."}, "expires_at": {"type": "string", "description": "ISO 8601; valid 15 minutes."}}, "type": "object"}, "HubSpotConnection": {"properties": {"configured": {"type": "boolean", "description": "Wihyu's HubSpot app is set up."}, "connected": {"type": "boolean"}, "portal_id": {"type": "object", "description": "HubSpot portal id when connected."}, "error_code": {"type": "string", "description": "HubSpot error code, if any."}, "message": {"type": "string"}, "needs_reauthorization": {"type": "boolean", "description": "The saved token is invalid; run the install again."}, "sync_stats": {"description": "Null unless connected.", "allOf": [{"$ref": "#/definitions/HubSpotSyncStats"}]}}, "type": "object"}, "HubSpotSyncStats": {"properties": {"total_companies": {"type": "integer"}, "hubspot_linked_companies": {"type": "integer"}, "hubspot_distinct_records": {"type": "integer"}, "last_sync_completed_at": {"type": "string", "description": "ISO 8601 or null."}, "last_sync_duration_seconds": {"type": "number"}, "last_sync_error_count": {"type": "integer"}}, "type": "object"}, "HubSpotInstallUrl": {"properties": {"url": {"type": "string", "description": "Open in a browser while signed in to Wihyu as the same user."}, "expires_at": {"type": "string", "description": "ISO 8601; valid 15 minutes."}}, "type": "object"}, "ApiKeyCreate": {"properties": {"owner_type": {"type": "string", "description": "user (default; acts as you) | account (admins only)."}, "name": {"type": "string"}, "scopes": {"type": "array", "description": "Default: every scope you hold except api_keys:manage. Only an admin signed in to the web app or using OAuth may add api_keys:manage.", "items": {"type": "string"}}, "expires_at": {"type": "string", "description": "ISO 8601 in the future. A key that expires can only create keys that expire no later."}}, "type": "object"}, "ApiKeys": {"properties": {"keys": {"type": "array", "items": {"$ref": "#/definitions/ApiKey"}}}, "type": "object"}, "ApiKey": {"properties": {"id": {"type": "integer"}, "name": {"type": "string"}, "owner_type": {"type": "string", "description": "user | account"}, "user_id": {"type": "integer"}, "key_prefix": {"type": "string", "description": "First characters, for recognition."}, "scopes": {"type": "array", "items": {"type": "string"}}, "created_at": {"type": "string", "description": "ISO 8601."}, "last_used_at": {"type": "string", "description": "ISO 8601 or null."}, "expires_at": {"type": "string", "description": "ISO 8601 or null."}, "revoked_at": {"type": "string", "description": "ISO 8601 or null."}, "rotated_from_id": {"type": "integer"}, "active": {"type": "boolean", "description": "Not revoked and not expired."}}, "type": "object"}, "ApiKeyWithSecret": {"properties": {"id": {"type": "integer"}, "name": {"type": "string"}, "owner_type": {"type": "string", "description": "user | account"}, "user_id": {"type": "integer"}, "key_prefix": {"type": "string", "description": "First characters, for recognition."}, "scopes": {"type": "array", "items": {"type": "string"}}, "created_at": {"type": "string", "description": "ISO 8601."}, "last_used_at": {"type": "string", "description": "ISO 8601 or null."}, "expires_at": {"type": "string", "description": "ISO 8601 or null."}, "revoked_at": {"type": "string", "description": "ISO 8601 or null."}, "rotated_from_id": {"type": "integer"}, "active": {"type": "boolean", "description": "Not revoked and not expired."}, "raw_key": {"type": "string", "description": "The key itself. Shown only in this response; store it now."}}, "type": "object"}}, "responses": {"ParseError": {"description": "When a mask can't be parsed"}, "MaskError": {"description": "When any error occurs on mask"}}}
