Lots Agent LogoLotsAgent

API Documentation

Complete reference for the LotsAgent REST API

Quick Start

1. Create an API Key

Go to Settings and create a site-level API key with the scopes you need.

2. Make Your First Request

curl -X GET https://lotsagent.com/api/v1/agents \
  -H "Authorization: Bearer YOUR_API_KEY"

Authentication

All API requests require authentication using a Bearer token in the Authorization header.

Authorization: Bearer YOUR_API_KEY

API Key Scopes:

  • site:readList and view resources
  • site:writeCreate and update resources
  • site:adminDelete resources and manage settings
  • site:executeExecute agents and run operations

Base URL

https://lotsagent.com/api/v1
GET/api/v1/agents
site:read

List all agents

Response:

{
  "agents": [
    {
      "id": "uuid",
      "name": "My Agent",
      "description": "Agent description",
      "status": "active",
      "model": "gpt-4o",
      "total_requests": 42,
      "created_at": "2025-01-01T00:00:00Z"
    }
  ],
  "total": 1
}
POST/api/v1/agents
site:write

Create a new agent

Request Body:

{
  "name": "My Agent",
  "description": "Agent description",
  "instructions": "You are a helpful assistant",
  "model": "gpt-4o",
  "temperature": 0.7,
  "max_tokens": 2000
}

Response:

{
  "id": "uuid",
  "name": "My Agent",
  "slug": "my-agent",
  "created_at": "2025-01-01T00:00:00Z"
}
GET/api/v1/agents/{agentId}
site:read

Get agent details

Response:

{
  "id": "uuid",
  "name": "My Agent",
  "description": "Agent description",
  "instructions": "You are a helpful assistant",
  "model": "gpt-4o",
  "temperature": 0.7,
  "status": "active"
}
PATCH/api/v1/agents/{agentId}
site:write

Update an agent

Request Body:

{
  "name": "Updated Name",
  "description": "Updated description",
  "temperature": 0.8
}

Response:

{
  "id": "uuid",
  "name": "Updated Name",
  "updated_at": "2025-01-01T00:00:00Z"
}
DELETE/api/v1/agents/{agentId}
site:admin

Delete an agent

Response:

{
  "success": true
}
POST/api/v1/agents/{agentId}/execute
site:execute

Execute an agent (chat or task mode)

Request Body:

{
  "message": "Hello, how are you?",
  "mode": "chat",
  "session_id": "optional-session-id",
  "model": "gpt-4o"
}

Response:

// Streaming response (SSE format)
data: {"type":"text-delta","delta":"Hello!"}
data: {"type":"text-delta","delta":" I'm"}
data: {"type":"text-delta","delta":" doing"}
data: {"type":"text-delta","delta":" well!"}
data: [DONE]

Error Handling

The API uses standard HTTP status codes and returns errors in JSON format.

400 Bad Request
{
  "error": "Validation error",
  "details": "Invalid input parameters"
}
401 Unauthorized
{
  "error": "Unauthorized",
  "details": "Invalid or missing API key"
}
404 Not Found
{
  "error": "Not found",
  "details": "Resource not found"
}

Rate Limiting

API requests are rate limited to ensure fair usage. Current limits: