# Stalkr full agent documentation

## Architecture

Stalkr defines product workflows once in a capability registry. REST routes, MCP tools, OpenAPI, activity logs, and reference documentation are generated from or execute that same registry. Every project starts with exactly two built-in keyword groups, My brand and Competitors; their names are fixed, and they cannot be updated or deleted. Every additional group is custom. The total group allowance, including both built-ins, equals the workspace keyword allowance. Keyword groups are first-class resources: keywords accept groupId, while mention, analytics, digest, and custom-alert filters accept keywordGroupIds. Mention analytics includes a keywordGroups breakdown for groups with active keywords. Project access is evaluated on every resource, after token scope checks. Dashboard and agent workflows share the same quota and provider services.

## Authentication

REST clients use Authorization: Bearer stalkr_sk_... keys created at https://www.stalkr.ai/developer. Keys are hashed at rest and can be scoped, expired, and revoked. MCP clients use https://www.stalkr.ai/mcp. ChatGPT discovers OAuth metadata, uses authorization code plus PKCE S256, and receives rotating refresh tokens restricted to the MCP resource.

## REST contract

Base URL: https://www.stalkr.ai/api/v1. Successes return {"data":...,"meta":{"capability":"...","requestId":"...","idempotencyReplayed":false}}. Failures return {"error":{"code":"...","message":"...","requestId":"..."}}. JSON request bodies are capped at 64 KB. Writes accept Idempotency-Key and retain completed responses for 24 hours.

## MCP contract

The Streamable HTTP server exposes each operation below as a tool, including read-only, destructive, and open-world annotations. It also exposes stalkr://capabilities. Tool results use the REST structured envelope. Safe tool errors never expose stacks or secrets.

## Webhooks

Events: 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. Payload IDs remain stable across retries. Signatures are HMAC-SHA256 over webhook-id + "." + webhook-timestamp + "." + rawBody, Base64 encoded in webhook-signature as v1,<digest>. Accept only verified signatures with a recent timestamp and deduplicate by ID. Delivery attempts time out after ten seconds, never follow redirects, retry eight times, and automatically disable endpoints after repeated failures.

## Limits and safety

Trial accounts have complete feature access with lower database-call rate ceilings. Existing keyword, mention, scan, alert, project, member, and provider quotas always apply. All machine clients in a workspace share rate buckets so extra keys do not multiply capacity. Webhook destinations are checked for HTTPS, DNS rebinding, local/private/reserved networks, custom ports, credentials, and redirects.

## Operations

### list_projects
- Purpose: List every active project the authenticated user owns or has been invited to.
- REST: GET https://www.stalkr.ai/api/v1/projects
- MCP tool: list_projects
- Required scope: projects:read
- Safety: readOnly=true, destructive=false, externalSideEffects=false

### get_project
- Purpose: Get one project and the authenticated user's role in it.
- REST: GET https://www.stalkr.ai/api/v1/projects/:projectId
- MCP tool: get_project
- Required scope: projects:read
- Safety: readOnly=true, destructive=false, externalSideEffects=false

### create_project
- Purpose: 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.
- REST: POST https://www.stalkr.ai/api/v1/projects
- MCP tool: create_project
- Required scope: projects:write
- Safety: readOnly=false, destructive=false, externalSideEffects=true

### update_project
- Purpose: Update project details or status. Only owners can pause or resume a project. Use delete_project for permanent deletion.
- REST: PATCH https://www.stalkr.ai/api/v1/projects/:projectId
- MCP tool: update_project
- Required scope: projects:write
- Safety: readOnly=false, destructive=false, externalSideEffects=false

### get_public_dashboard
- Purpose: Get the owner-only publication state and share URL for a project dashboard.
- REST: GET https://www.stalkr.ai/api/v1/projects/:projectId/public-dashboard
- MCP tool: get_public_dashboard
- Required scope: projects:read
- Safety: readOnly=true, destructive=false, externalSideEffects=false

### set_public_dashboard
- Purpose: 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.
- REST: PATCH https://www.stalkr.ai/api/v1/projects/:projectId/public-dashboard
- MCP tool: set_public_dashboard
- Required scope: projects:write
- Safety: readOnly=false, destructive=false, externalSideEffects=true

### delete_project
- Purpose: 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.
- REST: DELETE https://www.stalkr.ai/api/v1/projects/:projectId
- MCP tool: delete_project
- Required scope: projects:write
- Safety: readOnly=false, destructive=true, externalSideEffects=true

### list_project_members
- Purpose: List project members and, for owners, pending invitations.
- REST: GET https://www.stalkr.ai/api/v1/projects/:projectId/members
- MCP tool: list_project_members
- Required scope: projects:read
- Safety: readOnly=true, destructive=false, externalSideEffects=false

### invite_project_member
- Purpose: Email a time-limited project invitation. Only owners can invite and the existing seat and email rate limits apply.
- REST: POST https://www.stalkr.ai/api/v1/projects/:projectId/members
- MCP tool: invite_project_member
- Required scope: projects:write
- Safety: readOnly=false, destructive=false, externalSideEffects=true

### update_project_member
- Purpose: Change a member or pending invite role. Only the project owner can do this.
- REST: PATCH https://www.stalkr.ai/api/v1/projects/:projectId/members/:memberId
- MCP tool: update_project_member
- Required scope: projects:write
- Safety: readOnly=false, destructive=false, externalSideEffects=false

### remove_project_member
- Purpose: Remove a member or revoke a pending project invite.
- REST: DELETE https://www.stalkr.ai/api/v1/projects/:projectId/members/:memberId
- MCP tool: remove_project_member
- Required scope: projects:write
- Safety: readOnly=false, destructive=true, externalSideEffects=false

### list_keywords
- Purpose: List tracked keywords for one project or all accessible active projects.
- REST: GET https://www.stalkr.ai/api/v1/keywords
- MCP tool: list_keywords
- Required scope: keywords:read
- Safety: readOnly=true, destructive=false, externalSideEffects=false

### create_keyword
- Purpose: Create a tracked keyword in My brand or a specified keyword group. Existing workspace keyword limits are enforced.
- REST: POST https://www.stalkr.ai/api/v1/keywords
- MCP tool: create_keyword
- Required scope: keywords:write
- Safety: readOnly=false, destructive=false, externalSideEffects=true

### update_keyword
- Purpose: Update keyword text, sources, filters, group assignment, or active state.
- REST: PATCH https://www.stalkr.ai/api/v1/keywords/:keywordId
- MCP tool: update_keyword
- Required scope: keywords:write
- Safety: readOnly=false, destructive=false, externalSideEffects=true

### delete_keyword
- Purpose: Deactivate a tracked keyword without deleting its historical mentions.
- REST: DELETE https://www.stalkr.ai/api/v1/keywords/:keywordId
- MCP tool: delete_keyword
- Required scope: keywords:write
- Safety: readOnly=false, destructive=true, externalSideEffects=true

### list_keyword_groups
- Purpose: List reusable brand, competitor, and custom keyword groups.
- REST: GET https://www.stalkr.ai/api/v1/keyword-groups
- MCP tool: list_keyword_groups
- Required scope: keywords:read
- Safety: readOnly=true, destructive=false, externalSideEffects=false

### create_keyword_group
- Purpose: Create a custom keyword group inside an editable project. The total group allowance, including My brand and Competitors, equals the workspace keyword allowance.
- REST: POST https://www.stalkr.ai/api/v1/keyword-groups
- MCP tool: create_keyword_group
- Required scope: keywords:write
- Safety: readOnly=false, destructive=false, externalSideEffects=false

### update_keyword_group
- Purpose: Rename or reorder a custom keyword group. Default group names are fixed.
- REST: PATCH https://www.stalkr.ai/api/v1/keyword-groups/:groupId
- MCP tool: update_keyword_group
- Required scope: keywords:write
- Safety: readOnly=false, destructive=false, externalSideEffects=false

### delete_keyword_group
- Purpose: Delete an unused custom keyword group. Default groups are fixed and cannot be deleted.
- REST: DELETE https://www.stalkr.ai/api/v1/keyword-groups/:groupId
- MCP tool: delete_keyword_group
- Required scope: keywords:write
- Safety: readOnly=false, destructive=true, externalSideEffects=false

### search_mention_authors
- Purpose: Autocomplete accounts that mentioned a brand by partial display name or handle, including their network, avatar, and mention count.
- REST: GET https://www.stalkr.ai/api/v1/mention-authors
- MCP tool: search_mention_authors
- Required scope: mentions:read
- Safety: readOnly=true, destructive=false, externalSideEffects=false

### list_mentions
- Purpose: 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.
- REST: GET https://www.stalkr.ai/api/v1/mentions
- MCP tool: list_mentions
- Required scope: mentions:read
- Safety: readOnly=true, destructive=false, externalSideEffects=false

### get_mention
- Purpose: Get one source-compliant mention from an accessible project, including stored quoted-post context when available.
- REST: GET https://www.stalkr.ai/api/v1/mentions/:mentionId
- MCP tool: get_mention
- Required scope: mentions:read
- Safety: readOnly=true, destructive=false, externalSideEffects=false

### mark_mention_irrelevant
- Purpose: 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.
- REST: POST https://www.stalkr.ai/api/v1/mentions/:mentionId/irrelevant
- MCP tool: mark_mention_irrelevant
- Required scope: mentions:write
- Safety: readOnly=false, destructive=true, externalSideEffects=false

### update_mention_status
- Purpose: Mark a mention open, done, or needing follow-up.
- REST: PATCH https://www.stalkr.ai/api/v1/mentions/:mentionId
- MCP tool: update_mention_status
- Required scope: mentions:write
- Safety: readOnly=false, destructive=false, externalSideEffects=false

### get_mention_analytics
- Purpose: 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.
- REST: GET https://www.stalkr.ai/api/v1/analytics/mentions
- MCP tool: get_mention_analytics
- Required scope: mentions:read
- Safety: readOnly=true, destructive=false, externalSideEffects=false

### list_categories
- Purpose: List mention categories for one project or every accessible project.
- REST: GET https://www.stalkr.ai/api/v1/categories
- MCP tool: list_categories
- Required scope: mentions:read
- Safety: readOnly=true, destructive=false, externalSideEffects=false

### create_category
- Purpose: Create a category in a project the user can edit.
- REST: POST https://www.stalkr.ai/api/v1/categories
- MCP tool: create_category
- Required scope: mentions:write
- Safety: readOnly=false, destructive=false, externalSideEffects=false

### update_category
- Purpose: Update a mention category.
- REST: PATCH https://www.stalkr.ai/api/v1/categories/:categoryId
- MCP tool: update_category
- Required scope: mentions:write
- Safety: readOnly=false, destructive=false, externalSideEffects=false

### delete_category
- Purpose: Delete a category. Existing mentions become uncategorized.
- REST: DELETE https://www.stalkr.ai/api/v1/categories/:categoryId
- MCP tool: delete_category
- Required scope: mentions:write
- Safety: readOnly=false, destructive=true, externalSideEffects=false

### list_mention_views
- Purpose: List saved mention filter presets.
- REST: GET https://www.stalkr.ai/api/v1/mention-views
- MCP tool: list_mention_views
- Required scope: mentions:read
- Safety: readOnly=true, destructive=false, externalSideEffects=false

### create_mention_view
- Purpose: Save a mention filter preset.
- REST: POST https://www.stalkr.ai/api/v1/mention-views
- MCP tool: create_mention_view
- Required scope: mentions:write
- Safety: readOnly=false, destructive=false, externalSideEffects=false

### update_mention_view
- Purpose: Update a saved mention filter preset.
- REST: PATCH https://www.stalkr.ai/api/v1/mention-views/:viewId
- MCP tool: update_mention_view
- Required scope: mentions:write
- Safety: readOnly=false, destructive=false, externalSideEffects=false

### delete_mention_view
- Purpose: Delete a saved mention filter preset.
- REST: DELETE https://www.stalkr.ai/api/v1/mention-views/:viewId
- MCP tool: delete_mention_view
- Required scope: mentions:write
- Safety: readOnly=false, destructive=true, externalSideEffects=false

### list_alerts
- Purpose: List alert rules, the workspace-owner email recipient, and the shared daily email limit for the workspace or an accessible project.
- REST: GET https://www.stalkr.ai/api/v1/alerts
- MCP tool: list_alerts
- Required scope: alerts:read
- Safety: readOnly=true, destructive=false, externalSideEffects=false

### create_alert
- Purpose: 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.
- REST: POST https://www.stalkr.ai/api/v1/alerts
- MCP tool: create_alert
- Required scope: alerts:write
- Safety: readOnly=false, destructive=false, externalSideEffects=true

### update_alert
- Purpose: Update an alert rule, including its keyword-group and individual-keyword targets.
- REST: PATCH https://www.stalkr.ai/api/v1/alerts/:alertId
- MCP tool: update_alert
- Required scope: alerts:write
- Safety: readOnly=false, destructive=false, externalSideEffects=true

### delete_alert
- Purpose: Delete an alert rule.
- REST: DELETE https://www.stalkr.ai/api/v1/alerts/:alertId
- MCP tool: delete_alert
- Required scope: alerts:write
- Safety: readOnly=false, destructive=true, externalSideEffects=true

### get_linkedin_integration
- Purpose: Get LinkedIn Page connection status and available Page choices for a project.
- REST: GET https://www.stalkr.ai/api/v1/integrations/linkedin
- MCP tool: get_linkedin_integration
- Required scope: integrations:read
- Safety: readOnly=true, destructive=false, externalSideEffects=false

### get_linkedin_connect_url
- Purpose: Return the secure browser URL the project owner must open to authorize LinkedIn.
- REST: POST https://www.stalkr.ai/api/v1/integrations/linkedin/connect-url
- MCP tool: get_linkedin_connect_url
- Required scope: integrations:write
- Safety: readOnly=false, destructive=false, externalSideEffects=true

### select_linkedin_page
- Purpose: Choose a Page after LinkedIn authorization.
- REST: PATCH https://www.stalkr.ai/api/v1/integrations/linkedin
- MCP tool: select_linkedin_page
- Required scope: integrations:write
- Safety: readOnly=false, destructive=false, externalSideEffects=true

### sync_linkedin
- Purpose: Run a metered LinkedIn sync now. Provider and workspace quotas still apply.
- REST: POST https://www.stalkr.ai/api/v1/integrations/linkedin/sync
- MCP tool: sync_linkedin
- Required scope: integrations:write
- Safety: readOnly=false, destructive=false, externalSideEffects=true

### disconnect_linkedin
- Purpose: Disconnect LinkedIn from a project and remove its subscription.
- REST: DELETE https://www.stalkr.ai/api/v1/integrations/linkedin
- MCP tool: disconnect_linkedin
- Required scope: integrations:write
- Safety: readOnly=false, destructive=true, externalSideEffects=true

### get_account
- Purpose: Get the authenticated user's Stalkr profile.
- REST: GET https://www.stalkr.ai/api/v1/account
- MCP tool: get_account
- Required scope: account:read
- Safety: readOnly=true, destructive=false, externalSideEffects=false

### update_account
- Purpose: Update the authenticated user's display name.
- REST: PATCH https://www.stalkr.ai/api/v1/account
- MCP tool: update_account
- Required scope: account:write
- Safety: readOnly=false, destructive=false, externalSideEffects=false

### delete_account
- Purpose: 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.
- REST: DELETE https://www.stalkr.ai/api/v1/account
- MCP tool: delete_account
- Required scope: account:write
- Safety: readOnly=false, destructive=true, externalSideEffects=true

### get_usage
- Purpose: 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.
- REST: GET https://www.stalkr.ai/api/v1/usage
- MCP tool: get_usage
- Required scope: usage:read
- Safety: readOnly=true, destructive=false, externalSideEffects=false

### list_webhooks
- Purpose: List webhook endpoints visible to the authenticated user.
- REST: GET https://www.stalkr.ai/api/v1/webhooks
- MCP tool: list_webhooks
- Required scope: webhooks:read
- Safety: readOnly=true, destructive=false, externalSideEffects=false

### create_webhook
- Purpose: Create a signed HTTPS webhook endpoint for workspace or project events. The signing secret is returned once.
- REST: POST https://www.stalkr.ai/api/v1/webhooks
- MCP tool: create_webhook
- Required scope: webhooks:write
- Safety: readOnly=false, destructive=false, externalSideEffects=true

### update_webhook
- Purpose: Update, enable, disable, or rotate a webhook endpoint secret. A rotated secret is returned once.
- REST: PATCH https://www.stalkr.ai/api/v1/webhooks/:endpointId
- MCP tool: update_webhook
- Required scope: webhooks:write
- Safety: readOnly=false, destructive=false, externalSideEffects=true

### delete_webhook
- Purpose: Delete a webhook endpoint and its retained delivery history.
- REST: DELETE https://www.stalkr.ai/api/v1/webhooks/:endpointId
- MCP tool: delete_webhook
- Required scope: webhooks:write
- Safety: readOnly=false, destructive=true, externalSideEffects=true

### test_webhook
- Purpose: Queue a signed test event for exactly one webhook endpoint. Test sends share the workspace's daily delivery safety budget.
- REST: POST https://www.stalkr.ai/api/v1/webhooks/:endpointId/test
- MCP tool: test_webhook
- Required scope: webhooks:write
- Safety: readOnly=false, destructive=false, externalSideEffects=true

### list_webhook_deliveries
- Purpose: Inspect delivery status, attempts, response codes, and bounded response previews.
- REST: GET https://www.stalkr.ai/api/v1/webhooks/:endpointId/deliveries
- MCP tool: list_webhook_deliveries
- Required scope: webhooks:read
- Safety: readOnly=true, destructive=false, externalSideEffects=false

### replay_webhook_delivery
- Purpose: Reset and safely replay a retained webhook delivery. Replays share the workspace's daily delivery safety budget.
- REST: POST https://www.stalkr.ai/api/v1/webhooks/:endpointId/deliveries/:deliveryId/replay
- MCP tool: replay_webhook_delivery
- Required scope: webhooks:write
- Safety: readOnly=false, destructive=false, externalSideEffects=true

## Canonical resources

- Docs: https://www.stalkr.ai/docs
- OpenAPI: https://www.stalkr.ai/openapi.json
- MCP: https://www.stalkr.ai/mcp
- OAuth discovery: https://www.stalkr.ai/.well-known/oauth-authorization-server
- MCP protected resource: https://www.stalkr.ai/.well-known/oauth-protected-resource/mcp