claudeskill/skills/seq-api/SKILL.md

name, description

name

description

seq-api

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

# 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

# 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

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

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

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.