# Lots Engage API Documentation

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

## Overview

Internal community-thread ledger for Ambassador and later venue agents. Not a customer product.

## Authentication

AI agents: add `https://engage.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://engage.lotsmcp.com/api/v1/lotsengage/endpoint
```

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

```bash
curl -H "X-API-Key: YOUR_API_KEY" \
  https://engage.lotsmcp.com/api/v1/lotsengage/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 Engage, 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://engage.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: **14**

### opportunities

#### GET /api/v1/lotsengage/projects/:project_id/opportunities/:opportunity_id

Get one thread, its current reply, and whether it was posted.

**Tags:** engage, ambassador, agent

**Rate Limit:** 120 requests/minute

**Request Parameters:**

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

**Example Request:**

```bash
curl -X GET \
  -H "X-API-Key: YOUR_API_KEY" \
  https://engage.lotsmcp.com/api/v1/lotsengage/projects/:project_id/opportunities/:opportunity_id
```

---

#### POST /api/v1/lotsengage/projects/:project_id/opportunities/import

File up to 50 threads. Each row reports created, updated, or rejected. A repeated URL updates the same thread and does not wipe a reply already handed, approved, or posted.

**Tags:** engage, ambassador, agent

**Rate Limit:** 20 requests/minute

**Request Parameters:**

- `project_id` (string, **required**): 
- `opportunities` (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","opportunities":[]}' \
  https://engage.lotsmcp.com/api/v1/lotsengage/projects/:project_id/opportunities/import
```

---

#### GET /api/v1/lotsengage/projects/:project_id/opportunities

List threads in a project. Filter with platform, fit, or status.

**Tags:** engage, ambassador, agent

**Rate Limit:** 120 requests/minute

**Request Parameters:**

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

**Example Request:**

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

---

#### POST /api/v1/lotsengage/projects/:project_id/opportunities

File one community thread. The same URL updates the same row and does not reopen a thread that is already handed, approved, or posted. platform is reddit, quora, hackernews, forum, facebook_group, or other. fit is strong, partial, or poor. rules is answer_only, disclose_ok, promo_banned, or unknown.

**Tags:** engage, ambassador, agent

**Rate Limit:** 60 requests/minute

**Request Parameters:**

- `fit` (string, optional): 
- `url` (string, **required**): 
- `rules` (string, optional): 
- `title` (string, **required**): 
- `author` (string, optional): 
- `status` (string, optional): 
- `excerpt` (string, optional): 
- `asked_at` (string, optional): 
- `platform` (string, **required**): 
- `community` (string, optional): 
- `project_id` (string, **required**): 
- `external_id` (string, optional): 
- `skip_reason` (string, optional): 
- `why_it_fits` (string, optional): 
- `rules_source_url` (string, optional): 

**Example Request:**

```bash
curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"example_url","title":"example_title","platform":"example_platform","project_id":"00000000-0000-0000-0000-000000000000"}' \
  https://engage.lotsmcp.com/api/v1/lotsengage/projects/:project_id/opportunities
```

---

#### POST /api/v1/lotsengage/projects/:project_id/opportunities/:opportunity_id/skip

Mark a thread as not worth an answer. A skipped thread is not drafted again. reason is required.

**Tags:** engage, ambassador, agent

**Rate Limit:** 60 requests/minute

**Request Parameters:**

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

**Example Request:**

```bash
curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"example_reason","project_id":"00000000-0000-0000-0000-000000000000","opportunity_id":"00000000-0000-0000-0000-000000000000"}' \
  https://engage.lotsmcp.com/api/v1/lotsengage/projects/:project_id/opportunities/:opportunity_id/skip
```

---

### projects

#### POST /api/v1/lotsengage/projects

Create the product to represent in communities, or return the existing project when this owner already used that name. A repeat does not overwrite the saved offer or disclosure line.

**Tags:** engage, ambassador, agent

**Rate Limit:** 30 requests/minute

**Request Parameters:**

- `name` (string, **required**): 
- `website_url` (string, optional): 
- `offer_summary` (string, optional): 
- `disclosure_line` (string, optional): 

**Example Request:**

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

---

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

Get one product plus counts of ready replies, handed replies, approved replies, and posted threads.

**Tags:** engage, ambassador, 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://engage.lotsmcp.com/api/v1/lotsengage/projects/:project_id
```

---

#### GET /api/v1/lotsengage/projects

List the products this owner represents in communities.

**Tags:** engage, ambassador, agent

**Rate Limit:** 120 requests/minute

**Request Parameters:**


**Example Request:**

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

---

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

Change the product name, site, offer summary, or disclosure line.

**Tags:** engage, ambassador, agent

**Rate Limit:** 60 requests/minute

**Request Parameters:**

- `name` (string, optional): 
- `project_id` (string, **required**): 
- `website_url` (string, optional): 
- `offer_summary` (string, optional): 
- `disclosure_line` (string, 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://engage.lotsmcp.com/api/v1/lotsengage/projects/:project_id
```

---

### queue

#### GET /api/v1/lotsengage/projects/:project_id/queue

Start every community run here. Returns replies handed to the user, replies approved but not posted, ready replies not yet handed, then at most 3 found threads worth drafting. Skipped, declined, posted, and poor-fit threads are omitted.

**Tags:** engage, ambassador, 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://engage.lotsmcp.com/api/v1/lotsengage/projects/:project_id/queue
```

---

### replies

#### POST /api/v1/lotsengage/projects/:project_id/opportunities/:opportunity_id/handed

Record that the current ready reply was given to the user. reply_id, when sent, must be that current reply.

**Tags:** engage, ambassador, agent

**Rate Limit:** 60 requests/minute

**Request Parameters:**

- `reply_id` (string, optional): 
- `project_id` (string, **required**): 
- `opportunity_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","opportunity_id":"00000000-0000-0000-0000-000000000000"}' \
  https://engage.lotsmcp.com/api/v1/lotsengage/projects/:project_id/opportunities/:opportunity_id/handed
```

---

#### POST /api/v1/lotsengage/projects/:project_id/opportunities/:opportunity_id/posted

Record the live URL after the reply is public. posted_by=agent is rejected unless this reply was approved. posted_by=user records a post the person made. A second call returns the original URL.

**Tags:** engage, ambassador, agent

**Rate Limit:** 60 requests/minute

**Request Parameters:**

- `posted_by` (string, optional): 
- `posted_url` (string, **required**): 
- `project_id` (string, **required**): 
- `opportunity_id` (string, **required**): 

**Example Request:**

```bash
curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"posted_url":"example_posted_url","project_id":"00000000-0000-0000-0000-000000000000","opportunity_id":"00000000-0000-0000-0000-000000000000"}' \
  https://engage.lotsmcp.com/api/v1/lotsengage/projects/:project_id/opportunities/:opportunity_id/posted
```

---

#### POST /api/v1/lotsengage/projects/:project_id/opportunities/:opportunity_id/decision

Record the user's decision on the current ready reply. decision is approved or declined.

**Tags:** engage, ambassador, agent

**Rate Limit:** 60 requests/minute

**Request Parameters:**

- `decision` (string, **required**): 
- `reply_id` (string, optional): 
- `project_id` (string, **required**): 
- `opportunity_id` (string, **required**): 

**Example Request:**

```bash
curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"decision":"example_decision","project_id":"00000000-0000-0000-0000-000000000000","opportunity_id":"00000000-0000-0000-0000-000000000000"}' \
  https://engage.lotsmcp.com/api/v1/lotsengage/projects/:project_id/opportunities/:opportunity_id/decision
```

---

#### POST /api/v1/lotsengage/projects/:project_id/opportunities/:opportunity_id/replies

Save the prepared reply for one thread. A product mention requires discloses_ownership and the project disclosure line. promo_banned rejects a product mention. The previous ready reply is superseded.

**Tags:** engage, ambassador, agent

**Rate Limit:** 60 requests/minute

**Request Parameters:**

- `body` (string, **required**): 
- `status` (string, optional): 
- `project_id` (string, **required**): 
- `opportunity_id` (string, **required**): 
- `mentions_product` (boolean, optional): 
- `discloses_ownership` (boolean, optional): 

**Example Request:**

```bash
curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"body":"example_body","project_id":"00000000-0000-0000-0000-000000000000","opportunity_id":"00000000-0000-0000-0000-000000000000"}' \
  https://engage.lotsmcp.com/api/v1/lotsengage/projects/:project_id/opportunities/:opportunity_id/replies
```

---

## Support

For questions or issues, please visit https://engage.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://engage.lotsmcp.com/docs for the latest documentation
- Check our changelog for API updates and deprecations

---

*Documentation generated on 2026-10-11T00:07:57.522Z*