Guide

Quickstart

Create a scoped credential, make your first call, then choose REST, MCP, or both for your agent runtime.

1. Create a key

Open Dashboard → Developer, choose Create key, and select full or read-only access. Copy the secret immediately; only its hash is retained.

Use environment variables

Store the key as STALKR_API_KEY in your secret manager. Never place it in prompts, client-side code, source control, query strings, or webhook payloads.

2. List projects

cURL

curl "https://www.stalkr.ai/api/v1/projects" \
  --header "Authorization: Bearer $STALKR_API_KEY" \
  --header "X-Request-Id: my-agent-run-0001"

Response

{
  "data": { "projects": [/* projects you can access */] },
  "meta": {
    "capability": "list_projects",
    "requestId": "my-agent-run-0001",
    "idempotencyReplayed": false
  }
}

3. Make a safe write

Send an idempotency key on every write. Retrying the same operation with the same payload returns the original response; reusing a key with different input is rejected.

Create keyword

curl "https://www.stalkr.ai/api/v1/keywords" \
  --request POST \
  --header "Authorization: Bearer $STALKR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: run-42-create-keyword" \
  --data '{
    "projectId": "PROJECT_ID",
    "value": "your brand",
    "sources": ["x", "reddit", "youtube"]
  }'

Project editor access and the workspace keyword limit are checked before creation. The API does not bypass plan entitlements.

4. Connect MCP

For ChatGPT and OAuth-capable clients, add https://www.stalkr.ai/mcp. Stalkr publishes OAuth discovery metadata automatically; sign in, review the requested scopes, and approve the connection.

Read the MCP setup guide →