# API Reference

The LVNG REST API lets you programmatically interact with every part of the platform. Manage agents, orchestrate workflows, send messages, and build intelligent applications with a consistent, well-documented interface.

## Base URL

All API requests are made to the following base URL. HTTPS is required for all requests.

```
https://api.lvng.ai/api
```

## Versioning

The API is versioned via path prefix. The current version is `v2`.

- **v2** -- Current version. All features land here.

## Content Type

All requests and responses use JSON. Set the `Content-Type` header on every request that includes a body.

```
Content-Type: application/json
```

## Authentication

All endpoints require a Bearer token in the `Authorization` header. You can use JWT tokens from Supabase Auth or API keys.

```bash
curl -X GET https://api.lvng.ai/api/v2/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

Requests without a valid token receive a `401 Unauthorized` response.

## Response Format

Most responses follow a consistent envelope structure with a `success` field. The data key varies by endpoint.

**Success response:**

```json
{
  "success": true,
  "agent": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Research Agent",
    "status": "active"
  }
}
```

**Error response:**

```json
{
  "error": "Agent not found",
  "message": "No agent with the given ID exists in this workspace"
}
```

## Rate Limiting

API requests are rate-limited per endpoint and per API key plan. Rate limit information is returned in response headers.

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 97
X-RateLimit-Reset: 2026-03-19T19:00:00.000Z
```

If you exceed the limit, you will receive a `429 Too Many Requests` response. Wait until the reset timestamp before retrying.

## API Resources

- **[Chat](/docs/api/chat)** (2 endpoints) -- Send messages to AI and stream responses via SSE.
- **[Messages](/docs/api/messages)** (12 endpoints) -- Full CRUD for messages, threads, reactions, uploads, and AI summarization.
- **[Channels](/docs/api/channels)** (17 endpoints) -- Manage channels, members, digital twins, and pinned messages.
- **[Workspaces](/docs/api/workspaces)** (16 endpoints) -- Manage workspaces, team members, roles, permissions, and settings.
- **[Agents](/docs/api/agents)** (11 endpoints) -- Create, configure, and control AI agents.
- **[Workflows](/docs/api/workflows)** (16 endpoints) -- Build, execute, and schedule automation workflows.
- **[Digital Twins](/docs/api/twins)** (5 endpoints) -- Add and manage AI personas in workspaces.
- **[Artifacts](/docs/api/artifacts)** (12 endpoints) -- Store AI-generated artifacts with versioning.
- **[Knowledge](/docs/api/knowledge)** (11 endpoints) -- Ingest, search, and analyze content.
- **[Canvas](/docs/api/canvas)** (7 endpoints) -- Visual canvas cards and folders.
- **[Calendar](/docs/api/calendar)** (6 endpoints) -- Unified calendar across Google and Microsoft.
- **[Voice Notes](/docs/api/voice-notes)** (7 endpoints) -- Audio recording and Whisper transcription.
- **[Search](/docs/api/search)** (1 endpoint) -- Unified semantic search.
- **[Settings](/docs/api/settings)** (7 endpoints) -- User and workspace settings.
- **[Integrations](/docs/api/integrations)** (11 endpoints) -- Platform integrations for Discord, Slack, Teams.
- **[Conversations](/docs/api/conversations)** (10 endpoints) -- DMs, group conversations, read receipts.

## HTTP Methods

| Method | Description |
|--------|-------------|
| `GET` | Retrieve a resource or list of resources |
| `POST` | Create a new resource or trigger an action |
| `PUT` | Replace a resource entirely |
| `PATCH` | Partially update a resource |
| `DELETE` | Remove a resource |

## Pagination

List endpoints support offset-based pagination using `limit` and `offset` parameters. The default page size is 50 items.

```bash
curl -X GET "https://api.lvng.ai/api/v2/messages/history?channel_id=CHANNEL_ID&limit=25&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"
```