LanternDOCS

API Reference

The Lantern REST API provides programmatic access to all platform functionality. All endpoints are served from https://api.lantern.run/v1 (or your self-hosted domain).

Authentication

All API requests require a Bearer token in the Authorization header:

Authorization: Bearer lnt_your_api_key_here

Generate API keys from the dashboard under Settings > API Keys. Keys can be scoped to specific agents or full account access.

Agents

List agents

GET /v1/agents

Response:
{
  "agents": [
    {
      "name": "research-agent",
      "description": "Researches topics and writes reports",
      "model": "auto",
      "status": "active",
      "created_at": "2026-04-10T12:00:00Z",
      "updated_at": "2026-04-11T09:30:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20
}

Get agent

GET /v1/agents/:name

Response:
{
  "name": "research-agent",
  "description": "Researches topics and writes reports",
  "system_prompt": "You are a research assistant...",
  "model": "auto",
  "connectors": ["gmail", "web-search"],
  "surfaces": ["whatsapp", "slack"],
  "privacy_level": "standard",
  "guardrails": {
    "max_cost_per_run": 1.00,
    "block_pii": false
  },
  "schedule": {
    "cron": "0 9 * * 1-5",
    "timezone": "America/New_York"
  },
  "status": "active",
  "created_at": "2026-04-10T12:00:00Z"
}

Create agent

POST /v1/agents
Content-Type: application/json

{
  "name": "my-agent",
  "description": "Does something useful",
  "system_prompt": "You are a helpful assistant...",
  "model": "auto",
  "connectors": ["gmail"],
  "privacy_level": "standard"
}

Response: 201 Created
{
  "name": "my-agent",
  "status": "active",
  "created_at": "2026-04-12T10:00:00Z"
}

Update agent

PATCH /v1/agents/:name
Content-Type: application/json

{
  "description": "Updated description",
  "system_prompt": "Updated prompt..."
}

Response: 200 OK

Delete agent

DELETE /v1/agents/:name

Response: 204 No Content

Runs

Create a run

POST /v1/agents/:name/runs
Content-Type: application/json

{
  "input": {
    "topic": "quantum computing"
  }
}

Response: 201 Created
{
  "run_id": "run_abc123",
  "agent": "research-agent",
  "status": "queued",
  "created_at": "2026-04-12T10:00:00Z"
}

Get run status

GET /v1/runs/:run_id

Response:
{
  "run_id": "run_abc123",
  "agent": "research-agent",
  "status": "running",
  "steps": [
    {
      "name": "plan",
      "status": "completed",
      "duration_ms": 820,
      "model_used": "claude-3-haiku",
      "tokens": { "input": 150, "output": 340 }
    },
    {
      "name": "search-0",
      "status": "running",
      "started_at": "2026-04-12T10:00:01Z"
    }
  ],
  "created_at": "2026-04-12T10:00:00Z"
}

Stream run events

GET /v1/runs/:run_id/stream
Accept: text/event-stream

Response: Server-Sent Events
data: {"type": "step.start", "step": "plan", "timestamp": "..."}
data: {"type": "token", "content": "Quantum", "timestamp": "..."}
data: {"type": "token", "content": " computing", "timestamp": "..."}
data: {"type": "step.complete", "step": "plan", "duration_ms": 820}
data: {"type": "step.start", "step": "search-0"}
...
data: {"type": "run.complete", "run_id": "run_abc123"}
Tip: Use the streaming endpoint for real-time UI updates. Tokens flow end-to-end with no buffering -- the response streams as the LLM generates it.

List runs

GET /v1/agents/:name/runs?status=completed&limit=10

Response:
{
  "runs": [...],
  "total": 42,
  "page": 1,
  "per_page": 10
}

Cancel a run

POST /v1/runs/:run_id/cancel

Response: 200 OK
{
  "run_id": "run_abc123",
  "status": "cancelled"
}

Connectors

List connectors

GET /v1/connectors

Response:
{
  "connectors": [
    {
      "type": "gmail",
      "status": "connected",
      "account": "user@gmail.com",
      "connected_at": "2026-04-08T14:00:00Z"
    }
  ]
}

Schedules

Create or update schedule

PUT /v1/agents/:name/schedule
Content-Type: application/json

{
  "cron": "0 9 * * 1-5",
  "timezone": "America/New_York",
  "input": { "mode": "daily-digest" },
  "email_delivery": {
    "enabled": true,
    "recipients": ["team@company.com"],
    "subject": "[{agent_name}] Daily report - {run_date}"
  }
}

Response: 200 OK

Delete schedule

DELETE /v1/agents/:name/schedule

Response: 204 No Content

Error format

All errors follow a consistent format:

{
  "error": {
    "code": "not_found",
    "message": "Agent 'my-agent' not found",
    "request_id": "req_xyz789"
  }
}

Common error codes:

  • 400 -- bad_request -- invalid input
  • 401 -- unauthorized -- missing or invalid API key
  • 403 -- forbidden -- insufficient permissions
  • 404 -- not_found -- resource does not exist
  • 429 -- rate_limited -- too many requests
  • 500 -- internal_error -- server error

Rate limits

API rate limits vary by plan:

  • Personal -- 60 requests/minute
  • Team -- 300 requests/minute
  • Enterprise -- configurable

Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.