# Lots Intel API Documentation

Base URL: `https://intel.lotsmcp.com`

## Overview

Internal competitor intelligence for a scout agent. Not a customer product.

## Authentication

AI agents: add `https://intel.lotsmcp.com/mcp` as a remote MCP server and sign in with OAuth; no key is needed.

For REST integrations, authenticate with an API key or an OAuth access token in the request header:

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://intel.lotsmcp.com/api/v1/lotsintel/endpoint
```

Or using the `X-API-Key` header:

```bash
curl -H "X-API-Key: YOUR_API_KEY" \
  https://intel.lotsmcp.com/api/v1/lotsintel/endpoint
```

### Getting an API Key

1. Open https://www.lotstech.com/api and click "Manage API keys"
2. Sign in with your Lots account
3. Choose Lots Intel, name the key and create it (keys for every Lots app are managed in the same place)
4. Copy and securely store your API key (it will only be shown once)

Keys can also be created at https://intel.lotsmcp.com/dashboard.

## Rate Limiting

API requests are rate-limited to prevent abuse. Default limits:

- **100 requests per minute** per API key
- Rate limit headers are included in all responses:
  - `X-RateLimit-Limit`: Maximum requests allowed
  - `X-RateLimit-Remaining`: Requests remaining in current window
  - `X-RateLimit-Reset`: Time when the rate limit resets

## Response Format

All API responses follow a consistent JSON format:

### Success Response

```json
{
  "success": true,
  "data": {
    // Response data
  },
  "meta": {
    "timestamp": "2025-01-06T00:00:00.000Z"
  }
}
```

### Error Response

```json
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  },
  "meta": {
    "timestamp": "2025-01-06T00:00:00.000Z"
  }
}
```

## Common Error Codes

| Code | HTTP Status | Description |
|------|-------------|-------------|
| `AUTHENTICATION_REQUIRED` | 401 | API key is missing or invalid |
| `RATE_LIMIT_EXCEEDED` | 429 | Too many requests, slow down |
| `ENDPOINT_NOT_FOUND` | 404 | The requested endpoint does not exist |
| `VALIDATION_ERROR` | 400 | Request parameters are invalid |
| `INTERNAL_ERROR` | 500 | Server error, please try again |

## API Endpoints

Total endpoints: **19**

### competitors

#### POST /api/v1/lotsintel/projects/:project_id/competitors

Add one competitor, or update the existing row when the domain is already in this project. Optional surfaces can be included. The same domain is never inserted twice.

**Tags:** intel, scout, agent

**Rate Limit:** 60 requests/minute

**Request Parameters:**

- `kind` (string, optional): 
- `name` (string, optional): 
- `domain` (string, optional): 
- `source` (string, optional): 
- `status` (string, optional): 
- `priority` (integer, optional): 
- `surfaces` (array, optional): 
- `project_id` (string, **required**): 
- `source_url` (string, optional): 
- `website_url` (string, optional): 
- `why_we_watch` (string, optional): 
- `positioning_note` (string, optional): 
- `check_interval_days` (integer, optional): 

**Example Request:**

```bash
curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project_id":"00000000-0000-0000-0000-000000000000"}' \
  https://intel.lotsmcp.com/api/v1/lotsintel/projects/:project_id/competitors
```

---

#### DELETE /api/v1/lotsintel/projects/:project_id/competitors/:competitor_id

Take a competitor off the watch. History stays. A later import or restore_competitor puts them back.

**Tags:** intel, scout, agent

**Rate Limit:** 60 requests/minute

**Request Parameters:**

- `project_id` (string, **required**): 
- `competitor_id` (string, **required**): 

**Example Request:**

```bash
curl -X DELETE \
  -H "X-API-Key: YOUR_API_KEY" \
  https://intel.lotsmcp.com/api/v1/lotsintel/projects/:project_id/competitors/:competitor_id
```

---

#### GET /api/v1/lotsintel/projects/:project_id/competitors/:competitor_id

Get one competitor, the active pages and accounts being watched, the latest observation on each, and signals that have not been sent.

**Tags:** intel, scout, agent

**Rate Limit:** 120 requests/minute

**Request Parameters:**

- `project_id` (string, **required**): 
- `competitor_id` (string, **required**): 

**Example Request:**

```bash
curl -X GET \
  -H "X-API-Key: YOUR_API_KEY" \
  https://intel.lotsmcp.com/api/v1/lotsintel/projects/:project_id/competitors/:competitor_id
```

---

#### POST /api/v1/lotsintel/projects/:project_id/competitors/import

Add or update up to 50 competitors in one call. Match is the domain. An archived domain is brought back when it is imported again. Each row reports created, updated, or rejected. Pass surfaces on a row to set what to watch; omit surfaces to leave existing pages and accounts untouched.

**Tags:** intel, scout, agent

**Rate Limit:** 20 requests/minute

**Request Parameters:**

- `project_id` (string, **required**): 
- `competitors` (array, **required**): 

**Example Request:**

```bash
curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project_id":"00000000-0000-0000-0000-000000000000","competitors":[]}' \
  https://intel.lotsmcp.com/api/v1/lotsintel/projects/:project_id/competitors/import
```

---

#### GET /api/v1/lotsintel/projects/:project_id/competitors

List competitors in a project. Filter with status (proposed, active, paused, archived), kind, or due=true. Archived competitors are omitted unless status=archived.

**Tags:** intel, scout, agent

**Rate Limit:** 120 requests/minute

**Request Parameters:**

- `due` (boolean, optional): 
- `kind` (string, optional): 
- `status` (string, optional): 
- `project_id` (string, **required**): 

**Example Request:**

```bash
curl -X GET \
  -H "X-API-Key: YOUR_API_KEY" \
  https://intel.lotsmcp.com/api/v1/lotsintel/projects/:project_id/competitors
```

---

#### POST /api/v1/lotsintel/projects/:project_id/competitors/:competitor_id/restore

Put an archived competitor back on the watch as active and due.

**Tags:** intel, scout, agent

**Rate Limit:** 60 requests/minute

**Request Parameters:**

- `project_id` (string, **required**): 
- `competitor_id` (string, **required**): 

**Example Request:**

```bash
curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project_id":"00000000-0000-0000-0000-000000000000","competitor_id":"00000000-0000-0000-0000-000000000000"}' \
  https://intel.lotsmcp.com/api/v1/lotsintel/projects/:project_id/competitors/:competitor_id/restore
```

---

#### PATCH /api/v1/lotsintel/projects/:project_id/competitors/:competitor_id

Change kind, priority, interval, website, status, or notes. Status here is proposed, active, or paused. Removing someone from the watch is archive_competitor.

**Tags:** intel, scout, agent

**Rate Limit:** 60 requests/minute

**Request Parameters:**

- `kind` (string, optional): 
- `name` (string, optional): 
- `domain` (string, optional): 
- `source` (string, optional): 
- `status` (string, optional): 
- `priority` (integer, optional): 
- `project_id` (string, **required**): 
- `source_url` (string, optional): 
- `website_url` (string, optional): 
- `why_we_watch` (string, optional): 
- `competitor_id` (string, **required**): 
- `positioning_note` (string, optional): 
- `check_interval_days` (integer, optional): 

**Example Request:**

```bash
curl -X PATCH \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project_id":"00000000-0000-0000-0000-000000000000","competitor_id":"00000000-0000-0000-0000-000000000000"}' \
  https://intel.lotsmcp.com/api/v1/lotsintel/projects/:project_id/competitors/:competitor_id
```

---

### observations

#### POST /api/v1/lotsintel/projects/:project_id/observations

Save what was seen on one surface. The first observation for that surface is a baseline and cannot by itself justify a signal. The same content is stored once and still counts as a completed check. Only active competitors can be checked.

**Tags:** intel, scout, agent

**Rate Limit:** 120 requests/minute

**Request Parameters:**

- `source` (string, optional): 
- `excerpt` (string, optional): 
- `payload` (object, optional): 
- `summary` (string, **required**): 
- `project_id` (string, **required**): 
- `source_url` (string, optional): 
- `surface_id` (string, **required**): 
- `external_ids` (array, optional): 
- `competitor_id` (string, **required**): 
- `idempotency_key` (string, optional): 

**Example Request:**

```bash
curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"summary":"example_summary","project_id":"00000000-0000-0000-0000-000000000000","surface_id":"00000000-0000-0000-0000-000000000000","competitor_id":"00000000-0000-0000-0000-000000000000"}' \
  https://intel.lotsmcp.com/api/v1/lotsintel/projects/:project_id/observations
```

---

#### POST /api/v1/lotsintel/projects/:project_id/surfaces/:surface_id/refresh

Read one saved social account through the existing research provider, store the observation, and dedupe posts by URL. The project can spend 20 provider calls per day. The first snapshot is a baseline. A repeat of the same feed does not create another observation.

**Tags:** intel, scout, agent

**Rate Limit:** 30 requests/minute

**Request Parameters:**

- `project_id` (string, **required**): 
- `surface_id` (string, **required**): 
- `competitor_id` (string, **required**): 

**Example Request:**

```bash
curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project_id":"00000000-0000-0000-0000-000000000000","surface_id":"00000000-0000-0000-0000-000000000000","competitor_id":"00000000-0000-0000-0000-000000000000"}' \
  https://intel.lotsmcp.com/api/v1/lotsintel/projects/:project_id/surfaces/:surface_id/refresh
```

---

### projects

#### POST /api/v1/lotsintel/projects

Create the product or project to watch, or return the existing project when this owner already used that name. A repeat does not overwrite the saved description or destinations.

**Tags:** intel, scout, agent

**Rate Limit:** 30 requests/minute

**Request Parameters:**

- `name` (string, **required**): 
- `description` (string, optional): 
- `website_url` (string, optional): 
- `destinations` (object, optional): 

**Example Request:**

```bash
curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"example_name"}' \
  https://intel.lotsmcp.com/api/v1/lotsintel/projects
```

---

#### GET /api/v1/lotsintel/projects/:project_id

Get one project plus counts of active competitors, competitors due for a check, and unsent signals.

**Tags:** intel, scout, agent

**Rate Limit:** 120 requests/minute

**Request Parameters:**

- `project_id` (string, **required**): 

**Example Request:**

```bash
curl -X GET \
  -H "X-API-Key: YOUR_API_KEY" \
  https://intel.lotsmcp.com/api/v1/lotsintel/projects/:project_id
```

---

#### GET /api/v1/lotsintel/projects

List the products this owner is watching.

**Tags:** intel, scout, agent

**Rate Limit:** 120 requests/minute

**Request Parameters:**


**Example Request:**

```bash
curl -X GET \
  -H "X-API-Key: YOUR_API_KEY" \
  https://intel.lotsmcp.com/api/v1/lotsintel/projects
```

---

#### PATCH /api/v1/lotsintel/projects/:project_id

Change the project name, website, description, or signal destinations. Destinations.emails receives signals. webhook_url, when set, must be https and is posted the same JSON.

**Tags:** intel, scout, agent

**Rate Limit:** 60 requests/minute

**Request Parameters:**

- `name` (string, optional): 
- `project_id` (string, **required**): 
- `description` (string, optional): 
- `website_url` (string, optional): 
- `destinations` (object, optional): 

**Example Request:**

```bash
curl -X PATCH \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project_id":"00000000-0000-0000-0000-000000000000"}' \
  https://intel.lotsmcp.com/api/v1/lotsintel/projects/:project_id
```

---

### signals

#### POST /api/v1/lotsintel/projects/:project_id/signals/:signal_id/dismiss

Keep a signal and do not send it. A sent signal cannot be dismissed.

**Tags:** intel, scout, agent

**Rate Limit:** 60 requests/minute

**Request Parameters:**

- `signal_id` (string, **required**): 
- `project_id` (string, **required**): 

**Example Request:**

```bash
curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"signal_id":"00000000-0000-0000-0000-000000000000","project_id":"00000000-0000-0000-0000-000000000000"}' \
  https://intel.lotsmcp.com/api/v1/lotsintel/projects/:project_id/signals/:signal_id/dismiss
```

---

#### GET /api/v1/lotsintel/projects/:project_id/signals

List signals for a project. status is unsent, sent, or dismissed. unsent means recorded and not yet delivered.

**Tags:** intel, scout, agent

**Rate Limit:** 120 requests/minute

**Request Parameters:**

- `status` (string, optional): 
- `project_id` (string, **required**): 
- `competitor_id` (string, optional): 

**Example Request:**

```bash
curl -X GET \
  -H "X-API-Key: YOUR_API_KEY" \
  https://intel.lotsmcp.com/api/v1/lotsintel/projects/:project_id/signals
```

---

#### POST /api/v1/lotsintel/projects/:project_id/signals

Record a competitive change. Pass observation ids from this competitor. At least one must be a later observation rather than a baseline. This does not send the signal.

**Tags:** intel, scout, agent

**Rate Limit:** 60 requests/minute

**Request Parameters:**

- `detail` (string, optional): 
- `headline` (string, **required**): 
- `confidence` (string, optional): 
- `project_id` (string, **required**): 
- `materiality` (string, **required**): 
- `signal_type` (string, **required**): 
- `competitor_id` (string, **required**): 
- `observation_ids` (array, **required**): 

**Example Request:**

```bash
curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"headline":"example_headline","project_id":"00000000-0000-0000-0000-000000000000","materiality":"example_materiality","signal_type":"example_signal_type","competitor_id":"00000000-0000-0000-0000-000000000000","observation_ids":[]}' \
  https://intel.lotsmcp.com/api/v1/lotsintel/projects/:project_id/signals
```

---

#### POST /api/v1/lotsintel/projects/:project_id/signals/:signal_id/send

Deliver one signal once to the project email addresses and optional webhook. A second call returns the original delivery and does not send again. Fails with NO_DESTINATIONS when the project has nowhere to send. A partial failure stays unsent so only the failed destinations are retried.

**Tags:** intel, scout, agent

**Rate Limit:** 30 requests/minute

**Request Parameters:**

- `signal_id` (string, **required**): 
- `project_id` (string, **required**): 

**Example Request:**

```bash
curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"signal_id":"00000000-0000-0000-0000-000000000000","project_id":"00000000-0000-0000-0000-000000000000"}' \
  https://intel.lotsmcp.com/api/v1/lotsintel/projects/:project_id/signals/:signal_id/send
```

---

### surfaces

#### PUT /api/v1/lotsintel/projects/:project_id/competitors/:competitor_id/surfaces

Replace the pages and social accounts watched for one competitor. Social platforms are twitter (use this for X), instagram, linkedin, linkedin_page, and threads. A homepage, pricing page, changelog, or blog needs a public url.

**Tags:** intel, scout, agent

**Rate Limit:** 60 requests/minute

**Request Parameters:**

- `surfaces` (array, **required**): 
- `project_id` (string, **required**): 
- `competitor_id` (string, **required**): 

**Example Request:**

```bash
curl -X PUT \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"surfaces":[],"project_id":"00000000-0000-0000-0000-000000000000","competitor_id":"00000000-0000-0000-0000-000000000000"}' \
  https://intel.lotsmcp.com/api/v1/lotsintel/projects/:project_id/competitors/:competitor_id/surfaces
```

---

### watch

#### GET /api/v1/lotsintel/projects/:project_id/watch-queue

Start every check run here. Returns unsent signals first, then at most 3 due competitors. Each competitor includes its surfaces and the latest observation, or needs_surfaces when nothing is being watched yet.

**Tags:** intel, scout, agent

**Rate Limit:** 120 requests/minute

**Request Parameters:**

- `project_id` (string, **required**): 

**Example Request:**

```bash
curl -X GET \
  -H "X-API-Key: YOUR_API_KEY" \
  https://intel.lotsmcp.com/api/v1/lotsintel/projects/:project_id/watch-queue
```

---

## Support

For questions or issues, please visit https://intel.lotsmcp.com/docs or contact our support team.

## SDK and Libraries

We provide official SDKs for popular programming languages:

- **JavaScript/TypeScript**: Coming soon
- **Python**: Coming soon
- **Go**: Coming soon

## Changelog

Stay updated with the latest API changes:

- Visit https://intel.lotsmcp.com/docs for the latest documentation
- Check our changelog for API updates and deprecations

---

*Documentation generated on 2026-10-11T00:08:59.969Z*