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",
      "sentiment": "positive",
      "language": "en",
      "tags": ["feature-request"],
      "keywords": [{ "id": 1, "keyword": "YourProduct" }],
      "bookmarked": false,
      "engaged": false
    }
  ],
  "cursor": "eyJsYXN0SWQiOiAiYWJjMTIzIn0="
}
```

### 2. GET /keywords

List all keywords configured for the organization.

**Example Response:**
```json
{
  "data": [
    {
      "id": 1,
      "keyword": "YourProduct",
      "platforms": ["twitter", "reddit", "github"],
      "color": "#6366f1",
      "paused": false,
      "context": "Our main product name"
    }
  ]
}
```

### 3. GET /views

List all saved views (pre-configured filters).

**Example Response:**
```json
{
  "data": [
    {
      "id": 1,
      "name": "High Priority",
      "icon": "star",
      "filters": {
        "sentiment": ["positive", "negative"],
        "source": ["twitter"]
      },
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ]
}
```

## Filtering Mentions

The `/mentions` endpoint supports powerful filtering with two modes:

### Simple Mode (Implicit AND)

Put fields directly in filters. All conditions are ANDed together.

```json
{
  "filters": {
    "source": ["twitter", "linkedin"],
    "sentiment": ["positive"],
    "minXFollowers": 1000
  }
}
```
→ `source IN (twitter, linkedin) AND sentiment = positive AND followers ≥ 1000`

### Exclusions

Prefix any array field with ! to exclude values:

```json
{
  "filters": {
    "source": ["twitter"],
    "!keyword": [5, 6]
  }
}
```
→ `source = twitter AND keyword NOT IN (5, 6)`

### Advanced Mode (AND/OR Groups)

Use `operator` and `groups` for complex logic:

```json
{
  "filters": {
    "operator": "AND",
    "groups": [
      {
        "operator": "OR",
        "conditions": [
          { "source": ["twitter"] },
          { "source": ["linkedin"] }
        ]
      },
      {
        "operator": "AND",
        "conditions": [
          { "sentiment": ["positive"] },
          { "!tag": ["spam"] }
        ]
      }
    ]
  }
}
```
→ `(source = twitter OR source = linkedin) AND (sentiment = positive AND tag ≠ spam)`

### Available Filter Fields

| Field | Type | Description |
|-------|------|-------------|
| `source` | string[] | Platforms: twitter, reddit, github, linkedin, youtube, hackernews, devto, stackoverflow, bluesky, newsletter, podcast |
| `sentiment` | string[] | Values: positive, neutral, negative |
| `keyword` | string[] | Keyword IDs (get from /keywords endpoint) |
| `language` | string[] | ISO 639-1 codes: en, es, fr, de, pt, it, nl, ja, ko, zh |
| `tag` | string[] | Tag names |
| `bookmarked` | boolean | Filter bookmarked (true) or non-bookmarked (false) posts |
| `engaged` | boolean | Filter engaged (true) or non-engaged (false) posts |
| `minXFollowers` | number | Minimum Twitter follower count |
| `maxXFollowers` | number | Maximum Twitter follower count |
| `startDate` | string | ISO 8601 format (e.g., "2024-01-15T00:00:00Z") |
| `endDate` | string | ISO 8601 format |

## Using the Bundled Scripts

This skill includes helper scripts for common operations. Use them to quickly interact with the API:

### Fetch Mentions
```bash
node scripts/fetch-mentions.js YOUR_API_KEY [limit] [includeAll]
```

### List Keywords
```bash
node scripts/list-keywords.js YOUR_API_KEY
```

### List Views
```bash
node scripts/list-views.js YOUR_API_KEY
```

### Custom Filter Query
```bash
node scripts/query-mentions.js YOUR_API_KEY '{"source": ["twitter"], "sentiment": ["positive"]}' [limit]
```

### Advanced Query
```bash
node scripts/advanced-query.js YOUR_API_KEY [limit]
```

## Best Practices

1. **Always ask for the API key** before making requests
2. **Use views** when possible to leverage pre-configured filters
3. **Start with simple filters** and add complexity as needed
4. **Check rate limits** in response headers (`X-RateLimit-*`)
5. **Use pagination** with cursor for large result sets
6. **Dates must be ISO 8601** format (e.g., "2024-01-15T00:00:00Z")
7. **Get keyword IDs** from `/keywords` endpoint before filtering by keyword
8. **Use exclusions** (!) to filter out unwanted content
9. **Combine includeAll=false** with relevance filtering for quality results

## Common Use Cases

### Find positive Twitter mentions with high followers
```json
{
  "limit": 20,
  "filters": {
    "source": ["twitter"],
    "sentiment": ["positive"],
    "minXFollowers": 1000
  }
}
```

### Exclude spam and get Reddit + GitHub mentions
```json
{
  "limit": 50,
  "filters": {
    "source": ["reddit", "github"],
    "!tag": ["spam", "irrelevant"]
  }
}
```

### Complex query: (Twitter OR LinkedIn) AND positive sentiment, last 7 days
```json
{
  "limit": 30,
  "filters": {
    "operator": "AND",
    "groups": [
      {
        "operator": "OR",
        "conditions": [
          { "source": ["twitter"] },
          { "source": ["linkedin"] }
        ]
      },
      {
        "operator": "AND",
        "conditions": [
          { "sentiment": ["positive"] },
          { "startDate": "2024-01-20T00:00:00Z" }
        ]
      }
    ]
  }
}
```

## Error Handling

| Status | Error | Description |
|--------|-------|-------------|
| 401 | unauthorized | Missing or invalid API key |
| 403 | forbidden | Valid key but no permission |
| 404 | not_found | Resource (e.g., view ID) not found |
| 429 | rate_limit_exceeded | Too many requests |
| 400 | invalid_request | Malformed request body |
| 500 | internal_error | Server error, retry later |

## Step-by-Step Workflow

When a user asks to query Octolens data:

1. **Ask for API key** if not already provided
2. **Understand the request**: What are they looking for?
3. **Determine filters needed**: Source, sentiment, date range, etc.
4. **Check if a view applies**: List views first if user mentions saved filters
5. **Build the query**: Use simple mode first, advanced mode for complex logic
6. **Execute the request**: Use bundled Node.js scripts or fetch API directly
7. **Parse results**: Extract key information (author, body, sentiment, source)
8. **Handle pagination**: If more results needed, use cursor from response
9. **Present findings**: Summarize insights, highlight patterns

## Examples

### Example 1: Simple Query
**User**: "Show me positive mentions from Twitter in the last 7 days"

**Action** (using bundled script):
```bash
node scripts/query-mentions.js YOUR_API_KEY '{"source": ["twitter"], "sentiment": ["positive"], "startDate": "2024-01-20T00:00:00Z"}'
```

**Alternative** (using fetch API directly):
```javascript
const response = await fetch('https://app.octolens.com/api/v1/mentions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    limit: 20,
    filters: {
      source: ['twitter'],
      sentiment: ['positive'],
      startDate: '2024-01-20T00:00:00Z',
    },
  }),
});
const data = await response.json();
```

### Example 2: Advanced Query
**User**: "Find mentions from Reddit or GitHub, exclude spam tag, with positive or neutral sentiment"

**Action** (using bundled script):
```bash
node scripts/query-mentions.js YOUR_API_KEY '{"operator": "AND", "groups": [{"operator": "OR", "conditions": [{"source": ["reddit"]}, {"source": ["github"]}]}, {"operator": "OR", "conditions": [{"sentiment": ["positive"]}, {"sentiment": ["neutral"]}]}, {"operator": "AND", "conditions": [{"!tag": ["spam"]}]}]}'
```

**Alternative** (using fetch API directly):
```javascript
const response = await fetch('https://app.octolens.com/api/v1/mentions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    limit: 30,
    filters: {
      operator: 'AND',
      groups: [
        {
          operator: 'OR',
          conditions: [
            { source: ['reddit'] },
            { source: ['github'] },
          ],
        },
        {
          operator: 'OR',
          conditions: [
            { sentiment: ['positive'] },
            { sentiment: ['neutral'] },
          ],
        },
        {
          operator: 'AND',
          conditions: [
            { '!tag': ['spam'] },
          ],
        },
      ],
    },
  }),
});
const data = await response.json();
```

### Example 3: Get Keywords First
**User**: "Show mentions for our main product keyword"

**Actions**:
1. First, list keywords:
```bash
node scripts/list-keywords.js YOUR_API_KEY
```

2. Then query mentions with the keyword ID:
```bash
node scripts/query-mentions.js YOUR_API_KEY '{"keyword": [1]}'
```

## Tips for Agents

- **Use bundled scripts**: The Node.js scripts handle JSON parsing automatically
- **Cache keywords**: After fetching keywords once, remember them for the session
- **Explain filters**: When using complex filters, explain the logic to the user
- **Show examples**: When users are unsure, show example filter structures
- **Paginate wisely**: Ask if user wants more results before fetching next page
- **Summarize insights**: Don't just dump data, provide analysis (sentiment trends, top authors, platform distribution)