REST APIv1 · read-only

Insights API

Read conversations, handoffs, usage metrics, and knowledge sources for any workspace using a workspace-scoped API key. All endpoints are read-only — mutations go through the LuluDesk dashboard.

Base URL

https://luluclaw.com/api/v1/workspaces/{id}

Replace {id} with your workspace ID, visible in the LuluDesk dashboard URL or in the workspace settings.

Authentication

Every request requires a workspace-scoped API key in the Authorization: Bearer header. Generate a key from the workspace settings → API Keys tab. Keys have the format lld_<hex>.

Authorization: Bearer lld_YOUR_API_KEY

The key is shown exactly once on creation and cannot be recovered afterward. Revoke and regenerate from the dashboard if lost.

Scopes

Each endpoint requires a specific scope. The read_only_insights preset grants all five scopes listed below and is the default when creating a key.

Scope	Grants access to
read:insights	Aggregate insights summary endpoint
read:conversations	Conversation list endpoint
read:handoffs	Handoffs endpoint
read:usage	Usage metrics endpoint
read:knowledge	Knowledge sources endpoint

Endpoints

	Path	Required scope
GET	`/api/v1/workspaces/{id}/insights` Aggregated summary: conversations, handoffs, messages.	read:insights
GET	`/api/v1/workspaces/{id}/conversations` Paginated conversation list with status and message count.	read:conversations
GET	`/api/v1/workspaces/{id}/handoffs` Handoff records, filterable by status, cursor-paginated.	read:handoffs
GET	`/api/v1/workspaces/{id}/usage` Message usage, spend cap, and billing period dates.	read:usage
GET	`/api/v1/workspaces/{id}/knowledge-sources` Knowledge sources attached to the workspace.	read:knowledge

GET /insights

Returns an aggregated summary of conversations, handoffs, and message usage for the workspace in the current billing period. Use this as the single call to populate a dashboard overview.

Example request

bash

curl https://luluclaw.com/api/v1/workspaces/YOUR_WORKSPACE_ID/insights \
  -H "Authorization: Bearer lld_YOUR_API_KEY"

Example response

json

{
  "data": {
    "conversations": { "total": 142, "period_start": "2026-05-01T00:00:00.000Z", "period_end": "2026-05-31T00:00:00.000Z" },
    "handoffs":      { "total": 7, "pending": 2, "resolved": 5 },
    "messages":      { "total": 891, "limit": 3000 }
  },
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "meta": {
    "generated_at": "2026-05-17T09:00:00.000Z",
    "period_type": "billing_period"
  }
}

Common errors

401

Missing Authorization header

Include Authorization: Bearer lld_… in every request.

403 insufficient_scope

Wrong scope

This endpoint requires read:insights. Having other read scopes is not sufficient — regenerate the key with the read_only_insights preset.

404 workspace_not_found

Workspace not found

The workspace ID in the URL does not exist or has been deleted. Check the ID in your dashboard URL.

GET /conversations

Returns a paginated list of conversations for the workspace, ordered newest first. Each record includes the message count, lifecycle status, and any associated handoff ID.

Query parameters

Param	Default	Description
page	1	1-based page number.
limit	20	Page size, 1–100.
cursor	—	Opaque base64url cursor from next_cursor. Overrides page when present.

Example request

bash

curl "https://luluclaw.com/api/v1/workspaces/YOUR_WORKSPACE_ID/conversations?limit=20&page=1" \
  -H "Authorization: Bearer lld_YOUR_API_KEY"

Example response

json

{
  "data": [
    {
      "id": "conv_abc123",
      "workspace_id": "550e8400-...",
      "started_at": "2026-05-16T14:00:00.000Z",
      "ended_at": "2026-05-16T14:07:22.000Z",
      "message_count": 6,
      "handoff_id": null,
      "status": "closed"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 142,
    "has_more": true,
    "next_cursor": "eyJpZCI6ImNvbnZfYWJjMTIzIn0"
  }
}

Common errors

422 invalid_params

Bad query parameter

page and limit must be whole positive integers. Floats, negative values, and scientific notation are rejected.

GET /handoffs

Returns handoff records for the workspace, newest first. Filter by status or paginate with the before cursor.

Query parameters

Param	Default	Description
status	—	Filter: pending \| accepted \| resolved \| rejected
limit	50	Page size, 1–200.
before	—	ISO 8601 cursor — returns records with created_at < before.

Example request

bash

curl "https://luluclaw.com/api/v1/workspaces/YOUR_WORKSPACE_ID/handoffs?status=pending&limit=50" \
  -H "Authorization: Bearer lld_YOUR_API_KEY"

GET /usage

Returns message consumption, utilisation ratio, billing period dates, and Synthetic API spend against the tier hard cap. Use this to power a usage progress bar or alert users before they hit limits.

Example request

bash

curl https://luluclaw.com/api/v1/workspaces/YOUR_WORKSPACE_ID/usage \
  -H "Authorization: Bearer lld_YOUR_API_KEY"

Example response

json

{
  "data": {
    "messages_used": 891,
    "messages_limit": 3000,
    "messages_utilisation": 0.297,
    "period_start": "2026-05-01T00:00:00.000Z",
    "period_end": "2026-05-31T00:00:00.000Z",
    "cost_micros": 4200000,
    "cap_micros": 87000000,
    "pct_used": 4.83
  },
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "meta": { "period_type": "billing_period" }
}

cost_micros / cap_micros — Synthetic API spend in USD micros (1 micro = $0.000001). The hard cap is 3× your plan price. Free tier cap is $30.

GET /knowledge-sources

Returns the knowledge sources attached to the workspace — websites, documents, and manual entries that the assistant uses for retrieval. Use this to display source status in your own dashboard or to detect sources that need re-crawling.

Example request

bash

curl https://luluclaw.com/api/v1/workspaces/YOUR_WORKSPACE_ID/knowledge-sources \
  -H "Authorization: Bearer lld_YOUR_API_KEY"

Example response

json

{
  "data": [
    {
      "id": "ks_abc123",
      "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Help Centre",
      "type": "website",
      "url": "https://help.example.com",
      "chunk_count": 42,
      "status": "ready",
      "created_at": "2026-04-01T10:00:00.000Z",
      "updated_at": "2026-05-10T08:30:00.000Z"
    }
  ],
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "meta": { "total": 1, "page": 1, "limit": 20 }
}

status — one of ready, crawling, error, or pending. Only sources with status: "ready" are actively used for retrieval.

Common Error Reference

401

auth_required — Bearer token missing

The Authorization header is absent or not in Bearer … format.

403 forbidden

Invalid or revoked key

The API key does not exist, has been revoked, or its workspace_id does not match the {id} in the URL.

403 insufficient_scope

Key missing required scope

The key was created with a scope that does not include the scope needed by this endpoint. Regenerate the key with the read_only_insights preset.

404 workspace_not_found

Workspace does not exist

The workspace was deleted or the ID is wrong. Check your dashboard URL for the correct workspace ID.

422 invalid_params

Bad query parameter

One or more query parameters failed validation. The details array in the response body lists each invalid field, its value, and the constraint violated.

500 internal_error

Unexpected server error

An unexpected error occurred. Retry with exponential backoff. If the error persists, contact support.

Need an API key? Open the workspace settings → API Keys tab and create a key with the read_only_insights preset. The key is shown once — copy it before closing the modal.