API Overview
API v2 Overview
What’s New in v2
The v2 API provides comprehensive data export capabilities that mirror the CSV export functionality in the Knowatoa web application. Key improvements include:
- Multiple Output Formats: Every endpoint supports JSON (nested and flat) and CSV formats
- Site-Level Exports: 6 endpoints for individual site data
- Account-Level Exports: 6 endpoints for aggregated data across all sites
- BI Tool Integration: Flat JSON format optimized for Looker Studio and similar tools
- Consistent Data Structure: Matches CSV exports exactly for seamless migration
Get Your API Key
Log in to Knowatoa, from the sidebar choose Integrations and then API - if your plan supports
API access, the API key will be displayed.
Base URL
All v2 API endpoints are relative to:
https://app.knowatoa.com/api/v2/
Authentication
Same as V1 - include your API key as a query parameter:
?api_key=YOUR_API_KEY
Output Formats
Nested JSON (Default)
Standard hierarchical JSON structure:
https://app.knowatoa.com/api/v2/sites/tpc_abc123/questions?api_key=YOUR_API_KEY
Flat JSON (for BI Tools)
Flattened array format for Looker Studio, Tableau, etc. Activated by: -
Adding ?flat=true parameter.
https://app.knowatoa.com/api/v2/sites/tpc_abc123/questions?api_key=YOUR_API_KEY&flat=true
CSV Export
CSV format matching web application exports:
https://app.knowatoa.com/api/v2/sites/tpc_abc123/questions?api_key=YOUR_API_KEY&format=csv
Available Endpoints
Site-Level Exports
- GET /sites/:site_id/questions - Questions with mentions and sentiment
- GET /sites/:site_id/rankings - AI responses with ranks and citations
- GET /sites/:site_id/sentiment - Sentiment analysis per series
- GET /sites/:site_id/sources
- Citation domains from AI responses
- GET
/sites/:site_id/visibility
- Appearance rates across series
- GET
/sites/:site_id/competitors
- Competitor visibility analysis
Account-Level Exports
- GET /account/questions - All questions across all sites
- GET /account/rankings - All rankings across all sites
- GET /account/sentiment - All sentiment data across all sites
- GET /account/sources - All sources across all sites
- GET /account/visibility - All visibility data across all sites
- GET /account/competitors - All competitor data across all sites
Terminology
- Site: A business/website being monitored (internally called “topic”)
- Series: Collection of AI models (ChatGPT, Perplexity, etc.)
- Question: Search query used to test AI responses
- Rank: Position where site appears in AI response
- Mention: Whether the site appears in an AI response
- Sentiment: Tone of mention (Positive, Neutral, Negative, Mixed)