# Lots Team API Documentation

Base URL: `https://api.lots.team`

## Overview

Collect feedback, manage support and tasks, and share updates

## Authentication

All API requests require authentication using an API key. Include your API key in the request header:

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.lots.team/api/v1/lotsteam/endpoint
```

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

```bash
curl -H "X-API-Key: YOUR_API_KEY" \
  https://api.lots.team/api/v1/lotsteam/endpoint
```

### Getting an API Key

1. Log in to your account at https://api.lots.team/dashboard
2. Navigate to the API Keys section
3. Click "Create New API Key"
4. Copy and securely store your API key (it will only be shown once)

## 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: **25**

### Contact Messages

#### GET /api/v1/lotsteam/contact/:id/thread

Get a contact message with all replies in the thread

**Rate Limit:** 100 requests/minute

**Request Parameters:**

- `contact_message_id` (string, **required**): UUID of the support message. Get it from list_contact_messages.

**Example Request:**

```bash
curl -X GET \
  -H "X-API-Key: YOUR_API_KEY" \
  https://api.lots.team/api/v1/lotsteam/contact/:id/thread
```

---

### organizations

#### GET /api/v1/lotsteam/organizations/:id/members

Lists all members of an organization. IMPORTANT: Requires organization_id. Call lotsteam_list_organizations first to get the organization UUID.

**Rate Limit:** 60 requests/minute

**Request Parameters:**

- `limit` (number, optional): Max results
- `offset` (number, optional): Pagination offset
- `project_id` (string, optional): Organization ID (from list_organizations). Also accepts organization_id.
- `organization_id` (string, **required**): REQUIRED. The UUID of the organization whose members to list. Call lotsteam_list_organizations first if you do not have this value.

**Example Request:**

```bash
curl -X GET \
  -H "X-API-Key: YOUR_API_KEY" \
  https://api.lots.team/api/v1/lotsteam/organizations/:id/members
```

---

### General

#### GET /api/v1/lotsteam/funding

Check plan coverage, credit funding and current capacity rates. Plan coverage is used first; capacity beyond it is paid from the owner's credits automatically, charged daily (free credits first, then plan credits, then purchased). If credits run low, give the returned settings_url so the owner can top up or choose a plan.

**Rate Limit:** 100 requests/minute

**Request Parameters:**


**Example Request:**

```bash
curl -X GET \
  -H "X-API-Key: YOUR_API_KEY" \
  https://api.lots.team/api/v1/lotsteam/funding
```

---

#### POST /api/v1/lotsteam/changelog

Creates a new changelog entry in a project. IMPORTANT: Requires project_id. Call lotsteam_list_organizations first, then lotsteam_list_projects to get the project_id.

**Rate Limit:** 100 requests/minute

**Request Parameters:**

- `tag` (string, **required**): 
- `title` (string, **required**): 
- `task_id` (string, optional): 
- `project_id` (string, **required**): REQUIRED. The UUID of the project to create the changelog entry in. Call lotsteam_list_projects (with an organization_id) to get project UUIDs. If you do not have the organization_id, call lotsteam_list_organizations first.
- `description` (string, **required**): 
- `is_published` (boolean, optional): 
- `notify_requesters` (boolean, optional): Email the people whose posts are linked to this entry's task when it is first published. Off unless true. Ask the person before turning it on.

**Example Request:**

```bash
curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tag":"example_tag","title":"example_title","project_id":"00000000-0000-0000-0000-000000000000","description":"example_description"}' \
  https://api.lots.team/api/v1/lotsteam/changelog
```

---

#### POST /api/v1/lotsteam/feedback

Create a new post for a project. Posts can be feature requests, bug reports, announcements, discussions, or general feedback. Supports categories like feature request, bug report, improvement, announcement, discussion, question. Can set priority (low, normal, high, urgent), mark as pinned or announcement, and add tags.

**Rate Limit:** 100 requests/minute

**Request Parameters:**

- `tags` (array, optional): Array of tags for the post
- `email` (string, optional): Submitter email (for public submissions)
- `title` (string, **required**): Post title
- `category` (string, **required**): Category: feature (feature request), bug (bug report), improvement, announcement, discussion, question, other
- `priority` (string, optional): Priority level: low, normal, high, urgent
- `is_pinned` (boolean, optional): Whether to pin this post to the top
- `user_name` (string, optional): Submitter name (for public submissions)
- `project_id` (string, **required**): UUID of the project to create the post in
- `description` (string, **required**): Detailed description of the post
- `is_announcement` (boolean, optional): Mark as an announcement post

**Example Request:**

```bash
curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"example_title","category":"example_category","project_id":"00000000-0000-0000-0000-000000000000","description":"example_description"}' \
  https://api.lots.team/api/v1/lotsteam/feedback
```

---

#### POST /api/v1/lotsteam/post_comment

Add a comment to a post. Notifies all org members about the new comment.

**Rate Limit:** 100 requests/minute

**Request Parameters:**

- `content` (string, **required**): 
- `post_id` (string, **required**): UUID of the post.
- `is_admin` (boolean, optional): 
- `user_name` (string, optional): 
- `user_email` (string, optional): 

**Example Request:**

```bash
curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content":"example_content","post_id":"00000000-0000-0000-0000-000000000000"}' \
  https://api.lots.team/api/v1/lotsteam/post_comment
```

---

#### POST /api/v1/lotsteam/tasks

Creates a new task in a project. IMPORTANT: Requires project_id — call lotsteam_list_organizations → lotsteam_list_projects to get it. Supports roadmap fields: set is_roadmap=true to show the task on the public roadmap, optionally with eta_date and public_summary.

**Rate Limit:** 100 requests/minute

**Request Parameters:**

- `title` (string, **required**): 
- `status` (string, optional): 
- `goal_id` (string,null, optional): Optional goal UUID from the project Agent Team workspace. The goal must belong to the task project.
- `eta_date` (string, optional): Optional. Estimated completion date for roadmap display (ISO 8601 datetime string, e.g. '2025-12-31T00:00:00Z'). Only meaningful when is_roadmap is true.
- `priority` (string, optional): 
- `is_roadmap` (boolean, optional): Optional. Set to true to show this task on the public roadmap. When true, the task becomes publicly visible. Defaults to false.
- `project_id` (string, **required**): REQUIRED. The UUID of the project to create the task in. Call lotsteam_list_projects (with an organization_id) to get project UUIDs. If you do not have the organization_id, call lotsteam_list_organizations first.
- `assignee_id` (string, optional): Optional member UUID of the person responsible for the task.
- `description` (string, optional): 
- `feedback_id` (string, optional): 
- `public_summary` (string, optional): Optional. Public-facing description shown on the roadmap. If omitted and is_roadmap is true, the internal description is shown instead. Max 5000 characters.
- `review_required` (boolean, optional): When true, the task cannot be completed until the assigned reviewer approves it.
- `reviewer_user_id` (string,null, optional): Separate team member who must review the work before completion.

**Example Request:**

```bash
curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"example_title","project_id":"00000000-0000-0000-0000-000000000000"}' \
  https://api.lots.team/api/v1/lotsteam/tasks
```

---

#### POST /api/v1/lotsteam/task_comment

Adds a comment to a task. IMPORTANT: Requires task_id. Call lotsteam_list_organizations → lotsteam_list_projects → lotsteam_list_tasks to get the task_id.

**Rate Limit:** 100 requests/minute

**Request Parameters:**

- `content` (string, **required**): 
- `task_id` (string, **required**): REQUIRED. The UUID of the task to comment on. Call lotsteam_list_tasks (with a project_id or organization_id) to get task UUIDs.
- `is_admin` (boolean, optional): 
- `user_name` (string, optional): 
- `user_email` (string, optional): 

**Example Request:**

```bash
curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content":"example_content","task_id":"00000000-0000-0000-0000-000000000000"}' \
  https://api.lots.team/api/v1/lotsteam/task_comment
```

---

#### GET /api/v1/lotsteam/changelog/:id

Get a specific changelog entry by ID.

**Rate Limit:** 100 requests/minute

**Request Parameters:**

- `changelog_id` (string, **required**): REQUIRED. The UUID of the changelog entry. Call lotsteam_list_changelogs (with a project_id or organization_id) to get changelog UUIDs.

**Example Request:**

```bash
curl -X GET \
  -H "X-API-Key: YOUR_API_KEY" \
  https://api.lots.team/api/v1/lotsteam/changelog/:id
```

---

#### GET /api/v1/lotsteam/feedback/:id

Get detailed information about a specific post including title, description, category, status, priority, pinned status, announcement status, tags, upvotes count, comments count, and timestamps.

**Rate Limit:** 100 requests/minute

**Request Parameters:**

- `post_id` (string, **required**): UUID of the post to retrieve

**Example Request:**

```bash
curl -X GET \
  -H "X-API-Key: YOUR_API_KEY" \
  https://api.lots.team/api/v1/lotsteam/feedback/:id
```

---

#### GET /api/v1/lotsteam/projects/:id

Get detailed information for a project. User must have access to the project via their organization membership.

**Rate Limit:** 100 requests/minute

**Request Parameters:**

- `project_id` (string, **required**): REQUIRED. The UUID of the project. Call lotsteam_list_projects (with an organization_id) to get project UUIDs.

**Example Request:**

```bash
curl -X GET \
  -H "X-API-Key: YOUR_API_KEY" \
  https://api.lots.team/api/v1/lotsteam/projects/:id
```

---

#### GET /api/v1/lotsteam/tasks/:id

Get detailed information about a specific task.

**Rate Limit:** 100 requests/minute

**Request Parameters:**

- `task_id` (string, **required**): REQUIRED. The UUID of the task. Call lotsteam_list_tasks (with a project_id or organization_id) to get task UUIDs.

**Example Request:**

```bash
curl -X GET \
  -H "X-API-Key: YOUR_API_KEY" \
  https://api.lots.team/api/v1/lotsteam/tasks/:id
```

---

#### GET /api/v1/lotsteam/changelog

List changelog entries with filtering options.

**Rate Limit:** 100 requests/minute

**Request Parameters:**

- `tag` (string, optional): 
- `limit` (integer, optional): 
- `offset` (integer, optional): 
- `published` (boolean, optional): 
- `project_id` (string, optional): The UUID of a specific project to list changelog entries for. Either project_id or organization_id is required. Call lotsteam_list_projects (with an organization_id) to get project UUIDs.
- `organization_id` (string, optional): The UUID of the organization to list changelog entries across all accessible projects. Either project_id or organization_id is required.

**Example Request:**

```bash
curl -X GET \
  -H "X-API-Key: YOUR_API_KEY" \
  https://api.lots.team/api/v1/lotsteam/changelog
```

---

#### GET /api/v1/lotsteam/contact

Lists contact/support messages for a project or organization. IMPORTANT: Requires project_id or organization_id. Call lotsteam_list_organizations first, then lotsteam_list_projects to get a project_id.

**Rate Limit:** 100 requests/minute

**Request Parameters:**

- `limit` (integer, optional): 
- `offset` (integer, optional): 
- `status` (string, optional): 
- `project_id` (string, optional): The UUID of a specific project to list contact messages for. Either project_id or organization_id is required. Call lotsteam_list_projects (with an organization_id) to get project UUIDs.
- `organization_id` (string, optional): The UUID of the organization to list contact messages across all accessible projects. Either project_id or organization_id is required.

**Example Request:**

```bash
curl -X GET \
  -H "X-API-Key: YOUR_API_KEY" \
  https://api.lots.team/api/v1/lotsteam/contact
```

---

#### GET /api/v1/lotsteam/linked_posts

Get all posts linked to a specific task. Returns posts that are connected to the task for tracking which posts are being addressed by the task.

**Rate Limit:** 100 requests/minute

**Request Parameters:**

- `task_id` (string, **required**): UUID of the task to get linked posts for

**Example Request:**

```bash
curl -X GET \
  -H "X-API-Key: YOUR_API_KEY" \
  https://api.lots.team/api/v1/lotsteam/linked_posts
```

---

#### GET /api/v1/lotsteam/organizations

List all organizations for the authenticated user.

**Rate Limit:** 100 requests/minute

**Request Parameters:**

- `limit` (integer, optional): 
- `offset` (integer, optional): 

**Example Request:**

```bash
curl -X GET \
  -H "X-API-Key: YOUR_API_KEY" \
  https://api.lots.team/api/v1/lotsteam/organizations
```

---

#### GET /api/v1/lotsteam/post_comments

List all comments for a post.

**Rate Limit:** 100 requests/minute

**Request Parameters:**

- `limit` (integer, optional): 
- `offset` (integer, optional): 
- `post_id` (string, **required**): UUID of the post.

**Example Request:**

```bash
curl -X GET \
  -H "X-API-Key: YOUR_API_KEY" \
  https://api.lots.team/api/v1/lotsteam/post_comments
```

---

#### GET /api/v1/lotsteam/feedback

List all posts for a project with filtering and sorting. Filter by category (feature, bug, improvement, announcement, discussion, question), status (open, in-progress, resolved, closed, published), priority (low, normal, high, urgent), pinned status, or announcement status. Sort by recent (creation date) or popular (upvotes).

**Rate Limit:** 100 requests/minute

**Request Parameters:**

- `sort` (string, optional): Sort by: recent (creation date) or popular (upvotes count)
- `limit` (integer, optional): Number of posts to return
- `offset` (integer, optional): Pagination offset
- `status` (string, optional): Filter by status
- `category` (string, optional): Filter by category
- `priority` (string, optional): Filter by priority
- `is_pinned` (boolean, optional): Filter by pinned status
- `project_id` (string, optional): The UUID of a specific project to list posts for. Either project_id or organization_id is required. Call lotsteam_list_projects (with an organization_id) to get project UUIDs.
- `is_announcement` (boolean, optional): Filter by announcement status
- `organization_id` (string, optional): The UUID of the organization to list posts across all accessible projects. Either project_id or organization_id is required.

**Example Request:**

```bash
curl -X GET \
  -H "X-API-Key: YOUR_API_KEY" \
  https://api.lots.team/api/v1/lotsteam/feedback
```

---

#### GET /api/v1/lotsteam/projects

Lists all projects the authenticated user has access to within a specific organization. IMPORTANT: Requires organization_id. If you do not have it, call lotsteam_list_organizations first to get the list of organizations and their IDs.

**Rate Limit:** 100 requests/minute

**Request Parameters:**

- `limit` (integer, optional): 
- `offset` (integer, optional): 
- `project_id` (string, optional): Organization ID (alias for org-scoped list)
- `organization_id` (string, **required**): REQUIRED. The UUID of the organization to list projects for. Call lotsteam_list_organizations first if you do not have this value.

**Example Request:**

```bash
curl -X GET \
  -H "X-API-Key: YOUR_API_KEY" \
  https://api.lots.team/api/v1/lotsteam/projects
```

---

#### GET /api/v1/lotsteam/task_comments

Lists comments on a specific task. IMPORTANT: Requires task_id. Call lotsteam_list_organizations → lotsteam_list_projects → lotsteam_list_tasks to get the task_id.

**Rate Limit:** 100 requests/minute

**Request Parameters:**

- `limit` (integer, optional): 
- `offset` (integer, optional): 
- `task_id` (string, **required**): REQUIRED. The UUID of the task whose comments to list. Call lotsteam_list_tasks (with a project_id or organization_id) to get task UUIDs.

**Example Request:**

```bash
curl -X GET \
  -H "X-API-Key: YOUR_API_KEY" \
  https://api.lots.team/api/v1/lotsteam/task_comments
```

---

#### GET /api/v1/lotsteam/tasks

Lists tasks filtered by project or organization. Requires either project_id for a single project or organization_id for all accessible projects. Supports status, assignee_id, mine_only, priority, search, limit, offset, and sort.

**Rate Limit:** 100 requests/minute

**Request Parameters:**

- `sort` (string, optional): 
- `limit` (integer, optional): 
- `offset` (integer, optional): 
- `search` (string, optional): Free-text search across task title and description.
- `status` (string, optional): 
- `priority` (string, optional): 
- `mine_only` (boolean, optional): When true, return tasks assigned to or created by the authenticated user.
- `project_id` (string, optional): The UUID of a specific project to list tasks for. Either project_id or organization_id is required.
- `assignee_id` (string, optional): 
- `organization_id` (string, optional): The UUID of the organization to list tasks across all accessible projects. Either project_id or organization_id is required.

**Example Request:**

```bash
curl -X GET \
  -H "X-API-Key: YOUR_API_KEY" \
  https://api.lots.team/api/v1/lotsteam/tasks
```

---

#### POST /api/v1/lotsteam/contact/:id/reply

Send a reply to a contact message.

**Rate Limit:** 100 requests/minute

**Request Parameters:**

- `reply_message` (string, **required**): 
- `contact_message_id` (string, **required**): 

**Example Request:**

```bash
curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reply_message":"example_reply_message","contact_message_id":"00000000-0000-0000-0000-000000000000"}' \
  https://api.lots.team/api/v1/lotsteam/contact/:id/reply
```

---

#### PUT /api/v1/lotsteam/changelog/:id

Update an existing changelog entry.

**Rate Limit:** 100 requests/minute

**Request Parameters:**

- `tag` (string, optional): 
- `title` (string, optional): 
- `description` (string, optional): 
- `changelog_id` (string, **required**): REQUIRED. The UUID of the changelog entry. Call lotsteam_list_changelogs (with a project_id or organization_id) to get changelog UUIDs.
- `is_published` (boolean, optional): 
- `notify_requesters` (boolean, optional): Email the people whose posts are linked to this entry's task when it is first published. Off unless true. Ask the person before turning it on.

**Example Request:**

```bash
curl -X PUT \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"changelog_id":"00000000-0000-0000-0000-000000000000"}' \
  https://api.lots.team/api/v1/lotsteam/changelog/:id
```

---

#### PUT /api/v1/lotsteam/feedback/:id

Update an existing post. Can update title, description, category, status, priority, pinned status, announcement status, and tags. Use this to change post status (open, in-progress, resolved, closed, published), set priority, pin/unpin posts, mark as announcement, or add/remove tags.

**Rate Limit:** 100 requests/minute

**Request Parameters:**

- `tags` (array, optional): Updated tags array
- `title` (string, optional): Updated post title
- `status` (string, optional): Updated status: open, in-progress, resolved, closed, published
- `post_id` (string, **required**): UUID of the post to update
- `category` (string, optional): Updated category
- `priority` (string, optional): Updated priority: low, normal, high, urgent
- `is_pinned` (boolean, optional): Set to true to pin post, false to unpin
- `description` (string, optional): Updated description
- `is_announcement` (boolean, optional): Set to true to mark as announcement, false to remove announcement status

**Example Request:**

```bash
curl -X PUT \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"post_id":"00000000-0000-0000-0000-000000000000"}' \
  https://api.lots.team/api/v1/lotsteam/feedback/:id
```

---

#### PUT /api/v1/lotsteam/tasks/:id

Updates an existing task. IMPORTANT: Requires task_id — call lotsteam_list_tasks first to get it. Supports roadmap fields: set is_roadmap=true to show the task on the public roadmap, with optional eta_date and public_summary.

**Rate Limit:** 100 requests/minute

**Request Parameters:**

- `title` (string, optional): 
- `status` (string, optional): 
- `goal_id` (string,null, optional): Optional goal UUID from the project Agent Team workspace. The goal must belong to the task project.
- `task_id` (string, **required**): REQUIRED. The UUID of the task. Call lotsteam_list_tasks (with a project_id or organization_id) to get task UUIDs.
- `eta_date` (string, optional): Optional. Estimated completion date for roadmap display (ISO 8601 datetime string, e.g. '2025-12-31T00:00:00Z'). Set to null to clear. Only meaningful when is_roadmap is true.
- `priority` (string, optional): 
- `is_roadmap` (boolean, optional): Optional. Set to true to show this task on the public roadmap, false to hide it. When true, the task becomes publicly visible.
- `assignee_id` (string, optional): Optional member UUID of the person responsible for the task.
- `description` (string, optional): 
- `public_summary` (string, optional): Optional. Public-facing description shown on the roadmap. Set to null to clear and fall back to the internal description. Max 5000 characters.
- `review_required` (boolean, optional): When true, the task cannot be completed until the assigned reviewer approves it.
- `reviewer_user_id` (string,null, optional): Separate team member who must review the work before completion.

**Example Request:**

```bash
curl -X PUT \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task_id":"00000000-0000-0000-0000-000000000000"}' \
  https://api.lots.team/api/v1/lotsteam/tasks/:id
```

---

## Support

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

---

*Documentation generated on 2026-10-09T05:51:10.158Z*