REST

Agent API

A versioned JSON API generated from the same capability registry as MCP. Base URL: https://www.stalkr.ai/api/v1

Request conventions

Send a Bearer token in the Authorization header.
Send JSON objects for POST, PATCH, and DELETE bodies; the maximum body is 64 KB.
Use Idempotency-Key on writes. Keys are retained for 24 hours.
Optional X-Request-Id values appear in responses and activity logs.
List endpoints use bounded limits and cursor pagination where applicable.

Authorization: Bearer $STALKR_API_KEY
Content-Type: application/json
Idempotency-Key: unique-operation-key
X-Request-Id: trace-from-your-system

Response envelope

{
  "data": { /* operation result */ },
  "meta": {
    "capability": "update_mention_status",
    "requestId": "...",
    "idempotencyReplayed": false
  }
}

Stable contract

The data shape is operation-specific. Transport metadata always lives under meta, and failures always use an error envelope.

Keyword groups

Every project starts with exactly two built-in groups: My brand and Competitors. Their names are fixed, and they cannot be updated or deleted. Any additional group is custom. The total number of groups, including both built-ins, is limited to the workspace’s keyword allowance. Use list_keyword_groups, create_keyword_group, update_keyword_group, and delete_keyword_group to manage reusable custom groups. Keywords accept groupId; mention and analytics queries accept keywordGroupIds; digest and custom-alert filters accept the same group targets.

Dynamic membership

A group filter resolves its current keywords when the query or alert runs, so keywords moved into that group are included automatically.

The get_mention_analytics result includes analytics.keywordGroups for every group with at least one active keyword. Each item contains the group identity, system key, active keyword count, filtered mention count, and share. A mention matching several keywords in one group counts once for that group.

Operations

Machine-readable schema

The complete OpenAPI 3.1 document is generated at build/request time from live Zod capability schemas.

Open /openapi.json →