LVNGDocs
API ReferenceSDKslvng.ai

Developer API

Developer console endpoints for managing webhooks, viewing per-key API usage, and querying event logs. Webhooks support automatic retries, delivery logs, and test events. Use a verified JWT or a per-user API key with the required capability and current workspace access. JWT authentication is required for key management, including creation, listing, details, revocation, and rotation.

Per-user API key capabilities

Unmapped protected routes return 403 for per-user API keys. Capabilities do not grant workspace membership or ownership. JWT and legacy service-key authentication remain separate.

  • read: GET and HEAD /api/v2/developer/api-keys/:id/usage, /api/v2/developer/webhooks, /api/v2/developer/webhooks/:id/deliveries, and /api/v2/developer/logs.
  • write: POST /api/v2/developer/webhooks, PUT and DELETE /api/v2/developer/webhooks/:id, DELETE /api/knowledge-graph/documents/:id, and POST /api/v2/activity/log.
  • execute: POST /api/v2/developer/webhooks/:id/test. Write access alone cannot send a test webhook.
  • GET and HEAD /api/knowledge-graph/documents/:id require read or knowledge:read. Current document ownership and tenant checks still apply.
  • POST /api/v2/search requires read or knowledge:read; its POST method does not make it a write operation.

knowledge:write grants no currently supported operations. Existing admin labels do not grant any implicit capability and cannot be issued or copied during rotation. Unsupported scope labels and duplicate or empty scope lists are rejected.

Request checks use the current validation result. Revocation after the last successful check cannot undo a completed database or external effect.

Base path: /api/v2/developer

API Key Usage

View per-key usage statistics and sparkline data for dashboard charts.

GET/api/v2/developer/api-keys/:id/usageAuthenticated

Get per-key usage sparkline data (requests per day). Verifies the authenticated user owns the key.

Path Parameters

idstringrequired

UUID of the API key.

Query Parameters

daysinteger

Number of days of usage data. Defaults to 7.

Request

cURL
curl -X GET "https://api.lvng.ai/api/v2/developer/api-keys/{id}/usage" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "success": true,
  "data": {
    "key_id": "key_abc123",
    "days": 14,
    "sparkline": [12, 8, 15, 23, 19, 31, 28, 14, 9, 22, 35, 18, 27, 20]
  }
}

Webhooks

Create and manage webhook endpoints that receive real-time event notifications. Supported event types: agent.completed, workflow.completed, message.created, credit.low, swarm.spawn, knowledge.indexed.

Deliveries

Each delivery is a POST with a JSON body holding event, timestamp and data. The X-LVNG-Event header names the event and X-LVNG-Signature is the hex HMAC-SHA256 of the raw body, keyed with the signing secret returned when the webhook was created. Verify it before trusting the body.

message.created is sent for messages in public, announcement and text channels only. workflow.completed names the run and its timing, never its inputs or outputs.

The delivery log keeps the first 2 KB of each body that was sent, with the SHA-256 and size of the full body (body_preview, body_sha256, body_bytes, truncated), not the full payload.

No loop protection. LVNG does not detect delivery loops. If your endpoint answers a message.created delivery by posting a message into a public, announcement or text channel of the same workspace, for example with an API key, that message raises another message.created, which reaches your endpoint again, and so on. The same holds for an endpoint that starts a workflow run when it receives workflow.completed. Skip the events your own integration caused before acting on them: for messages, compare data.sender_id with the user that owns your API key.

POST/api/v2/developer/webhooksAuthenticated

Create a new webhook endpoint. A signing secret is generated automatically for verifying payloads.

Body Parameters

urlstringrequired

HTTP/HTTPS URL to receive webhook payloads.

eventsstring[]required

Array of event types to subscribe to.

descriptionstring

Human-readable description of the webhook.

Request

cURL
curl -X POST "https://api.lvng.ai/api/v2/developer/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response 201

{
  "success": true,
  "data": {
    "id": "wh_abc123",
    "workspace_id": "ws_abc123",
    "url": "https://myapp.com/webhooks/lvng",
    "events": ["agent.completed", "workflow.completed"],
    "signing_secret": "YOUR_WEBHOOK_SIGNING_SECRET",
    "active": true,
    "description": "Production webhook for agent completions",
    "created_at": "2026-04-01T12:00:00.000Z"
  }
}
GET/api/v2/developer/webhooksAuthenticated

List all webhooks for the current workspace.

Request

cURL
curl -X GET "https://api.lvng.ai/api/v2/developer/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "success": true,
  "data": [
    {
      "id": "wh_abc123",
      "url": "https://myapp.com/webhooks/lvng",
      "events": ["agent.completed", "workflow.completed"],
      "active": true,
      "description": "Production webhook for agent completions",
      "created_at": "2026-04-01T12:00:00.000Z",
      "updated_at": "2026-04-01T12:00:00.000Z"
    }
  ]
}
PUT/api/v2/developer/webhooks/:idAuthenticated

Update a webhook's URL, events, active status, or description.

Path Parameters

idstringrequired

UUID of the webhook.

Body Parameters

urlstring

Updated webhook URL.

eventsstring[]

Updated event subscriptions.

activeboolean

Enable or disable the webhook.

descriptionstring

Updated description.

Request

cURL
curl -X PUT "https://api.lvng.ai/api/v2/developer/webhooks/{id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response 200

{
  "success": true,
  "data": {
    "id": "wh_abc123",
    "url": "https://myapp.com/webhooks/lvng",
    "events": ["agent.completed", "workflow.completed", "credit.low"],
    "active": true,
    "updated_at": "2026-04-01T14:00:00.000Z"
  }
}
DELETE/api/v2/developer/webhooks/:idAuthenticated

Delete a webhook endpoint.

Path Parameters

idstringrequired

UUID of the webhook.

Request

cURL
curl -X DELETE "https://api.lvng.ai/api/v2/developer/webhooks/{id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "success": true,
  "message": "Webhook deleted"
}
GET/api/v2/developer/webhooks/:id/deliveriesAuthenticated

Get the last 50 delivery attempts for a webhook, including status codes and response data.

Path Parameters

idstringrequired

UUID of the webhook.

Request

cURL
curl -X GET "https://api.lvng.ai/api/v2/developer/webhooks/{id}/deliveries" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "success": true,
  "data": [
    {
      "id": "del_xyz789",
      "webhook_id": "wh_abc123",
      "event_type": "agent.completed",
      "status_code": 200,
      "success": true,
      "latency_ms": 145,
      "request_body": {
        "event": "agent.completed",
        "timestamp": "2026-04-01T13:00:00.000Z",
        "body_sha256": "9f2c...e41a",
        "body_bytes": 96,
        "truncated": false,
        "body_preview": "{\"event\":\"agent.completed\",...}"
      },
      "response_body": "OK",
      "created_at": "2026-04-01T13:00:00.000Z"
    }
  ]
}
POST/api/v2/developer/webhooks/:id/testAuthenticated

Send a test.ping event to the webhook endpoint to verify connectivity.

Path Parameters

idstringrequired

UUID of the webhook.

Request

cURL
curl -X POST "https://api.lvng.ai/api/v2/developer/webhooks/{id}/test" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response 200

{
  "success": true,
  "data": {
    "delivered": true,
    "status_code": 200,
    "latency_ms": 132,
    "delivery": {
      "id": "del_test123",
      "event_type": "test.ping"
    }
  }
}

Event Logs

Query paginated, filterable developer event logs. Supports cursor-based pagination.

GET/api/v2/developer/logsAuthenticated

Get paginated developer event logs with optional filtering by category, API key, and date range.

Query Parameters

categoriesstring

Comma-separated event categories to filter by.

api_key_idstring

Filter by specific API key UUID.

startstring

Start date (ISO 8601) for date range filter.

endstring

End date (ISO 8601) for date range filter.

cursorstring

Pagination cursor from a previous response.

limitinteger

Results per page (max 100). Defaults to 50.

Request

cURL
curl -X GET "https://api.lvng.ai/api/v2/developer/logs" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "success": true,
  "data": [
    {
      "id": "evt_abc123",
      "category": "api",
      "action": "agent.create",
      "api_key_id": "key_abc123",
      "status_code": 201,
      "duration_ms": 45,
      "created_at": "2026-04-01T12:00:00.000Z"
    }
  ],
  "nextCursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wNC0wMVQxMTowMDowMC4wMDBaIn0="
}