claudeskill/skills/seq-api/SKILL.md

---
name: seq-api
description: Guide for making HTTP API calls to the Seq structured log server (by Datalust). Use this skill whenever the user wants to interact with Seq programmatically — including ingesting events/logs/traces, querying events, managing API keys, signals, dashboards, alerts, users, workspaces, retention policies, app instances, backups, diagnostics, or any other Seq server resource. Also trigger when the user mentions Seq API, CLEF ingestion, Seq health checks, Seq SQL queries via API, or building scripts/automation that talk to a Seq server. Even if the user just says "send logs to Seq" or "query Seq" or "check Seq health", use this skill.
---

# Seq HTTP API Skill

This skill provides guidance for calling the Seq server HTTP API. Seq is a centralized structured log server by Datalust. Its full API is REST-like, JSON-based, and navigable from the `/api/` root resource.

## Quick Reference

### Base URL & Discovery

The API root is at `{SEQ_SERVER_URL}/api/`. A GET to this endpoint returns a JSON object listing links to all resource groups (e.g., `ApiKeysResources`, `EventsResources`).

### Authentication

Two methods (only needed when auth is enabled on the server):

1. **Query string**: `?apiKey={YOUR_API_KEY}`
2. **Header**: `X-Seq-ApiKey: {YOUR_API_KEY}`

API keys are the recommended method. Each key has specific permissions — make sure the key has the required permission level for the endpoint you're calling (see permission levels below).

### Permission Levels

Seq endpoints require one of these permission levels (from lowest to highest):

- **Public** — No auth needed (health checks, resource listings, auth settings)
- **Ingest** — Required for writing events when `RequireApiKeyForWritingEvents` is enabled
- **Read** — View events, signals, dashboards, alerts, queries
- **Write** — Create/update/delete signals, dashboards, alerts, queries
- **Project** — Administrative project-level access (retention policies, indexes, alert state, diagnostics metrics)
- **Organization** — Manage users
- **System** — Full server administration (apps, backups, cluster, feeds, settings, licenses)

### Common Patterns

All resource endpoints follow a consistent pattern:

| Operation | Method | Path |
|-----------|--------|------|
| List all | GET | `api/{resource}` |
| Create | POST | `api/{resource}` |
| Get one | GET | `api/{resource}/{id}` |
| Update | PUT | `api/{resource}/{id}` |
| Delete | DELETE | `api/{resource}/{id}` |
| Get template | GET | `api/{resource}/template` |
| Resource links | GET | `api/{resource}/resources` |

Use the `template` endpoint to get a blank object with the correct structure before creating a new resource.

### Content Type

All API requests and responses use `application/json`, except:
- CLEF ingestion uses `application/vnd.serilog.clef`
- OpenTelemetry ingestion uses protocol-specific content types

---

## Key Tasks

### 1. Health Check

```
GET {SEQ_URL}/health
```

Returns 200 (healthy) or 503 (unhealthy) with JSON body `{"status": "..."}`. No authentication needed. For clusters, use `/health/cluster`.

### 2. Ingest Events (CLEF Format)

**Read `references/ingestion.md` for full CLEF format details and all reified properties.**

```
POST {SEQ_URL}/ingest/clef
Content-Type: application/vnd.serilog.clef
X-Seq-ApiKey: {API_KEY}

{"@t":"2024-01-15T10:30:00Z","@mt":"User {User} logged in","User":"alice","@l":"Information"}
{"@t":"2024-01-15T10:30:01Z","@mt":"Error processing {OrderId}","OrderId":123,"@l":"Error","@x":"System.Exception: ..."}
```

Response: `201 Created` with `{"MinimumLevelAccepted": null}` on success.

### 3. Ingest via OpenTelemetry

```
POST {SEQ_URL}/ingest/otlp/v1/logs
POST {SEQ_URL}/ingest/otlp/v1/traces
POST {SEQ_URL}/ingest/otlp/v1/metrics
```

### 4. Query Events

```
GET {SEQ_URL}/api/events?count=30&filter=StatusCode%20%3E%20399
```

Key query parameters: `count`, `filter` (Seq filter expression), `signal` (signal ID), `fromDateUtc`, `toDateUtc`.

For SQL-style queries:

```
POST {SEQ_URL}/api/data
Content-Type: application/json
X-Seq-ApiKey: {API_KEY}

{
  "Query": "select count(*) from stream group by RequestPath",
  "RangeStartUtc": "2024-01-01T00:00:00Z",
  "RangeEndUtc": "2024-01-02T00:00:00Z",
  "SignalExpression": null
}
```

Also available via GET: `GET /api/data?q={query}&rangeStartUtc=...&rangeEndUtc=...`

### 5. Manage API Keys

```bash
# List keys (need Read or Project permission)
GET /api/apikeys

# Create a key
POST /api/apikeys
{"Title": "My App Key", "AssignedPermissions": ["Ingest"]}

# Delete a key
DELETE /api/apikeys/{id}
```

### 6. Manage Signals

```bash
# List signals
GET /api/signals

# Create a signal
POST /api/signals
{"Title": "Errors", "Filters": [{"Filter": "@Level = 'Error'"}]}
```

### 7. Manage Dashboards & Alerts

Follow the same CRUD pattern at `/api/dashboards` and `/api/alerts`. Use the `/template` endpoint to get the correct JSON structure.

### 8. Server Diagnostics

```bash
GET /api/diagnostics/status     # Read permission
GET /api/diagnostics/metrics    # Project permission
GET /api/diagnostics/ingestion  # System permission
GET /api/diagnostics/storage    # Project permission
GET /api/diagnostics/report     # System permission — full diagnostic report
```

### 9. User Management

```bash
GET /api/users/current          # Get logged-in user
POST /api/users/login           # Authenticate
GET /api/users                  # List users (Project permission)
POST /api/users                 # Create user (Organization permission)
```

### 10. Backup

```bash
POST /api/backups/immediate     # Trigger immediate backup (System permission)
GET /api/backups                # List backups
GET /api/backups/files/{name}   # Download a backup file
```

---

## Ownership & Sharing Rules

For signals, dashboards, alerts, SQL queries, and workspaces:
- Users can only read/modify **shared** resources and **their own** resources
- Creating/modifying **protected** resources requires **Project** permission
- Resources are either shared (visible to everyone), personal (owner-only), or protected (admin-managed)

---

## Response Conventions

- Successful list requests return a JSON array
- Successful single-resource requests return a JSON object
- Error responses include `{"Error": "message"}`
- Ingestion success returns `{"MinimumLevelAccepted": null}` (or a level string if filtering is applied)

---

## Reference Files

For the complete endpoint listing with all paths, HTTP methods, and permission requirements, read:
- `references/endpoints.md` — Full API endpoint table for every resource
- `references/ingestion.md` — CLEF format specification, reified properties, status codes, and batch formatting

Read the appropriate reference file when you need the specific details for an endpoint or ingestion format.