{"openapi":"3.1.0","info":{"title":"Stalkr Agent API","version":"2026-08-24","description":"The same project-scoped capabilities used by Stalkr's dashboard and MCP server.","termsOfService":"https://www.stalkr.ai/terms"},"servers":[{"url":"https://www.stalkr.ai/api/v1","description":"Production"}],"paths":{"/projects":{"get":{"operationId":"list_projects","summary":"List projects","description":"List every active project the authenticated user owns or has been invited to.","tags":["projects"],"security":[{"BearerAuth":[]}],"parameters":[],"x-mcp-tool":"list_projects","x-required-scope":"projects:read","x-tool-annotations":{"readOnlyHint":true,"destructiveHint":false,"openWorldHint":false},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}},"post":{"operationId":"create_project","summary":"Create project","description":"Create a new monitoring project with Daily Digest enabled at 8 AM in digestTimezone (UTC by default), within workspace limits. Digests email the workspace owner and can be disabled or deleted through alerts.","tags":["projects"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"8-128 character retry key. Strongly recommended for writes.","schema":{"type":"string","minLength":8,"maxLength":128}}],"x-mcp-tool":"create_project","x-required-scope":"projects:write","x-tool-annotations":{"readOnlyHint":false,"destructiveHint":false,"openWorldHint":true},"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"digestTimezone":{"default":"UTC","description":"Timezone for the automatic 8 AM daily digest; defaults to UTC","type":"string","maxLength":100},"name":{"type":"string","minLength":1,"maxLength":100},"description":{"default":"","type":"string","maxLength":500},"color":{"default":"#7e47eb","type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"icon":{"default":"📡","type":"string","maxLength":10},"enabledSources":{"default":["x","reddit","youtube","linkedin"],"type":"array","items":{"type":"string","enum":["x","reddit","youtube","linkedin"]}}},"required":["digestTimezone","name","description","color","icon","enabledSources"],"additionalProperties":false}}}}}},"/projects/{projectId}":{"get":{"operationId":"get_project","summary":"Get project","description":"Get one project and the authenticated user's role in it.","tags":["projects"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"x-mcp-tool":"get_project","x-required-scope":"projects:read","x-tool-annotations":{"readOnlyHint":true,"destructiveHint":false,"openWorldHint":false},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}},"patch":{"operationId":"update_project","summary":"Update project","description":"Update project details or status. Only owners can pause or resume a project. Use delete_project for permanent deletion.","tags":["projects"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"description":"8-128 character retry key. Strongly recommended for writes.","schema":{"type":"string","minLength":8,"maxLength":128}}],"x-mcp-tool":"update_project","x-required-scope":"projects:write","x-tool-annotations":{"readOnlyHint":false,"destructiveHint":false,"openWorldHint":false},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","maxLength":500},"color":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"icon":{"type":"string","maxLength":10},"enabledSources":{"type":"array","items":{"type":"string","enum":["x","reddit","youtube","linkedin"]}},"status":{"type":"string","enum":["active","paused"]}},"additionalProperties":false}}}}},"delete":{"operationId":"delete_project","summary":"Delete project","description":"Delete a project, its keywords, settings, and shared access. Retains stored mentions and their snapshots privately for support recovery; they disappear from the dashboard and API. Before calling, tell the user which project will be deleted and these consequences, ask for explicit confirmation, and wait for their answer. Only then supply confirmDeletion: true and the exact current project name as confirmationName. Never infer confirmation from knowing the name. Requires owner access. Frees keyword slots; preserves consumed monthly/trial mention usage and all billing/provider allowances. Emits project.deleted to workspace webhooks. There is no self-service undo.","tags":["projects"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"description":"8-128 character retry key. Strongly recommended for writes.","schema":{"type":"string","minLength":8,"maxLength":128}}],"x-mcp-tool":"delete_project","x-required-scope":"projects:write","x-tool-annotations":{"readOnlyHint":false,"destructiveHint":true,"openWorldHint":true},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"confirmationName":{"type":"string","minLength":1,"maxLength":100,"description":"Exact current project name confirmed by the user. Keyword slots are freed; mention history and consumed mention usage are preserved."},"confirmDeletion":{"type":"boolean","const":true,"description":"Required explicit confirmation. Set true only after the user confirms deleting this specific project after being told the consequences. Never infer consent from knowing the project name."}},"required":["confirmationName","confirmDeletion"],"additionalProperties":false}}}}}},"/projects/{projectId}/public-dashboard":{"get":{"operationId":"get_public_dashboard","summary":"Get public dashboard settings","description":"Get the owner-only publication state and share URL for a project dashboard.","tags":["projects"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"x-mcp-tool":"get_public_dashboard","x-required-scope":"projects:read","x-tool-annotations":{"readOnlyHint":true,"destructiveHint":false,"openWorldHint":false},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}},"patch":{"operationId":"set_public_dashboard","summary":"Set public dashboard access","description":"Publish or disable a project's read-only Mentions and Analytics dashboard, with an optional public description and website link. Its share URL is assigned once and remains reserved when disabled.","tags":["projects"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"description":"8-128 character retry key. Strongly recommended for writes.","schema":{"type":"string","minLength":8,"maxLength":128}}],"x-mcp-tool":"set_public_dashboard","x-required-scope":"projects:write","x-tool-annotations":{"readOnlyHint":false,"destructiveHint":false,"openWorldHint":true},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"},"description":{"type":"string","maxLength":160},"websiteUrl":{"type":"string","maxLength":2048,"description":"Optional public HTTP or HTTPS website URL"}},"required":["enabled"],"additionalProperties":false}}}}}},"/projects/{projectId}/members":{"get":{"operationId":"list_project_members","summary":"List project members","description":"List project members and, for owners, pending invitations.","tags":["projects"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"x-mcp-tool":"list_project_members","x-required-scope":"projects:read","x-tool-annotations":{"readOnlyHint":true,"destructiveHint":false,"openWorldHint":false},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}},"post":{"operationId":"invite_project_member","summary":"Invite project member","description":"Email a time-limited project invitation. Only owners can invite and the existing seat and email rate limits apply.","tags":["projects"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"description":"8-128 character retry key. Strongly recommended for writes.","schema":{"type":"string","minLength":8,"maxLength":128}}],"x-mcp-tool":"invite_project_member","x-required-scope":"projects:write","x-tool-annotations":{"readOnlyHint":false,"destructiveHint":false,"openWorldHint":true},"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{},"role":{"default":"viewer","type":"string","enum":["viewer","editor"]}},"required":["email","role"],"additionalProperties":false}}}}}},"/projects/{projectId}/members/{memberId}":{"patch":{"operationId":"update_project_member","summary":"Update project member","description":"Change a member or pending invite role. Only the project owner can do this.","tags":["projects"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"memberId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"description":"8-128 character retry key. Strongly recommended for writes.","schema":{"type":"string","minLength":8,"maxLength":128}}],"x-mcp-tool":"update_project_member","x-required-scope":"projects:write","x-tool-annotations":{"readOnlyHint":false,"destructiveHint":false,"openWorldHint":false},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"role":{"type":"string","enum":["viewer","editor"]},"memberType":{"default":"member","type":"string","enum":["member","invite"]}},"required":["role","memberType"],"additionalProperties":false}}}}},"delete":{"operationId":"remove_project_member","summary":"Remove project member","description":"Remove a member or revoke a pending project invite.","tags":["projects"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"memberId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"description":"8-128 character retry key. Strongly recommended for writes.","schema":{"type":"string","minLength":8,"maxLength":128}}],"x-mcp-tool":"remove_project_member","x-required-scope":"projects:write","x-tool-annotations":{"readOnlyHint":false,"destructiveHint":true,"openWorldHint":false},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"memberType":{"default":"member","type":"string","enum":["member","invite"]}},"required":["memberType"],"additionalProperties":false}}}}}},"/keywords":{"get":{"operationId":"list_keywords","summary":"List keywords","description":"List tracked keywords for one project or all accessible active projects.","tags":["keywords"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"projectId","in":"query","required":false,"schema":{"type":"string"}},{"name":"active","in":"query","required":false,"schema":{"type":"boolean"}}],"x-mcp-tool":"list_keywords","x-required-scope":"keywords:read","x-tool-annotations":{"readOnlyHint":true,"destructiveHint":false,"openWorldHint":false},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}},"post":{"operationId":"create_keyword","summary":"Create keyword","description":"Create a tracked keyword in My brand or a specified keyword group. Existing workspace keyword limits are enforced.","tags":["keywords"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"8-128 character retry key. Strongly recommended for writes.","schema":{"type":"string","minLength":8,"maxLength":128}}],"x-mcp-tool":"create_keyword","x-required-scope":"keywords:write","x-tool-annotations":{"readOnlyHint":false,"destructiveHint":false,"openWorldHint":true},"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"projectId":{"type":"string","minLength":1},"groupId":{"description":"Keyword group to assign; defaults to the project's My brand group","type":"string","minLength":1},"value":{"type":"string","minLength":3,"maxLength":200},"sources":{"default":["x","reddit","youtube","linkedin"],"minItems":1,"type":"array","items":{"type":"string","enum":["x","reddit","youtube","linkedin"]}},"aliases":{"default":[],"maxItems":10,"type":"array","items":{"type":"string","maxLength":200}},"excludedTerms":{"default":[],"maxItems":10,"type":"array","items":{"type":"string","maxLength":200}},"filters":{},"caseSensitive":{"default":false,"type":"boolean"}},"required":["projectId","value","sources","aliases","excludedTerms","filters","caseSensitive"],"additionalProperties":false}}}}}},"/keywords/{keywordId}":{"patch":{"operationId":"update_keyword","summary":"Update keyword","description":"Update keyword text, sources, filters, group assignment, or active state.","tags":["keywords"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"keywordId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"description":"8-128 character retry key. Strongly recommended for writes.","schema":{"type":"string","minLength":8,"maxLength":128}}],"x-mcp-tool":"update_keyword","x-required-scope":"keywords:write","x-tool-annotations":{"readOnlyHint":false,"destructiveHint":false,"openWorldHint":true},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"groupId":{"description":"Move the keyword into this keyword group","type":"string","minLength":1},"value":{"type":"string","minLength":3,"maxLength":200},"sources":{"minItems":1,"type":"array","items":{"type":"string","enum":["x","reddit","youtube","linkedin"]}},"aliases":{"maxItems":10,"type":"array","items":{"type":"string","maxLength":200}},"excludedTerms":{"maxItems":10,"type":"array","items":{"type":"string","maxLength":200}},"filters":{},"caseSensitive":{"type":"boolean"},"active":{"type":"boolean"}},"additionalProperties":false}}}}},"delete":{"operationId":"delete_keyword","summary":"Stop tracking keyword","description":"Deactivate a tracked keyword without deleting its historical mentions.","tags":["keywords"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"keywordId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"description":"8-128 character retry key. Strongly recommended for writes.","schema":{"type":"string","minLength":8,"maxLength":128}}],"x-mcp-tool":"delete_keyword","x-required-scope":"keywords:write","x-tool-annotations":{"readOnlyHint":false,"destructiveHint":true,"openWorldHint":true},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/keyword-groups":{"get":{"operationId":"list_keyword_groups","summary":"List keyword groups","description":"List reusable brand, competitor, and custom keyword groups.","tags":["keywords"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"projectId","in":"query","required":false,"schema":{"type":"string"}}],"x-mcp-tool":"list_keyword_groups","x-required-scope":"keywords:read","x-tool-annotations":{"readOnlyHint":true,"destructiveHint":false,"openWorldHint":false},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}},"post":{"operationId":"create_keyword_group","summary":"Create keyword group","description":"Create a custom keyword group inside an editable project. The total group allowance, including My brand and Competitors, equals the workspace keyword allowance.","tags":["keywords"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"8-128 character retry key. Strongly recommended for writes.","schema":{"type":"string","minLength":8,"maxLength":128}}],"x-mcp-tool":"create_keyword_group","x-required-scope":"keywords:write","x-tool-annotations":{"readOnlyHint":false,"destructiveHint":false,"openWorldHint":false},"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"projectId":{"type":"string","minLength":1,"description":"Project that owns the keyword group"},"name":{"type":"string","minLength":1,"maxLength":60,"description":"Reusable keyword group name"}},"required":["projectId","name"],"additionalProperties":false}}}}}},"/keyword-groups/{groupId}":{"patch":{"operationId":"update_keyword_group","summary":"Update keyword group","description":"Rename or reorder a custom keyword group. Default group names are fixed.","tags":["keywords"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"groupId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"description":"8-128 character retry key. Strongly recommended for writes.","schema":{"type":"string","minLength":8,"maxLength":128}}],"x-mcp-tool":"update_keyword_group","x-required-scope":"keywords:write","x-tool-annotations":{"readOnlyHint":false,"destructiveHint":false,"openWorldHint":false},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60},"order":{"type":"integer","minimum":0,"maximum":100}},"additionalProperties":false}}}}},"delete":{"operationId":"delete_keyword_group","summary":"Delete keyword group","description":"Delete an unused custom keyword group. Default groups are fixed and cannot be deleted.","tags":["keywords"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"groupId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"description":"8-128 character retry key. Strongly recommended for writes.","schema":{"type":"string","minLength":8,"maxLength":128}}],"x-mcp-tool":"delete_keyword_group","x-required-scope":"keywords:write","x-tool-annotations":{"readOnlyHint":false,"destructiveHint":true,"openWorldHint":false},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/mention-authors":{"get":{"operationId":"search_mention_authors","summary":"Search mentioning accounts","description":"Autocomplete accounts that mentioned a brand by partial display name or handle, including their network, avatar, and mention count.","tags":["mentions"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"projectId","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"Project whose mentioning accounts to search"}},{"name":"q","in":"query","required":true,"schema":{"default":"","description":"Partial display name or handle; omit to return the top accounts","type":"string","maxLength":100}},{"name":"limit","in":"query","required":true,"schema":{"default":8,"type":"integer","minimum":1,"maximum":20}}],"x-mcp-tool":"search_mention_authors","x-required-scope":"mentions:read","x-tool-annotations":{"readOnlyHint":true,"destructiveHint":false,"openWorldHint":false},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/mentions":{"get":{"operationId":"list_mentions","summary":"List mentions","description":"Search and paginate mentions across accessible projects with the same filters as the dashboard, including an exact From author and stored quoted-post context when available. Each source post appears once per project across matching keywords; X edits update the same mention without consuming another mention. Separate replies and quote posts remain distinct.","tags":["mentions"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"projectId","in":"query","required":false,"schema":{"type":"string"}},{"name":"source","in":"query","required":false,"schema":{"type":"string","enum":["x","reddit","youtube","linkedin"]}},{"name":"fromSource","in":"query","required":false,"schema":{"description":"Network for an exact author filter","type":"string","enum":["x","reddit","youtube","linkedin"]}},{"name":"fromHandle","in":"query","required":false,"schema":{"description":"Exact author handle, without or with a leading @","type":"string","maxLength":200}},{"name":"fromName","in":"query","required":false,"schema":{"description":"Exact author display name, used when no handle is available","type":"string","maxLength":200}},{"name":"fromProfileUrl","in":"query","required":false,"schema":{"description":"Exact author profile URL fallback when no handle is available","type":"string","maxLength":2048}},{"name":"keywordId","in":"query","required":false,"schema":{"type":"string"}},{"name":"keywordIds","in":"query","required":false,"schema":{"type":"string","maxLength":5000}},{"name":"keywordGroupIds","in":"query","required":false,"schema":{"description":"Comma-separated keyword group IDs; matches keywords currently in any selected group","type":"string","maxLength":5000}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["open","done","follow_up"]}},{"name":"sentiment","in":"query","required":false,"schema":{"type":"string","enum":["positive","neutral","negative"]}},{"name":"categoryId","in":"query","required":false,"schema":{"type":"string"}},{"name":"urgencyMin","in":"query","required":false,"schema":{"type":"number","minimum":0,"maximum":100}},{"name":"urgencyMax","in":"query","required":false,"schema":{"type":"number","minimum":0,"maximum":100}},{"name":"search","in":"query","required":false,"schema":{"type":"string","maxLength":200}},{"name":"engagement","in":"query","required":false,"schema":{"type":"string","maxLength":500}},{"name":"dateFrom","in":"query","required":false,"schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},{"name":"dateTo","in":"query","required":false,"schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},{"name":"sort","in":"query","required":true,"schema":{"default":"createdAtSource","type":"string","enum":["createdAtSource","urgencyScore","engagement"]}},{"name":"direction","in":"query","required":true,"schema":{"default":"desc","type":"string","enum":["asc","desc"]}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":true,"schema":{"default":25,"type":"integer","minimum":1,"maximum":100}},{"name":"tzOffset","in":"query","required":true,"schema":{"default":0,"type":"integer","minimum":-840,"maximum":840}}],"x-mcp-tool":"list_mentions","x-required-scope":"mentions:read","x-tool-annotations":{"readOnlyHint":true,"destructiveHint":false,"openWorldHint":false},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/mentions/{mentionId}":{"get":{"operationId":"get_mention","summary":"Get mention","description":"Get one source-compliant mention from an accessible project, including stored quoted-post context when available.","tags":["mentions"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"mentionId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"x-mcp-tool":"get_mention","x-required-scope":"mentions:read","x-tool-annotations":{"readOnlyHint":true,"destructiveHint":false,"openWorldHint":false},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}},"patch":{"operationId":"update_mention_status","summary":"Update mention status","description":"Mark a mention open, done, or needing follow-up.","tags":["mentions"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"mentionId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"description":"8-128 character retry key. Strongly recommended for writes.","schema":{"type":"string","minLength":8,"maxLength":128}}],"x-mcp-tool":"update_mention_status","x-required-scope":"mentions:write","x-tool-annotations":{"readOnlyHint":false,"destructiveHint":false,"openWorldHint":false},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["open","done","follow_up"]}},"required":["status"],"additionalProperties":false}}}}}},"/mentions/{mentionId}/irrelevant":{"post":{"operationId":"mark_mention_irrelevant","summary":"Mark mention irrelevant","description":"Permanently remove an irrelevant mention from its project, optionally preserve context as relevance feedback, and prevent re-ingestion. Removal has no daily cap and remains available when the mention allowance is exhausted.","tags":["mentions"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"mentionId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"description":"8-128 character retry key. Strongly recommended for writes.","schema":{"type":"string","minLength":8,"maxLength":128}}],"x-mcp-tool":"mark_mention_irrelevant","x-required-scope":"mentions:write","x-tool-annotations":{"readOnlyHint":false,"destructiveHint":true,"openWorldHint":false},"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":1000,"description":"Optional context about why this mention does not belong to the project; used as relevance feedback"}},"additionalProperties":false}}}}}},"/analytics/mentions":{"get":{"operationId":"get_mention_analytics","summary":"Get mention analytics","description":"Read a five-minute cached analytics snapshot, including keyword-group mention share and top positive and negative authors, for one accessible project using the dashboard's mention filters.","tags":["mentions"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"projectId","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"Project to analyze"}},{"name":"source","in":"query","required":false,"schema":{"type":"string","enum":["x","reddit","youtube","linkedin"]}},{"name":"fromSource","in":"query","required":false,"schema":{"description":"Network for an exact author filter","type":"string","enum":["x","reddit","youtube","linkedin"]}},{"name":"fromHandle","in":"query","required":false,"schema":{"description":"Exact author handle, without or with a leading @","type":"string","maxLength":200}},{"name":"fromName","in":"query","required":false,"schema":{"description":"Exact author display name, used when no handle is available","type":"string","maxLength":200}},{"name":"fromProfileUrl","in":"query","required":false,"schema":{"description":"Exact author profile URL fallback when no handle is available","type":"string","maxLength":2048}},{"name":"keywordId","in":"query","required":false,"schema":{"type":"string"}},{"name":"keywordIds","in":"query","required":false,"schema":{"type":"string","maxLength":5000}},{"name":"keywordGroupIds","in":"query","required":false,"schema":{"description":"Comma-separated keyword group IDs; matches keywords currently in any selected group","type":"string","maxLength":5000}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["open","done","follow_up"]}},{"name":"sentiment","in":"query","required":false,"schema":{"type":"string","enum":["positive","neutral","negative"]}},{"name":"categoryId","in":"query","required":false,"schema":{"type":"string"}},{"name":"urgencyMin","in":"query","required":false,"schema":{"type":"number","minimum":0,"maximum":100}},{"name":"urgencyMax","in":"query","required":false,"schema":{"type":"number","minimum":0,"maximum":100}},{"name":"search","in":"query","required":false,"schema":{"type":"string","maxLength":200}},{"name":"engagement","in":"query","required":false,"schema":{"type":"string","maxLength":500}},{"name":"dateFrom","in":"query","required":false,"schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},{"name":"dateTo","in":"query","required":false,"schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},{"name":"datePreset","in":"query","required":false,"schema":{"description":"Optional dashboard date preset; all_time disables the 30-day default","type":"string","enum":["today","last_7_days","last_30_days","last_4_weeks","last_6_months","last_12_months","month_to_date","quarter_to_date","year_to_date","all_time","custom"]}},{"name":"tzOffset","in":"query","required":true,"schema":{"default":0,"description":"Browser timezone offset in minutes, as returned by Date.getTimezoneOffset","type":"integer","minimum":-840,"maximum":840}}],"x-mcp-tool":"get_mention_analytics","x-required-scope":"mentions:read","x-tool-annotations":{"readOnlyHint":true,"destructiveHint":false,"openWorldHint":false},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/categories":{"get":{"operationId":"list_categories","summary":"List categories","description":"List mention categories for one project or every accessible project.","tags":["mentions"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"projectId","in":"query","required":false,"schema":{"type":"string"}}],"x-mcp-tool":"list_categories","x-required-scope":"mentions:read","x-tool-annotations":{"readOnlyHint":true,"destructiveHint":false,"openWorldHint":false},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}},"post":{"operationId":"create_category","summary":"Create category","description":"Create a category in a project the user can edit.","tags":["mentions"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"8-128 character retry key. Strongly recommended for writes.","schema":{"type":"string","minLength":8,"maxLength":128}}],"x-mcp-tool":"create_category","x-required-scope":"mentions:write","x-tool-annotations":{"readOnlyHint":false,"destructiveHint":false,"openWorldHint":false},"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"projectId":{"type":"string","minLength":1},"name":{"type":"string","minLength":1,"maxLength":60},"description":{"default":"","type":"string","maxLength":280},"icon":{"type":"string","minLength":1,"maxLength":60},"order":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["projectId","name","description","icon"],"additionalProperties":false}}}}}},"/categories/{categoryId}":{"patch":{"operationId":"update_category","summary":"Update category","description":"Update a mention category.","tags":["mentions"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"categoryId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"description":"8-128 character retry key. Strongly recommended for writes.","schema":{"type":"string","minLength":8,"maxLength":128}}],"x-mcp-tool":"update_category","x-required-scope":"mentions:write","x-tool-annotations":{"readOnlyHint":false,"destructiveHint":false,"openWorldHint":false},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60},"description":{"type":"string","maxLength":280},"icon":{"type":"string","minLength":1,"maxLength":60},"order":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"additionalProperties":false}}}}},"delete":{"operationId":"delete_category","summary":"Delete category","description":"Delete a category. Existing mentions become uncategorized.","tags":["mentions"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"categoryId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"description":"8-128 character retry key. Strongly recommended for writes.","schema":{"type":"string","minLength":8,"maxLength":128}}],"x-mcp-tool":"delete_category","x-required-scope":"mentions:write","x-tool-annotations":{"readOnlyHint":false,"destructiveHint":true,"openWorldHint":false},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/mention-views":{"get":{"operationId":"list_mention_views","summary":"List saved mention views","description":"List saved mention filter presets.","tags":["mentions"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"projectId","in":"query","required":false,"schema":{"type":"string"}}],"x-mcp-tool":"list_mention_views","x-required-scope":"mentions:read","x-tool-annotations":{"readOnlyHint":true,"destructiveHint":false,"openWorldHint":false},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}},"post":{"operationId":"create_mention_view","summary":"Create saved mention view","description":"Save a mention filter preset.","tags":["mentions"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"8-128 character retry key. Strongly recommended for writes.","schema":{"type":"string","minLength":8,"maxLength":128}}],"x-mcp-tool":"create_mention_view","x-required-scope":"mentions:write","x-tool-annotations":{"readOnlyHint":false,"destructiveHint":false,"openWorldHint":false},"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"projectId":{"type":"string","minLength":1},"name":{"type":"string","minLength":1,"maxLength":60},"filters":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"order":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["projectId","name","filters"],"additionalProperties":false}}}}}},"/mention-views/{viewId}":{"patch":{"operationId":"update_mention_view","summary":"Update saved mention view","description":"Update a saved mention filter preset.","tags":["mentions"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"viewId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"description":"8-128 character retry key. Strongly recommended for writes.","schema":{"type":"string","minLength":8,"maxLength":128}}],"x-mcp-tool":"update_mention_view","x-required-scope":"mentions:write","x-tool-annotations":{"readOnlyHint":false,"destructiveHint":false,"openWorldHint":false},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60},"filters":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"order":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"additionalProperties":false}}}}},"delete":{"operationId":"delete_mention_view","summary":"Delete saved mention view","description":"Delete a saved mention filter preset.","tags":["mentions"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"viewId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"description":"8-128 character retry key. Strongly recommended for writes.","schema":{"type":"string","minLength":8,"maxLength":128}}],"x-mcp-tool":"delete_mention_view","x-required-scope":"mentions:write","x-tool-annotations":{"readOnlyHint":false,"destructiveHint":true,"openWorldHint":false},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/alerts":{"get":{"operationId":"list_alerts","summary":"List alerts","description":"List alert rules, the workspace-owner email recipient, and the shared daily email limit for the workspace or an accessible project.","tags":["alerts"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"projectId","in":"query","required":false,"schema":{"type":"string"}}],"x-mcp-tool":"list_alerts","x-required-scope":"alerts:read","x-tool-annotations":{"readOnlyHint":true,"destructiveHint":false,"openWorldHint":false},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}},"post":{"operationId":"create_alert","summary":"Create alert","description":"Create an email alert rule targeting keyword groups, individual keywords, or one exact mentioning account, while enforcing the workspace alert cap and owner-only recipient policy. No separate email verification is required. Digests and custom alerts share a daily limit of 3 emails for trial workspaces and 30 for paid workspaces, resetting at midnight UTC.","tags":["alerts"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"8-128 character retry key. Strongly recommended for writes.","schema":{"type":"string","minLength":8,"maxLength":128}}],"x-mcp-tool":"create_alert","x-required-scope":"alerts:write","x-tool-annotations":{"readOnlyHint":false,"destructiveHint":false,"openWorldHint":true},"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"projectId":{"default":null,"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"type":"string","minLength":1,"maxLength":80},"type":{"type":"string","enum":["digest","custom"]},"active":{"default":true,"type":"boolean"},"channels":{"minItems":1,"maxItems":1,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"email"},"config":{"default":{},"type":"object","properties":{"recipients":{"maxItems":1,"type":"array","items":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}}},"additionalProperties":false}},"required":["type","config"],"additionalProperties":false},"description":"Exactly one email channel; Stalkr delivers alerts only to the workspace owner"},"digest":{"type":"object","properties":{"sendHour":{"type":"integer","minimum":0,"maximum":23},"timezone":{"type":"string","minLength":1,"maxLength":80},"sources":{"default":[],"type":"array","items":{"type":"string","enum":["x","reddit","youtube","linkedin"]}},"allKeywords":{"default":false,"type":"boolean"},"keywordIds":{"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":64}},"keywordGroupIds":{"description":"Keyword groups whose current keywords should be included in the digest","maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":64}}},"required":["sendHour","timezone","sources","allKeywords"],"additionalProperties":false},"filters":{"type":"object","properties":{"sources":{"type":"array","items":{"type":"string","enum":["x","reddit","youtube","linkedin"]}},"sentiments":{"type":"array","items":{"type":"string","enum":["positive","neutral","negative"]}},"categoryIds":{"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":64}},"keywordIds":{"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":64}},"keywordGroupIds":{"description":"Keyword groups whose current keywords can trigger the alert","maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":64}},"minUrgency":{"type":"integer","minimum":0,"maximum":100},"author":{"description":"Exact account whose mentions should trigger this alert","type":"object","properties":{"source":{"type":"string","enum":["x","reddit","youtube","linkedin"]},"handle":{"default":"","type":"string","maxLength":200},"name":{"default":"","type":"string","maxLength":200},"avatarUrl":{"default":null,"anyOf":[{"type":"string","maxLength":2048,"format":"uri"},{"type":"null"}]},"profileUrl":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","maxLength":2048,"format":"uri"}]}},"required":["source","handle","name","avatarUrl","profileUrl"],"additionalProperties":false},"engagement":{"type":"object","propertyNames":{"type":"string","enum":["x","reddit","youtube","linkedin"]},"additionalProperties":{"type":"object","properties":{"metric":{"type":"string","maxLength":40},"min":{"type":"number","minimum":0}},"additionalProperties":false}}},"additionalProperties":false}},"required":["projectId","name","type","active","channels"],"additionalProperties":false}}}}}},"/alerts/{alertId}":{"patch":{"operationId":"update_alert","summary":"Update alert","description":"Update an alert rule, including its keyword-group and individual-keyword targets.","tags":["alerts"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"alertId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"description":"8-128 character retry key. Strongly recommended for writes.","schema":{"type":"string","minLength":8,"maxLength":128}}],"x-mcp-tool":"update_alert","x-required-scope":"alerts:write","x-tool-annotations":{"readOnlyHint":false,"destructiveHint":false,"openWorldHint":true},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"active":{"type":"boolean"},"channels":{"minItems":1,"maxItems":1,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"email"},"config":{"default":{},"type":"object","properties":{"recipients":{"maxItems":1,"type":"array","items":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}}},"additionalProperties":false}},"required":["type","config"],"additionalProperties":false},"description":"Exactly one email channel; Stalkr delivers alerts only to the workspace owner"},"digest":{"type":"object","properties":{"sendHour":{"type":"integer","minimum":0,"maximum":23},"timezone":{"type":"string","minLength":1,"maxLength":80},"sources":{"default":[],"type":"array","items":{"type":"string","enum":["x","reddit","youtube","linkedin"]}},"allKeywords":{"default":false,"type":"boolean"},"keywordIds":{"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":64}},"keywordGroupIds":{"description":"Keyword groups whose current keywords should be included in the digest","maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":64}}},"required":["sendHour","timezone","sources","allKeywords"],"additionalProperties":false},"filters":{"type":"object","properties":{"sources":{"type":"array","items":{"type":"string","enum":["x","reddit","youtube","linkedin"]}},"sentiments":{"type":"array","items":{"type":"string","enum":["positive","neutral","negative"]}},"categoryIds":{"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":64}},"keywordIds":{"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":64}},"keywordGroupIds":{"description":"Keyword groups whose current keywords can trigger the alert","maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":64}},"minUrgency":{"type":"integer","minimum":0,"maximum":100},"author":{"description":"Exact account whose mentions should trigger this alert","type":"object","properties":{"source":{"type":"string","enum":["x","reddit","youtube","linkedin"]},"handle":{"default":"","type":"string","maxLength":200},"name":{"default":"","type":"string","maxLength":200},"avatarUrl":{"default":null,"anyOf":[{"type":"string","maxLength":2048,"format":"uri"},{"type":"null"}]},"profileUrl":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","maxLength":2048,"format":"uri"}]}},"required":["source","handle","name","avatarUrl","profileUrl"],"additionalProperties":false},"engagement":{"type":"object","propertyNames":{"type":"string","enum":["x","reddit","youtube","linkedin"]},"additionalProperties":{"type":"object","properties":{"metric":{"type":"string","maxLength":40},"min":{"type":"number","minimum":0}},"additionalProperties":false}}},"additionalProperties":false}},"additionalProperties":false}}}}},"delete":{"operationId":"delete_alert","summary":"Delete alert","description":"Delete an alert rule.","tags":["alerts"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"alertId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"description":"8-128 character retry key. Strongly recommended for writes.","schema":{"type":"string","minLength":8,"maxLength":128}}],"x-mcp-tool":"delete_alert","x-required-scope":"alerts:write","x-tool-annotations":{"readOnlyHint":false,"destructiveHint":true,"openWorldHint":true},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/integrations/linkedin":{"get":{"operationId":"get_linkedin_integration","summary":"Get LinkedIn integration","description":"Get LinkedIn Page connection status and available Page choices for a project.","tags":["integrations"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"projectId","in":"query","required":true,"schema":{"type":"string","minLength":1}}],"x-mcp-tool":"get_linkedin_integration","x-required-scope":"integrations:read","x-tool-annotations":{"readOnlyHint":true,"destructiveHint":false,"openWorldHint":false},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}},"patch":{"operationId":"select_linkedin_page","summary":"Select LinkedIn Page","description":"Choose a Page after LinkedIn authorization.","tags":["integrations"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"8-128 character retry key. Strongly recommended for writes.","schema":{"type":"string","minLength":8,"maxLength":128}}],"x-mcp-tool":"select_linkedin_page","x-required-scope":"integrations:write","x-tool-annotations":{"readOnlyHint":false,"destructiveHint":false,"openWorldHint":true},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"projectId":{"type":"string","minLength":1},"organizationUrn":{"type":"string","maxLength":200,"pattern":"^urn:li:organization:.*"}},"required":["projectId","organizationUrn"],"additionalProperties":false}}}}},"delete":{"operationId":"disconnect_linkedin","summary":"Disconnect LinkedIn","description":"Disconnect LinkedIn from a project and remove its subscription.","tags":["integrations"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"8-128 character retry key. Strongly recommended for writes.","schema":{"type":"string","minLength":8,"maxLength":128}}],"x-mcp-tool":"disconnect_linkedin","x-required-scope":"integrations:write","x-tool-annotations":{"readOnlyHint":false,"destructiveHint":true,"openWorldHint":true},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"projectId":{"type":"string","minLength":1}},"required":["projectId"],"additionalProperties":false}}}}}},"/integrations/linkedin/connect-url":{"post":{"operationId":"get_linkedin_connect_url","summary":"Get LinkedIn connect URL","description":"Return the secure browser URL the project owner must open to authorize LinkedIn.","tags":["integrations"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"8-128 character retry key. Strongly recommended for writes.","schema":{"type":"string","minLength":8,"maxLength":128}}],"x-mcp-tool":"get_linkedin_connect_url","x-required-scope":"integrations:write","x-tool-annotations":{"readOnlyHint":false,"destructiveHint":false,"openWorldHint":true},"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"projectId":{"type":"string","minLength":1}},"required":["projectId"],"additionalProperties":false}}}}}},"/integrations/linkedin/sync":{"post":{"operationId":"sync_linkedin","summary":"Sync LinkedIn now","description":"Run a metered LinkedIn sync now. Provider and workspace quotas still apply.","tags":["integrations"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"8-128 character retry key. Strongly recommended for writes.","schema":{"type":"string","minLength":8,"maxLength":128}}],"x-mcp-tool":"sync_linkedin","x-required-scope":"integrations:write","x-tool-annotations":{"readOnlyHint":false,"destructiveHint":false,"openWorldHint":true},"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"projectId":{"type":"string","minLength":1}},"required":["projectId"],"additionalProperties":false}}}}}},"/account":{"get":{"operationId":"get_account","summary":"Get account","description":"Get the authenticated user's Stalkr profile.","tags":["account"],"security":[{"BearerAuth":[]}],"parameters":[],"x-mcp-tool":"get_account","x-required-scope":"account:read","x-tool-annotations":{"readOnlyHint":true,"destructiveHint":false,"openWorldHint":false},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}},"patch":{"operationId":"update_account","summary":"Update account","description":"Update the authenticated user's display name.","tags":["account"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"8-128 character retry key. Strongly recommended for writes.","schema":{"type":"string","minLength":8,"maxLength":128}}],"x-mcp-tool":"update_account","x-required-scope":"account:write","x-tool-annotations":{"readOnlyHint":false,"destructiveHint":false,"openWorldHint":false},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80}},"required":["name"],"additionalProperties":false}}}}},"delete":{"operationId":"delete_account","summary":"Deactivate account","description":"Stop all projects, provider work, alerts, webhooks, machine access, LinkedIn access, and Stripe subscriptions while keeping account and project data recoverable. Requires explicit DELETE confirmation.","tags":["account"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"8-128 character retry key. Strongly recommended for writes.","schema":{"type":"string","minLength":8,"maxLength":128}}],"x-mcp-tool":"delete_account","x-required-scope":"account:write","x-tool-annotations":{"readOnlyHint":false,"destructiveHint":true,"openWorldHint":true},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"confirmation":{"type":"string","const":"DELETE"}},"required":["confirmation"],"additionalProperties":false}}}}}},"/usage":{"get":{"operationId":"get_usage","summary":"Get usage and limits","description":"Get plan, mention, keyword, source, and project usage with the same billing windows as the dashboard. Trial workspaces include 100 free mentions. Paid discovery pauses at the mention limit and automatically becomes eligible again when an upgrade or monthly usage reset adds allowance.","tags":["usage"],"security":[{"BearerAuth":[]}],"parameters":[],"x-mcp-tool":"get_usage","x-required-scope":"usage:read","x-tool-annotations":{"readOnlyHint":true,"destructiveHint":false,"openWorldHint":false},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/webhooks":{"get":{"operationId":"list_webhooks","summary":"List webhooks","description":"List webhook endpoints visible to the authenticated user.","tags":["webhooks"],"security":[{"BearerAuth":[]}],"parameters":[],"x-mcp-tool":"list_webhooks","x-required-scope":"webhooks:read","x-tool-annotations":{"readOnlyHint":true,"destructiveHint":false,"openWorldHint":false},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}},"post":{"operationId":"create_webhook","summary":"Create webhook","description":"Create a signed HTTPS webhook endpoint for workspace or project events. The signing secret is returned once.","tags":["webhooks"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"8-128 character retry key. Strongly recommended for writes.","schema":{"type":"string","minLength":8,"maxLength":128}}],"x-mcp-tool":"create_webhook","x-required-scope":"webhooks:write","x-tool-annotations":{"readOnlyHint":false,"destructiveHint":false,"openWorldHint":true},"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"type":"string","minLength":1,"maxLength":80},"url":{"type":"string","maxLength":2048,"format":"uri"},"eventTypes":{"minItems":1,"maxItems":24,"type":"array","items":{"type":"string","enum":["mention.created","mention.updated","mention.status_changed","mention.marked_irrelevant","keyword.created","keyword.updated","keyword.deleted","keyword_group.created","keyword_group.updated","keyword_group.deleted","alert.created","alert.updated","alert.deleted","alert.delivered","project.created","project.updated","project.public_dashboard_updated","project.archived","project.deleted","integration.connected","integration.disconnected","integration.sync_completed","integration.sync_failed","webhook.test"]}}},"required":["name","url","eventTypes"],"additionalProperties":false}}}}}},"/webhooks/{endpointId}":{"patch":{"operationId":"update_webhook","summary":"Update webhook","description":"Update, enable, disable, or rotate a webhook endpoint secret. A rotated secret is returned once.","tags":["webhooks"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"endpointId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"description":"8-128 character retry key. Strongly recommended for writes.","schema":{"type":"string","minLength":8,"maxLength":128}}],"x-mcp-tool":"update_webhook","x-required-scope":"webhooks:write","x-tool-annotations":{"readOnlyHint":false,"destructiveHint":false,"openWorldHint":true},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"url":{"type":"string","maxLength":2048,"format":"uri"},"eventTypes":{"minItems":1,"maxItems":24,"type":"array","items":{"type":"string","enum":["mention.created","mention.updated","mention.status_changed","mention.marked_irrelevant","keyword.created","keyword.updated","keyword.deleted","keyword_group.created","keyword_group.updated","keyword_group.deleted","alert.created","alert.updated","alert.deleted","alert.delivered","project.created","project.updated","project.public_dashboard_updated","project.archived","project.deleted","integration.connected","integration.disconnected","integration.sync_completed","integration.sync_failed","webhook.test"]}},"active":{"type":"boolean"},"rotateSecret":{"type":"boolean"}},"additionalProperties":false}}}}},"delete":{"operationId":"delete_webhook","summary":"Delete webhook","description":"Delete a webhook endpoint and its retained delivery history.","tags":["webhooks"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"endpointId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"description":"8-128 character retry key. Strongly recommended for writes.","schema":{"type":"string","minLength":8,"maxLength":128}}],"x-mcp-tool":"delete_webhook","x-required-scope":"webhooks:write","x-tool-annotations":{"readOnlyHint":false,"destructiveHint":true,"openWorldHint":true},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/webhooks/{endpointId}/test":{"post":{"operationId":"test_webhook","summary":"Test webhook","description":"Queue a signed test event for exactly one webhook endpoint. Test sends share the workspace's daily delivery safety budget.","tags":["webhooks"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"endpointId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"description":"8-128 character retry key. Strongly recommended for writes.","schema":{"type":"string","minLength":8,"maxLength":128}}],"x-mcp-tool":"test_webhook","x-required-scope":"webhooks:write","x-tool-annotations":{"readOnlyHint":false,"destructiveHint":false,"openWorldHint":true},"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/webhooks/{endpointId}/deliveries":{"get":{"operationId":"list_webhook_deliveries","summary":"List webhook deliveries","description":"Inspect delivery status, attempts, response codes, and bounded response previews.","tags":["webhooks"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"endpointId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"limit","in":"query","required":true,"schema":{"default":50,"type":"integer","minimum":1,"maximum":100}}],"x-mcp-tool":"list_webhook_deliveries","x-required-scope":"webhooks:read","x-tool-annotations":{"readOnlyHint":true,"destructiveHint":false,"openWorldHint":false},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/webhooks/{endpointId}/deliveries/{deliveryId}/replay":{"post":{"operationId":"replay_webhook_delivery","summary":"Replay webhook delivery","description":"Reset and safely replay a retained webhook delivery. Replays share the workspace's daily delivery safety budget.","tags":["webhooks"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"endpointId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"deliveryId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"description":"8-128 character retry key. Strongly recommended for writes.","schema":{"type":"string","minLength":8,"maxLength":128}}],"x-mcp-tool":"replay_webhook_delivery","x-required-scope":"webhooks:write","x-tool-annotations":{"readOnlyHint":false,"destructiveHint":false,"openWorldHint":true},"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimited"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"Stalkr API key or OAuth access token"}},"schemas":{"SuccessEnvelope":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","additionalProperties":true},"meta":{"type":"object","required":["capability","requestId","idempotencyReplayed"],"properties":{"capability":{"type":"string"},"requestId":{"type":"string"},"idempotencyReplayed":{"type":"boolean"}}}}},"ErrorEnvelope":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"},"details":{"type":"array","items":{"type":"object"}}}}}}},"responses":{"BadRequest":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Unauthorized":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"UsageLimited":{"description":"Plan or safety limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Forbidden":{"description":"Missing scope or project role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"NotFound":{"description":"Resource not found or inaccessible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Conflict":{"description":"Conflicting or duplicate operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"RateLimited":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Unavailable":{"description":"A required safety dependency is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}