All docs
API Keys
API Keys
API keys let you access Koala SEO programmatically — through AI assistants, scripts, or custom integrations.
Creating an API Key
- Go to Settings → API Keys
- Click Create New Key
- Give it a descriptive name (e.g., "Claude Desktop", "Home Assistant script")
- Copy the key — you won't be able to see it again
Using Your API Key
Include your API key in the Authorization header:
Authorization: Bearer YOUR_API_KEY_HERE
Available Endpoints
All API access is through the /api/v1 prefix:
Sites
| Method | Endpoint | Description |
|---|---|---|
GET |
/sites |
List all connected sites |
GET |
/sites/{siteUrl} |
Get site details |
Keywords
| Method | Endpoint | Description |
|---|---|---|
GET |
/properties/{siteUrl}/keywords |
List keywords for a site |
GET |
/properties/{siteUrl}/keywords/{keyword} |
Get details for a specific keyword |
Trends
| Method | Endpoint | Description |
|---|---|---|
GET |
/properties/{siteUrl}/trends/best |
Best performing keywords |
GET |
/properties/{siteUrl}/trends/worst |
Worst performing keywords |
Opportunities
| Method | Endpoint | Description |
|---|---|---|
GET |
/properties/{siteUrl}/opportunities/quick-wins |
Quick win opportunities |
GET |
/properties/{siteUrl}/opportunities/ctr |
CTR improvement opportunities |
Favorites
| Method | Endpoint | Description |
|---|---|---|
GET |
/favorite-keywords |
List all favorited keywords |
POST |
/favorite-keywords |
Add a keyword to favorites |
DELETE |
/favorite-keywords/{id} |
Remove a keyword from favorites by ID |
DELETE |
/favorite-keywords/by-keyword?siteUrl=...&keyword=... |
Remove by site + keyword |
Notes
| Method | Endpoint | Description |
|---|---|---|
GET |
/notes |
List all notes |
POST |
/notes |
Create a note |
PUT |
/notes/{id} |
Update a note |
DELETE |
/notes/{id} |
Delete a note |
MCP Server
For AI assistants, Koala provides an MCP server at /api/mcp. Configure your AI client to connect using your API key as a Bearer token.
See Connect AI Assistants for setup instructions.
Security
- Keep keys secret — Don't commit them to version control or share publicly
- Use descriptive names — Know which integration each key is for
- Revoke unused keys — If you stop using an integration, delete the key
- One key per integration — Makes rotation easier if a key is compromised
Rate Limits
API requests are rate-limited to ensure fair usage. If you hit a limit, wait a few seconds before retrying. For bulk operations, implement backoff logic.