Skip to main content

Lars API Reference

Integrate Lars capabilities into your applications using the Stanna API.

Authentication

All API requests require authentication:
X-API-Key: your-api-key
X-Workspace-Id: your-workspace-id

Chat API

Send Message

Send a message to Lars and receive a response with suggested actions.
POST /api/ai-agent/chat
Content-Type: application/json

Request Body

{
  "content": "What's the status of Acme Corp?",
  "conversationId": "optional-conversation-uuid"
}

Response

{
  "success": true,
  "data": {
    "content": "Acme Corp is currently showing healthy metrics...",
    "conversationId": "conversation-uuid",
    "suggestedActions": [
      {
        "id": "action-uuid",
        "type": "CREATE_TASK",
        "title": "Follow up with Acme Corp",
        "description": "Schedule a check-in call",
        "status": "SUGGESTED",
        "riskLevel": "low",
        "params": {
          "clientId": "client-uuid",
          "title": "Check-in call",
          "dueAt": "2024-02-01T10:00:00Z"
        }
      }
    ],
    "clientReferences": [
      {
        "id": "client-uuid",
        "name": "Acme Corp",
        "domain": "acme.com"
      }
    ]
  }
}

Actions API

Execute Action

Execute a suggested action from Lars.
POST /api/ai-agent/actions/{actionId}/execute
Content-Type: application/json

Request Body

{
  "actionId": "action-uuid",
  "autoApprove": true
}

Response

{
  "success": true,
  "data": {
    "success": true,
    "result": {
      "taskId": "task-uuid",
      "title": "Follow up with Acme Corp"
    },
    "metadata": {
      "actionType": "create_task",
      "clientId": "client-uuid"
    }
  }
}

Error Responses

All endpoints return consistent error responses:
{
  "success": false,
  "error": "Action not found or unauthorized",
  "code": "ACTION_NOT_FOUND",
  "timestamp": "2024-01-15T10:30:00Z"
}

Common Error Codes

CodeStatusDescription
CONVERSATION_NOT_FOUND404Conversation ID not found
ACTION_NOT_FOUND404Action ID not found
INVALID_ACTION_STATUS400Action cannot be executed
CLIENT_NOT_FOUND404Client ID not found
RATE_LIMIT_EXCEEDED429Too many requests
VALIDATION_ERROR400Request validation failed

Rate Limiting

API requests are rate-limited per workspace:
  • Chat API: 60 requests per minute
  • Actions API: 30 requests per minute
Rate limit headers are included in responses:
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1642248000

Examples

Node.js

const axios = require('axios');

const client = axios.create({
  baseURL: 'https://api.gostanna.com',
  headers: {
    'X-API-Key': process.env.STANNA_API_KEY,
    'X-Workspace-Id': process.env.STANNA_WORKSPACE_ID
  }
});

// Send message to Lars
async function askLars(question) {
  const response = await client.post('/api/ai-agent/chat', {
    content: question
  });
  return response.data;
}

// Execute suggested action
async function executeAction(actionId) {
  const response = await client.post(
    `/api/ai-agent/actions/${actionId}/execute`,
    { autoApprove: true }
  );
  return response.data;
}

// Example usage
(async () => {
  const result = await askLars('Which clients are at risk?');
  console.log(result.data.content);

  if (result.data.suggestedActions.length > 0) {
    const action = result.data.suggestedActions[0];
    await executeAction(action.id);
  }
})();

Python

import requests
import os

class LarsClient:
    def __init__(self):
        self.base_url = 'https://api.gostanna.com'
        self.headers = {
            'X-API-Key': os.environ['STANNA_API_KEY'],
            'X-Workspace-Id': os.environ['STANNA_WORKSPACE_ID']
        }

    def ask(self, question):
        response = requests.post(
            f'{self.base_url}/api/ai-agent/chat',
            headers=self.headers,
            json={'content': question}
        )
        return response.json()

    def execute_action(self, action_id):
        response = requests.post(
            f'{self.base_url}/api/ai-agent/actions/{action_id}/execute',
            headers=self.headers,
            json={'autoApprove': True}
        )
        return response.json()

# Example usage
lars = LarsClient()
result = lars.ask('Which clients are at risk?')
print(result['data']['content'])

if result['data']['suggestedActions']:
    action = result['data']['suggestedActions'][0]
    lars.execute_action(action['id'])

Next Steps