LVNGDocs
API ReferenceSDKslvng.ai

Agents API

Agents are configurable AI entities with custom system prompts, model selection, capabilities, and tool access. They can be started, stopped, duplicated, and messaged directly. Agents are scoped to the authenticated user but can be shared via the isPublic flag. All endpoints require JWT authentication and are rate-limited to 100 requests per minute.

Base path: /api/v2/agents

Agent CRUD

Create, retrieve, update, and delete agents. Ownership checks are enforced on update and delete operations. Public agents are readable by anyone.

POST/api/v2/agentsAuthenticated

Create a new AI agent with custom configuration.

Body Parameters

namestringrequired

Display name for the agent.

descriptionstring

Brief description of purpose and capabilities.

avatarstring

URL to an avatar image.

systemPromptstring

System prompt defining agent behavior and constraints.

modelstring

AI model identifier (e.g. claude-sonnet, claude-haiku, claude-opus).

temperaturenumber

Sampling temperature (0.0 to 1.0).

capabilitiesobject

Capabilities configuration object.

metadataobject

Arbitrary metadata attached to the agent.

tagsstring[]

Array of tags for categorization and filtering.

workspaceIdstring

UUID of the workspace to scope this agent to.

isPublicboolean

Whether the agent is visible to all users.

Request

cURL
400">curl -X 400">POST https:400">class="text-zinc-500">//api.lvng.ai/api/v2/agents \
  -H 400">class="text-emerald-400">"Authorization: Bearer YOUR_JWT_TOKEN" \
  -H 400">class="text-emerald-400">"Content-Type: application/json" \
  -d '{
    400">class="text-emerald-400">"name": 400">class="text-emerald-400">"Data Analyst",
    400">class="text-emerald-400">"description": 400">class="text-emerald-400">"Analyzes datasets and produces reports with statistical insights.",
    400">class="text-emerald-400">"systemPrompt": 400">class="text-emerald-400">"You are a senior data analyst. Analyze data thoroughly and provide clear statistical insights.",
    400">class="text-emerald-400">"model": 400">class="text-emerald-400">"claude-sonnet",
    400">class="text-emerald-400">"temperature": 0.3,
    400">class="text-emerald-400">"capabilities": {
      400">class="text-emerald-400">"code_interpreter": true,
      400">class="text-emerald-400">"file_analysis": true
    },
    400">class="text-emerald-400">"tags": [400">class="text-emerald-400">"analytics", 400">class="text-emerald-400">"reporting"],
    400">class="text-emerald-400">"isPublic": false
  }'

Response 201

{
  400">class="text-emerald-400">"success": true,
  400">class="text-emerald-400">"agent": {
    400">class="text-emerald-400">"id": 400">class="text-emerald-400">"550e8400-e29b-41d4-a716-446655440000",
    400">class="text-emerald-400">"name": 400">class="text-emerald-400">"Data Analyst",
    400">class="text-emerald-400">"description": 400">class="text-emerald-400">"Analyzes datasets and produces reports with statistical insights.",
    400">class="text-emerald-400">"avatar": null,
    400">class="text-emerald-400">"systemPrompt": 400">class="text-emerald-400">"You are a senior data analyst. Analyze data thoroughly and provide clear statistical insights.",
    400">class="text-emerald-400">"model": 400">class="text-emerald-400">"claude-sonnet",
    400">class="text-emerald-400">"temperature": 0.3,
    400">class="text-emerald-400">"capabilities": {
      400">class="text-emerald-400">"code_interpreter": true,
      400">class="text-emerald-400">"file_analysis": true
    },
    400">class="text-emerald-400">"metadata": {},
    400">class="text-emerald-400">"tags": [400">class="text-emerald-400">"analytics", 400">class="text-emerald-400">"reporting"],
    400">class="text-emerald-400">"status": 400">class="text-emerald-400">"inactive",
    400">class="text-emerald-400">"isPublic": false,
    400">class="text-emerald-400">"user_id": 400">class="text-emerald-400">"a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
    400">class="text-emerald-400">"created_at": 400">class="text-emerald-400">"2026-03-19T16:00:00.000Z",
    400">class="text-emerald-400">"updated_at": 400">class="text-emerald-400">"2026-03-19T16:00:00.000Z"
  }
}
GET/api/v2/agentsAuthenticated

List agents owned by the user. Supports search, filtering by status/tags, and pagination.

Query Parameters

searchstring

Search term matched against name and description (ilike).

workspaceIdstring

Filter by workspace UUID.

statusstring

Filter by status: active, inactive, archived.

tagsstring

Comma-separated tags to filter by (uses contains).

includePublicboolean

Include public agents from other users.

limitinteger

Maximum agents to return.

offsetinteger

Number of agents to skip.

Request

cURL
400">curl -X 400">GET 400">class="text-emerald-400">"https:400">class="text-zinc-500">//api.lvng.ai/api/v2/agents?search=analyst&status=active&limit=25" \
  -H 400">class="text-emerald-400">"Authorization: Bearer YOUR_JWT_TOKEN"

Response 200

{
  400">class="text-emerald-400">"success": true,
  400">class="text-emerald-400">"agents": [
    {
      400">class="text-emerald-400">"id": 400">class="text-emerald-400">"550e8400-e29b-41d4-a716-446655440000",
      400">class="text-emerald-400">"name": 400">class="text-emerald-400">"Data Analyst",
      400">class="text-emerald-400">"description": 400">class="text-emerald-400">"Analyzes datasets and produces reports with statistical insights.",
      400">class="text-emerald-400">"model": 400">class="text-emerald-400">"claude-sonnet",
      400">class="text-emerald-400">"status": 400">class="text-emerald-400">"active",
      400">class="text-emerald-400">"capabilities": {
        400">class="text-emerald-400">"code_interpreter": true,
        400">class="text-emerald-400">"file_analysis": true
      },
      400">class="text-emerald-400">"tags": [400">class="text-emerald-400">"analytics", 400">class="text-emerald-400">"reporting"],
      400">class="text-emerald-400">"isPublic": false,
      400">class="text-emerald-400">"created_at": 400">class="text-emerald-400">"2026-03-19T16:00:00.000Z"
    }
  ],
  400">class="text-emerald-400">"total": 1,
  400">class="text-emerald-400">"limit": 25,
  400">class="text-emerald-400">"offset": 0
}
GET/api/v2/agents/:idAuthenticated

Get full agent details. Returns if user is owner or agent is public.

Path Parameters

idstringrequired

UUID of the agent.

Request

cURL
400">curl -X 400">GET https:400">class="text-zinc-500">//api.lvng.ai/api/v2/agents/550e8400-e29b-41d4-a716-446655440000 \
  -H 400">class="text-emerald-400">"Authorization: Bearer YOUR_JWT_TOKEN"

Response 200

{
  400">class="text-emerald-400">"success": true,
  400">class="text-emerald-400">"agent": {
    400">class="text-emerald-400">"id": 400">class="text-emerald-400">"550e8400-e29b-41d4-a716-446655440000",
    400">class="text-emerald-400">"name": 400">class="text-emerald-400">"Data Analyst",
    400">class="text-emerald-400">"description": 400">class="text-emerald-400">"Analyzes datasets and produces reports with statistical insights.",
    400">class="text-emerald-400">"avatar": null,
    400">class="text-emerald-400">"systemPrompt": 400">class="text-emerald-400">"You are a senior data analyst. Analyze data thoroughly and provide clear statistical insights.",
    400">class="text-emerald-400">"model": 400">class="text-emerald-400">"claude-sonnet",
    400">class="text-emerald-400">"temperature": 0.3,
    400">class="text-emerald-400">"capabilities": {
      400">class="text-emerald-400">"code_interpreter": true,
      400">class="text-emerald-400">"file_analysis": true
    },
    400">class="text-emerald-400">"metadata": {},
    400">class="text-emerald-400">"tags": [400">class="text-emerald-400">"analytics", 400">class="text-emerald-400">"reporting"],
    400">class="text-emerald-400">"status": 400">class="text-emerald-400">"active",
    400">class="text-emerald-400">"isPublic": false,
    400">class="text-emerald-400">"user_id": 400">class="text-emerald-400">"a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
    400">class="text-emerald-400">"created_at": 400">class="text-emerald-400">"2026-03-19T16:00:00.000Z",
    400">class="text-emerald-400">"updated_at": 400">class="text-emerald-400">"2026-03-19T16:30:00.000Z"
  }
}
PUT/api/v2/agents/:idAuthenticated

Update agent configuration. Requires ownership.

Path Parameters

idstringrequired

UUID of the agent.

Body Parameters

namestring

Updated display name.

descriptionstring

Updated description.

avatarstring

Updated avatar URL.

systemPromptstring

Updated system prompt.

modelstring

Updated model identifier.

temperaturenumber

Updated temperature.

capabilitiesobject

Updated capabilities.

metadataobject

Updated metadata.

tagsstring[]

Updated tags.

isPublicboolean

Updated visibility.

statusstring

Updated status.

Request

cURL
400">curl -X 400">PUT https:400">class="text-zinc-500">//api.lvng.ai/api/v2/agents/550e8400-e29b-41d4-a716-446655440000 \
  -H 400">class="text-emerald-400">"Authorization: Bearer YOUR_JWT_TOKEN" \
  -H 400">class="text-emerald-400">"Content-Type: application/json" \
  -d '{
    400">class="text-emerald-400">"name": 400">class="text-emerald-400">"Senior Data Analyst",
    400">class="text-emerald-400">"description": 400">class="text-emerald-400">"Advanced agent for data analysis with SQL access and visualization.",
    400">class="text-emerald-400">"tags": [400">class="text-emerald-400">"analytics", 400">class="text-emerald-400">"reporting", 400">class="text-emerald-400">"sql"]
  }'

Response 200

{
  400">class="text-emerald-400">"success": true,
  400">class="text-emerald-400">"agent": {
    400">class="text-emerald-400">"id": 400">class="text-emerald-400">"550e8400-e29b-41d4-a716-446655440000",
    400">class="text-emerald-400">"name": 400">class="text-emerald-400">"Senior Data Analyst",
    400">class="text-emerald-400">"description": 400">class="text-emerald-400">"Advanced agent for data analysis with SQL access and visualization.",
    400">class="text-emerald-400">"model": 400">class="text-emerald-400">"claude-sonnet",
    400">class="text-emerald-400">"temperature": 0.3,
    400">class="text-emerald-400">"capabilities": {
      400">class="text-emerald-400">"code_interpreter": true,
      400">class="text-emerald-400">"file_analysis": true
    },
    400">class="text-emerald-400">"tags": [400">class="text-emerald-400">"analytics", 400">class="text-emerald-400">"reporting", 400">class="text-emerald-400">"sql"],
    400">class="text-emerald-400">"status": 400">class="text-emerald-400">"active",
    400">class="text-emerald-400">"isPublic": false,
    400">class="text-emerald-400">"updated_at": 400">class="text-emerald-400">"2026-03-19T16:45:00.000Z"
  }
}
DELETE/api/v2/agents/:idAuthenticated

Soft-delete an agent. Sets deleted_at and status='archived'. Requires ownership.

Path Parameters

idstringrequired

UUID of the agent to delete.

Request

cURL
400">curl -X 400">DELETE https:400">class="text-zinc-500">//api.lvng.ai/api/v2/agents/550e8400-e29b-41d4-a716-446655440000 \
  -H 400">class="text-emerald-400">"Authorization: Bearer YOUR_JWT_TOKEN"

Response 200

{
  400">class="text-emerald-400">"success": true,
  400">class="text-emerald-400">"message": 400">class="text-emerald-400">"Agent deleted successfully"
}

Agent Operations

Control agent lifecycle. Duplicate agents as templates, view usage statistics, and update capabilities independently of other configuration.

POST/api/v2/agents/:id/duplicateAuthenticated

Create a copy of an existing agent with all configuration. Copy starts as inactive.

Path Parameters

idstringrequired

UUID of the agent to duplicate.

Body Parameters

namestring

Name for the copy. Defaults to original name with "(Copy)" suffix.

Request

cURL
400">curl -X 400">POST https:400">class="text-zinc-500">//api.lvng.ai/api/v2/agents/550e8400-e29b-41d4-a716-446655440000/duplicate \
  -H 400">class="text-emerald-400">"Authorization: Bearer YOUR_JWT_TOKEN" \
  -H 400">class="text-emerald-400">"Content-Type: application/json" \
  -d '{
    400">class="text-emerald-400">"name": 400">class="text-emerald-400">"Data Analyst v2"
  }'

Response 201

{
  400">class="text-emerald-400">"success": true,
  400">class="text-emerald-400">"agent": {
    400">class="text-emerald-400">"id": 400">class="text-emerald-400">"6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    400">class="text-emerald-400">"name": 400">class="text-emerald-400">"Data Analyst v2",
    400">class="text-emerald-400">"description": 400">class="text-emerald-400">"Analyzes datasets and produces reports with statistical insights.",
    400">class="text-emerald-400">"systemPrompt": 400">class="text-emerald-400">"You are a senior data analyst. Analyze data thoroughly and provide clear statistical insights.",
    400">class="text-emerald-400">"model": 400">class="text-emerald-400">"claude-sonnet",
    400">class="text-emerald-400">"temperature": 0.3,
    400">class="text-emerald-400">"capabilities": {
      400">class="text-emerald-400">"code_interpreter": true,
      400">class="text-emerald-400">"file_analysis": true
    },
    400">class="text-emerald-400">"tags": [400">class="text-emerald-400">"analytics", 400">class="text-emerald-400">"reporting"],
    400">class="text-emerald-400">"status": 400">class="text-emerald-400">"inactive",
    400">class="text-emerald-400">"isPublic": false,
    400">class="text-emerald-400">"user_id": 400">class="text-emerald-400">"a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
    400">class="text-emerald-400">"created_at": 400">class="text-emerald-400">"2026-03-19T17:00:00.000Z",
    400">class="text-emerald-400">"updated_at": 400">class="text-emerald-400">"2026-03-19T17:00:00.000Z"
  }
}
GET/api/v2/agents/:id/statsAuthenticated

Get usage statistics for an agent over a time period.

Path Parameters

idstringrequired

UUID of the agent.

Query Parameters

periodstring

Time period: 7d, 30d, 90d. Defaults to 7d.

Request

cURL
400">curl -X 400">GET 400">class="text-emerald-400">"https:400">class="text-zinc-500">//api.lvng.ai/api/v2/agents/550e8400-e29b-41d4-a716-446655440000/stats?period=30d" \
  -H 400">class="text-emerald-400">"Authorization: Bearer YOUR_JWT_TOKEN"

Response 200

{
  400">class="text-emerald-400">"success": true,
  400">class="text-emerald-400">"stats": {
    400">class="text-emerald-400">"conversations": 89,
    400">class="text-emerald-400">"tokens": {
      400">class="text-emerald-400">"input": 523400,
      400">class="text-emerald-400">"output": 198750
    },
    400">class="text-emerald-400">"startDate": 400">class="text-emerald-400">"2026-02-17T00:00:00.000Z",
    400">class="text-emerald-400">"endDate": 400">class="text-emerald-400">"2026-03-19T17:00:00.000Z"
  }
}
PUT/api/v2/agents/:id/capabilitiesAuthenticated

Update agent capabilities. Deep merges with existing capabilities object.

Path Parameters

idstringrequired

UUID of the agent.

Body Parameters

capabilitiesobjectrequired

Capabilities object. Deep merged with existing values.

Request

cURL
400">curl -X 400">PUT https:400">class="text-zinc-500">//api.lvng.ai/api/v2/agents/550e8400-e29b-41d4-a716-446655440000/capabilities \
  -H 400">class="text-emerald-400">"Authorization: Bearer YOUR_JWT_TOKEN" \
  -H 400">class="text-emerald-400">"Content-Type: application/json" \
  -d '{
    400">class="text-emerald-400">"capabilities": {
      400">class="text-emerald-400">"code_interpreter": true,
      400">class="text-emerald-400">"file_analysis": true,
      400">class="text-emerald-400">"web_search": true
    }
  }'

Response 200

{
  400">class="text-emerald-400">"success": true,
  400">class="text-emerald-400">"agent": {
    400">class="text-emerald-400">"id": 400">class="text-emerald-400">"550e8400-e29b-41d4-a716-446655440000",
    400">class="text-emerald-400">"name": 400">class="text-emerald-400">"Senior Data Analyst",
    400">class="text-emerald-400">"capabilities": {
      400">class="text-emerald-400">"code_interpreter": true,
      400">class="text-emerald-400">"file_analysis": true,
      400">class="text-emerald-400">"web_search": true
    },
    400">class="text-emerald-400">"updated_at": 400">class="text-emerald-400">"2026-03-19T17:10:00.000Z"
  }
}

Lifecycle Control

Start and stop agents. Active agents can process messages and execute tools. Inactive agents reject incoming requests.

POST/api/v2/agents/:id/startAuthenticated

Start an agent. Sets status to 'active'.

Path Parameters

idstringrequired

UUID of the agent.

Request

cURL
400">curl -X 400">POST https:400">class="text-zinc-500">//api.lvng.ai/api/v2/agents/550e8400-e29b-41d4-a716-446655440000/start \
  -H 400">class="text-emerald-400">"Authorization: Bearer YOUR_JWT_TOKEN"

Response 200

{
  400">class="text-emerald-400">"success": true,
  400">class="text-emerald-400">"agent": {
    400">class="text-emerald-400">"id": 400">class="text-emerald-400">"550e8400-e29b-41d4-a716-446655440000",
    400">class="text-emerald-400">"name": 400">class="text-emerald-400">"Senior Data Analyst",
    400">class="text-emerald-400">"status": 400">class="text-emerald-400">"active",
    400">class="text-emerald-400">"updated_at": 400">class="text-emerald-400">"2026-03-19T17:15:00.000Z"
  }
}
POST/api/v2/agents/:id/stopAuthenticated

Stop an agent. Sets status to 'inactive'.

Path Parameters

idstringrequired

UUID of the agent.

Request

cURL
400">curl -X 400">POST https:400">class="text-zinc-500">//api.lvng.ai/api/v2/agents/550e8400-e29b-41d4-a716-446655440000/stop \
  -H 400">class="text-emerald-400">"Authorization: Bearer YOUR_JWT_TOKEN"

Response 200

{
  400">class="text-emerald-400">"success": true,
  400">class="text-emerald-400">"agent": {
    400">class="text-emerald-400">"id": 400">class="text-emerald-400">"550e8400-e29b-41d4-a716-446655440000",
    400">class="text-emerald-400">"name": 400">class="text-emerald-400">"Senior Data Analyst",
    400">class="text-emerald-400">"status": 400">class="text-emerald-400">"inactive",
    400">class="text-emerald-400">"updated_at": 400">class="text-emerald-400">"2026-03-19T17:20:00.000Z"
  }
}

Agent Messaging

Send a message directly to an agent outside of a channel context. The agent loads its configuration, fetches conversation history, and calls the Claude API with its configured system prompt and tools.

POST/api/v2/agents/:id/messageAuthenticated

Send a message to an agent and receive a response. Loads agent config, fetches history, and calls Claude.

Path Parameters

idstringrequired

UUID of the agent. Agent must be active.

Body Parameters

messagestringrequired

The message to send to the agent.

contextobject

Additional context passed to the agent. Available in the system prompt and tool calls.

Request

cURL
400">curl -X 400">POST https:400">class="text-zinc-500">//api.lvng.ai/api/v2/agents/550e8400-e29b-41d4-a716-446655440000/message \
  -H 400">class="text-emerald-400">"Authorization: Bearer YOUR_JWT_TOKEN" \
  -H 400">class="text-emerald-400">"Content-Type: application/json" \
  -d '{
    400">class="text-emerald-400">"message": 400">class="text-emerald-400">"What were the top 3 products by revenue last quarter?",
    400">class="text-emerald-400">"context": {
      400">class="text-emerald-400">"database": 400">class="text-emerald-400">"analytics_prod",
      400">class="text-emerald-400">"time_range": 400">class="text-emerald-400">"Q1_2026"
    }
  }'

Response 200

{
  400">class="text-emerald-400">"success": true,
  400">class="text-emerald-400">"response": 400">class="text-emerald-400">"Based on Q1 2026 revenue data, the top 3 products were:\n\n1. Enterprise Plan -- $1.8M (43% of total)\n2. Team Plan -- $1.2M (29% of total)\n3. API Access -- $780K (19% of total)\n\nEnterprise showed the strongest growth at 31% YoY.",
  400">class="text-emerald-400">"model": 400">class="text-emerald-400">"claude-sonnet",
  400">class="text-emerald-400">"toolsUsed": [400">class="text-emerald-400">"query_database"],
  400">class="text-emerald-400">"usage": {
    400">class="text-emerald-400">"input_tokens": 856,
    400">class="text-emerald-400">"output_tokens": 423
  }
}