octolens

# Octolens API Skill

## When to use this skill

Use this skill when the user needs to:
- Fetch brand mentions from social media and other platforms
- Filter mentions by source (Twitter, Reddit, GitHub, LinkedIn, YouTube, HackerNews, DevTO, StackOverflow, Bluesky, newsletters, podcasts)
- Analyze sentiment (positive, neutral, negative)
- Filter by author follower count or engagement
- Search for specific keywords or tags
- Query mentions by date range
- List available keywords or saved views
- Apply complex filtering logic with AND/OR conditions

## API Authentication

The Octolens API requires a Bearer token for authentication. The user should provide their API key, which you'll use in the `Authorization` header:

```
Authorization: Bearer YOUR_API_KEY
```

**Important**: Always ask the user for their API key before making any API calls. Store it in a variable for subsequent requests.

## Base URL

All API endpoints use the base URL: `https://app.octolens.com/api/v1`

## Rate Limits

- **Limit**: 500 requests per hour
- **Check headers**: `X-RateLimit-*` headers indicate current usage

## Available Endpoints

### 1. POST /mentions

Fetch mentions matching keywords with optional filtering. Returns posts sorted by timestamp (newest first).

**Key Parameters:**
- `limit` (number, 1-100): Maximum results to return (default: 20)
- `cursor` (string): Pagination cursor from previous response
- `includeAll` (boolean): Include low-relevance posts (default: false)
- `view` (number): View ID to use for filtering
- `filters` (object): Filter criteria (see filtering section)

**Example Response:**
```json
{
  "data": [
    {
      "id": "abc123",
      "url": "https://twitter.com/user/status/123",
      "body": "Just discovered @YourProduct - this is exactly what I needed!",
      "source": "twitter",
      "timestamp": "2024-01-15T10:30:00Z",
      "author": "user123",
      "authorName": "John Doe",
      "authorFollowers": 5420,
      "relevance": "relevant",
      "sentimen...