polecat-x-api

PolecatX API

Use this skill to query the PolecatX API for media monitoring data — events, entities, companies, and theme sets.

Auth check

Before any API call, verify the key is available:

if [ -z "$POLECATX_API_KEY" ]; then
  echo "POLECATX_API_KEY is not set"
  exit 1
fi

If unset, tell the user to add it to .claude/settings.local.json:

{
  "env": {
    "POLECATX_API_KEY": "<your-token>"
  }
}

Tokens are created in PolecatX via API → Tokens.

Base variables

BASE="https://x.polecat.com/beta"
AUTH="Authorization: Bearer $POLECATX_API_KEY"

Endpoints

Verify auth

curl -s -H "$AUTH" "$BASE/whoami"

Search entities (by name, ticker, or ISIN)

curl -s -X POST -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"name": "Apple", "limit": 5}' \
  "$BASE/entities/search"

Returns [{id, name, type, ticker, isin}]. Get entity IDs here before fetching events.

Search companies (public companies only)

curl -s -H "$AUTH" "$BASE/companies/search?name=Apple&limit=5"

Fetch events — POST (main endpoint)

POST /events triggers a scan and returns fresh data. Always prefer this over GET /events unless the same params were already scanned recently.

curl -s -X POST -H "$AUTH" -H "Content-Type: application/json" \
  -d '{
    "entity": ["entity-id-1"],
    "start": "2024-01-01T00:00:00Z",
    "end":   "2024-03-31T23:59:59Z"
  }' \
  "$BASE/events"

Optional filters in the body: sentiment (positive/concerning/unclear), esg_controversies (environmental/social/governance), source_categories (international/national/industry/local/other), locations (country or region name), summary_include, summary_exclude, source_allow, source_deny, themeset (theme set ID).

Response shape: { data: { events: [...], timeSeries: [...] } }

Event fields: id, summary, sentiment, score, scoringFactors, entity, esgControversy, entityRelevance, dateRange, sources, sampleLinks, themes.

Fetch events — GET (cache read)

Only use this when POST /events was already called with the same params. Array params must be repeated:

curl -s -H "$AUTH" \
  "$BASE/events?entity=id1&entity=id2&start=2024-01-01T00:00:00Z&end=2024-03-31T23:59:59Z"

Get entity by ID

curl -s -H "$AUTH" "$BASE/entities/<id>"

Create entity

curl -s -X POST -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"name": "Acme Corp", "type": "organization", "description": "...", "url": "https://acme.example.com", "industry": "Technology"}' \
  "$BASE/entities"

Update entity

curl -s -X PUT -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"name": "Acme Corporation"}' \
  "$BASE/entities/<id>"

Delete entity

curl -s -X DELETE -H "$AUTH" "$BASE/entities/<id>"

Search theme sets

curl -s -X POST -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"title": "ESG", "limit": 10}' \
  "$BASE/themesets/search"

Create theme set

curl -s -X POST -H "$AUTH" -H "Content-Type: application/json" \
  -d '{
    "title": "ESG Themes",
    "themes": [
      {"title": "Climate", "description": "Environmental and climate-related events."},
      {"title": "Governance", "description": "Corporate governance events."}
    ],
    "multi_theme": true
  }' \
  "$BASE/themesets"

Get / update / delete theme set

curl -s -H "$AUTH" "$BASE/themesets/<id>"
curl -s -X PUT -H "$AUTH" -H "Content-Type: application/json" -d '{"title": "Updated"}' "$BASE/themesets/<id>"
curl -s -X DELETE -H "$AUTH" "$BASE/themesets/<id>"

Typical workflow

1. Find entity IDs: POST /entities/search or GET /companies/search
2. Fetch events: POST /events with entity IDs + date range
3. Optionally re-read cached data: GET /events with same params

Notes

• Dates must be UTC ISO 8601: 2024-01-01T00:00:00Z
• Array query params must be repeated: ?entity=id1&entity=id2 (not comma-separated)
• POST /events returns 502 when some providers failed but still includes partial results