API Reference

The LensAI API provides programmatic access to all platform functionality, enabling you to send events, record metrics, query analytics, and manage your projects and configuration.

Base URL

All API requests should be made to:

https://api.getlens.ai/v1

Authentication

LensAI uses API keys for authentication. Include your API key in the Authorization header of every request:

Authorization: Bearer YOUR_LENSAI_API_KEY

Example request:

curl https://api.getlens.ai/v1/agents \
  -H "Authorization: Bearer sk_xyz_abc123..." \
  -H "Content-Type: application/json"

Obtaining API Keys

Sign in to your LensAI account at dashboard.getlens.ai
Navigate to Settings → API Keys
Click Generate API Key
Copy the key and store it securely (you won't be able to see it again)

Important: Keep your API keys secret. Do not commit them to version control or expose them in client-side code.

API Endpoints

LensAI APIs are organized around the following groups:

Agents: List and retrieve AI agent configurations
Customers: Access customer records and metadata
Goal Types: Define and manage goal categories
Goals: Track goal definitions and completions
Outcomes: Record business outcome events
Revenues: Query revenue attribution data

Request Format

All requests should use JSON format with Content-Type: application/json header.

Example:

curl -X POST https://api.getlens.ai/v1/revenues \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "5mczBhCjbBgoWwf6Vbp5sC",
    "amount": "100"
  }'

Response Format

All successful responses return JSON with appropriate HTTP status codes:

200 OK: Request successful, data returned
201 Created: Resource created successfully
204 No Content: Request successful, no data to return
400 Bad Request: Invalid request format or parameters
401 Unauthorized: Missing or invalid API key
403 Forbidden: API key lacks permission for this operation
404 Not Found: Resource not found
429 Too Many Requests: Rate limit exceeded
500 Internal Server Error: Server error (contact support if persistent)

Success response example:

{
    "agentId": "5mczBhCjbBgoWwf6Vbp5sC",
    "amount": "100",
    "createdAt": "2025-10-21T16:03:52.493Z",
    "customerId": null,
    "description": null,
    "eventId": null,
    "goalId": null,
    "id": "3F8q36dijMU5n8xtKG7exN",
    "key": "42cb4dab-dfb4-432e-b26f-674ae3937eb0",
    "recordedAt": "2025-10-21T16:03:52.491Z",
    "source": "Manual",
    "updatedAt": "2025-10-21T18:10:51Z"
}

Error response example:

{
    "code": "Invalid ID",
    "message": "Invalid ID",
    "path": "GET /v1/revenues/5mczBhCjbBgoWwf6Vbp5s!",
    "status": 400,
    "timestamp": "2025-10-21T16:05:16.455Z"
}

API rate limits depend on your plan tier. When you exceed the rate limit, you'll receive a 429 Too Many Requests response. Implement exponential backoff and retry logic to handle rate limiting gracefully.

Pagination

List endpoints support pagination using limit and offset parameters:

GET /events?limit=100&offset=200

limit: Number of results per page (max 1000, default 100)
offset: Number of results to skip (default 0)

Idempotency

Event ingestion endpoints support idempotency keys to prevent duplicate event creation. Include an Idempotency-Key header:

curl -X POST https://api.getlens.ai/v1/revenues \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Idempotency-Key: unique_key_123" \
  -H "Content-Type: application/json" \
  -d '{...}'

If you retry a request with the same idempotency key, LensAI will return the original response without creating a duplicate event.

Next Steps

Explore individual endpoint documentation for detailed request/response schemas
Review Errors for how to handle erros
Check Types for common API types

Overview