✨ feat: Add seq-api skill for Seq structured log server HTTP API

Add a comprehensive skill for interacting with the Seq HTTP API, covering event ingestion (CLEF/OpenTelemetry), querying, API key management, signals, dashboards, alerts, diagnostics, backups, and user management. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-13 14:34:10 +08:00
parent 1351371bd2
commit 55da2b74a4
3 changed files with 833 additions and 0 deletions
--- a/skills/seq-api/references/endpoints.md
+++ b/skills/seq-api/references/endpoints.md
@@ -0,0 +1,488 @@
+# Seq Server API — Complete Endpoint Reference
+
+This file lists every API endpoint provided by the Seq server, organized by resource group.
+
+## Table of Contents
+
+1. [api (root)](#api-root)
+2. [alerts](#alerts)
+3. [alertstate](#alertstate)
+4. [apikeys](#apikeys)
+5. [appinstances](#appinstances)
+6. [apps](#apps)
+7. [backups](#backups)
+8. [cluster](#cluster)
+9. [dashboards](#dashboards)
+10. [data (queries)](#data-queries)
+11. [deferred](#deferred)
+12. [diagnostics](#diagnostics)
+13. [events](#events)
+14. [expressionindexes](#expressionindexes)
+15. [expressions](#expressions)
+16. [feeds](#feeds)
+17. [indexes](#indexes)
+18. [licenses](#licenses)
+19. [permalinks](#permalinks)
+20. [retentionpolicies](#retentionpolicies)
+21. [roles](#roles)
+22. [runningtasks](#runningtasks)
+23. [settings](#settings)
+24. [signals](#signals)
+25. [sqlqueries](#sqlqueries)
+26. [updates](#updates)
+27. [users](#users)
+28. [workspaces](#workspaces)
+29. [health](#health)
+30. [ingestion](#ingestion)
+31. [other](#other)
+
+---
+
+## api (root)
+
+| Path | Method | Permission |
+|------|--------|------------|
+| `api` | GET | Public |
+
+Returns the root resource with links to all API resource groups.
+
+---
+
+## alerts
+
+Manage alert definitions. Users can only access shared alerts and their own. Protected alerts require `Project` permission.
+
+| Path | Method | Permission | Notes |
+|------|--------|------------|-------|
+| `api/alerts` | GET | Read | Shared + own only |
+| `api/alerts` | POST | Write | Project for protected |
+| `api/alerts/{id}` | GET | Read | Shared + own only |
+| `api/alerts/{id}` | PUT | Write | Project for protected |
+| `api/alerts/{id}` | DELETE | Write | Project for protected |
+| `api/alerts/resources` | GET | Public | |
+| `api/alerts/template` | GET | Write | |
+
+---
+
+## alertstate
+
+| Path | Method | Permission |
+|------|--------|------------|
+| `api/alertstate` | GET | Project |
+| `api/alertstate/{id}` | GET | Project |
+| `api/alertstate/{id}` | DELETE | Project |
+| `api/alertstate/resources` | GET | Public |
+
+---
+
+## apikeys
+
+Manage API keys. Non-Project principals can only view/manage their own keys.
+
+| Path | Method | Permission | Notes |
+|------|--------|------------|-------|
+| `api/apikeys` | GET | Read | Project sees all; others own only |
+| `api/apikeys` | POST | Write | Can only delegate own permissions |
+| `api/apikeys/{id}` | GET | Read | Project sees all; others own only |
+| `api/apikeys/{id}` | PUT | Write | Can only delegate own permissions |
+| `api/apikeys/{id}` | DELETE | Write | Project removes any; others own only |
+| `api/apikeys/{id}/metrics/{measurement}` | GET | Read | Own or Project |
+| `api/apikeys/metrics/{measurement}` | GET | Project | |
+| `api/apikeys/resources` | GET | Public | |
+| `api/apikeys/template` | GET | Read | |
+
+---
+
+## appinstances
+
+Manage installed Seq app instances. Non-Project principals see basic details only.
+
+| Path | Method | Permission | Notes |
+|------|--------|------------|-------|
+| `api/appinstances` | GET | Read | Basic details without Project |
+| `api/appinstances` | POST | System | |
+| `api/appinstances/{id}` | GET | Read | Basic details without Project |
+| `api/appinstances/{id}` | PUT | System | |
+| `api/appinstances/{id}` | DELETE | System | |
+| `api/appinstances/{id}/icon` | GET | Read | |
+| `api/appinstances/{id}/invoke` | POST | Write | Must be an output app; System for non-direct-invocation |
+| `api/appinstances/{id}/metrics/{measurement}` | GET | Project | |
+| `api/appinstances/resources` | GET | Public | |
+| `api/appinstances/template` | GET | System | |
+
+---
+
+## apps
+
+Manage app packages (install, update, remove). All require System permission.
+
+| Path | Method | Permission |
+|------|--------|------------|
+| `api/apps` | GET | System |
+| `api/apps/{id}` | GET | System |
+| `api/apps/{id}` | DELETE | System |
+| `api/apps/{id}/icon` | GET | System |
+| `api/apps/{id}/update` | POST | System |
+| `api/apps/install` | POST | System |
+| `api/apps/resources` | GET | Public |
+| `api/apps/template` | GET | System |
+
+---
+
+## backups
+
+| Path | Method | Permission | Notes |
+|------|--------|------------|-------|
+| `api/backups` | GET | System | |
+| `api/backups/{id}` | GET | System | |
+| `api/backups/files/{filename}` | GET | System | Download backup file |
+| `api/backups/immediate` | POST | System | Allows cross-site POSTs |
+| `api/backups/resources` | GET | Public | |
+
+---
+
+## cluster
+
+| Path | Method | Permission |
+|------|--------|------------|
+| `api/cluster` | GET | System |
+| `api/cluster/{id}` | GET | System |
+| `api/cluster/{id}/drain` | POST | System |
+| `api/cluster/resources` | GET | Public |
+
+---
+
+## dashboards
+
+Manage dashboards. Users can only access shared dashboards and their own. Protected dashboards require `Project` permission.
+
+| Path | Method | Permission | Notes |
+|------|--------|------------|-------|
+| `api/dashboards` | GET | Read | Shared + own only |
+| `api/dashboards` | POST | Write | Project for protected |
+| `api/dashboards/{id}` | GET | Read | Shared + own only |
+| `api/dashboards/{id}` | PUT | Write | Project for protected |
+| `api/dashboards/{id}` | DELETE | Write | Project for protected |
+| `api/dashboards/query/template` | GET | Write | |
+| `api/dashboards/resources` | GET | Public | |
+| `api/dashboards/template` | GET | Write | |
+
+---
+
+## data (queries)
+
+Execute SQL-style queries against the event stream.
+
+| Path | Method | Permission | Notes |
+|------|--------|------------|-------|
+| `api/data` | GET | Read | Query via query params |
+| `api/data` | POST | Read | Query via JSON body |
+| `api/data/{signalId}` | GET | Read | **Obsolete** |
+| `api/data/resources` | GET | Public | |
+
+---
+
+## deferred
+
+Retrieve results of long-running/deferred operations.
+
+| Path | Method | Permission |
+|------|--------|------------|
+| `api/deferred/{deferredId}` | GET | Read |
+
+---
+
+## diagnostics
+
+| Path | Method | Permission | Notes |
+|------|--------|------------|-------|
+| `api/diagnostics/status` | GET | Read | Basic server status |
+| `api/diagnostics/metrics` | GET | Project | |
+| `api/diagnostics/metrics/{measurement}` | GET | Project | |
+| `api/diagnostics/ingestion` | GET | System | |
+| `api/diagnostics/storage` | GET | Project | |
+| `api/diagnostics/report` | GET | System | Full diagnostic report |
+| `api/diagnostics/cluster/metrics` | GET | System | |
+| `api/diagnostics/usage-telemetry` | POST | Read | |
+| `api/diagnostics/resources` | GET | Public | |
+
+---
+
+## events
+
+Core event operations — retrieve, search, stream, delete by signal, and raw ingestion.
+
+| Path | Method | Permission | Notes |
+|------|--------|------------|-------|
+| `api/events` | GET | Read | List/search events |
+| `api/events/{id}` | GET | Read | Get single event |
+| `api/events/raw` | POST | Public* | Raw event ingestion; cross-site allowed. *Ingest required if RequireApiKeyForWritingEvents is on |
+| `api/events/scan` | GET | Read | |
+| `api/events/scan` | POST | Read | |
+| `api/events/signal` | GET | Read | |
+| `api/events/signal` | POST | Read | |
+| `api/events/signal` | DELETE | Project | Delete events matching signal |
+| `api/events/signal/{signalId}` | GET | Read | **Obsolete** |
+| `api/events/stream` | GET | Read | Live event stream (Server-Sent Events) |
+| `api/events/tabulate` | POST | Read | |
+| `api/events/tabulate/{signalId}` | GET | Read | |
+| `api/events/resources` | GET | Public | |
+
+---
+
+## expressionindexes
+
+| Path | Method | Permission |
+|------|--------|------------|
+| `api/expressionindexes` | GET | Read |
+| `api/expressionindexes` | POST | Write |
+| `api/expressionindexes/{id}` | GET | Read |
+| `api/expressionindexes/{id}` | DELETE | Write |
+| `api/expressionindexes/resources` | GET | Public |
+| `api/expressionindexes/template` | GET | Write |
+
+---
+
+## expressions
+
+| Path | Method | Permission |
+|------|--------|------------|
+| `api/expressions/sql` | GET | Read |
+| `api/expressions/strict` | GET | Read |
+| `api/expressions/resources` | GET | Public |
+
+---
+
+## feeds
+
+App package feeds. All require System permission.
+
+| Path | Method | Permission |
+|------|--------|------------|
+| `api/feeds` | GET | System |
+| `api/feeds` | POST | System |
+| `api/feeds/{id}` | GET | System |
+| `api/feeds/{id}` | PUT | System |
+| `api/feeds/{id}` | DELETE | System |
+| `api/feeds/resources` | GET | Public |
+| `api/feeds/template` | GET | System |
+
+---
+
+## indexes
+
+Signal indexes. Require Project permission.
+
+| Path | Method | Permission |
+|------|--------|------------|
+| `api/indexes` | GET | Project |
+| `api/indexes/{id}` | GET | Project |
+| `api/indexes/{id}` | DELETE | Project |
+| `api/indexes/resources` | GET | Public |
+
+---
+
+## licenses
+
+| Path | Method | Permission | Notes |
+|------|--------|------------|-------|
+| `api/licenses` | GET | System | |
+| `api/licenses/{id}` | GET | Read | Read sees status; System sees certificate details |
+| `api/licenses/{id}` | PUT | System | |
+| `api/licenses/downgrade` | POST | System | |
+| `api/licenses/resources` | GET | Public | |
+
+---
+
+## permalinks
+
+| Path | Method | Permission | Notes |
+|------|--------|------------|-------|
+| `api/permalinks` | GET | Read | Non-Project: own only |
+| `api/permalinks` | POST | Write | Non-Project: own only |
+| `api/permalinks/{id}` | GET | Read | Non-Project: own only |
+| `api/permalinks/{id}` | DELETE | Write | Non-Project: own only |
+| `api/permalinks/resources` | GET | Public | |
+| `api/permalinks/template` | GET | Write | |
+
+---
+
+## retentionpolicies
+
+All require Project permission.
+
+| Path | Method | Permission |
+|------|--------|------------|
+| `api/retentionpolicies` | GET | Project |
+| `api/retentionpolicies` | POST | Project |
+| `api/retentionpolicies/{id}` | GET | Project |
+| `api/retentionpolicies/{id}` | PUT | Project |
+| `api/retentionpolicies/{id}` | DELETE | Project |
+| `api/retentionpolicies/resources` | GET | Public |
+| `api/retentionpolicies/template` | GET | Project |
+
+---
+
+## roles
+
+| Path | Method | Permission |
+|------|--------|------------|
+| `api/roles` | GET | Read |
+| `api/roles/{id}` | GET | Read |
+| `api/roles/resources` | GET | Public |
+
+---
+
+## runningtasks
+
+| Path | Method | Permission |
+|------|--------|------------|
+| `api/runningtasks` | GET | System |
+| `api/runningtasks/{id}` | GET | System |
+| `api/runningtasks/{id}` | DELETE | System |
+| `api/runningtasks/resources` | GET | Public |
+
+---
+
+## settings
+
+Server settings. Most require System permission. Notable publicly accessible settings:
+
+| Path | Method | Permission | Notes |
+|------|--------|------------|-------|
+| `api/settings/{id}` | GET | System | Generic setting |
+| `api/settings/{id}` | PUT | System | |
+| `api/settings/setting-authenticationprovider` | GET | Public | |
+| `api/settings/setting-instancetitle` | GET | Public | |
+| `api/settings/setting-isauthenticationenabled` | GET | Public | |
+| `api/settings/setting-isactivedirectoryauthentication` | GET | Public | |
+| `api/settings/setting-isusagetelemetryenabled` | GET | Read | |
+| `api/settings/setting-searchdurationseconds` | GET | Read | |
+| `api/settings/setting-searchdurationseconds` | PUT | System | |
+| `api/settings/setting-servicenameexpression` | GET | Read | |
+| `api/settings/setting-servicenameexpression` | PUT | Project | |
+| `api/settings/setting-requireapikeyforwritingevents` | GET | Project | |
+| `api/settings/setting-requireapikeyforwritingevents` | PUT | Project | |
+| `api/settings/setting-newusershowdashboardids` | GET/PUT | Organization | |
+| `api/settings/setting-newusershowqueryids` | GET/PUT | Organization | |
+| `api/settings/setting-newusershowsignalids` | GET/PUT | Organization | |
+| `api/settings/setting-checkforupdates` | GET/PUT | System | |
+| `api/settings/setting-minimumfreestoragespace` | GET/PUT | System | |
+| `api/settings/setting-raweventmaximumcontentlength` | GET/PUT | System | |
+| `api/settings/setting-rawpayloadmaximumcontentlength` | GET/PUT | System | |
+| `api/settings/setting-themestyles` | GET/PUT | System | |
+| `api/settings/internal-error-reporting` | GET/PUT | System | |
+| `api/settings/resources` | GET | Public | |
+
+---
+
+## signals
+
+Saved signals. Users can only access shared signals and their own. Protected signals require `Project` permission.
+
+| Path | Method | Permission | Notes |
+|------|--------|------------|-------|
+| `api/signals` | GET | Read | Shared + own only |
+| `api/signals` | POST | Write | Project for protected |
+| `api/signals/{id}` | GET | Read | Shared + own only |
+| `api/signals/{id}` | PUT | Write | Project for protected |
+| `api/signals/{id}` | DELETE | Write | Project for protected |
+| `api/signals/resources` | GET | Public | |
+| `api/signals/template` | GET | Write | |
+
+---
+
+## sqlqueries
+
+Saved SQL queries. Same ownership/sharing rules as signals.
+
+| Path | Method | Permission | Notes |
+|------|--------|------------|-------|
+| `api/sqlqueries` | GET | Read | Shared + own only |
+| `api/sqlqueries` | POST | Write | Project for protected |
+| `api/sqlqueries/{id}` | GET | Read | Shared + own only |
+| `api/sqlqueries/{id}` | PUT | Write | Project for protected |
+| `api/sqlqueries/{id}` | DELETE | Write | Project for protected |
+| `api/sqlqueries/resources` | GET | Public | |
+| `api/sqlqueries/template` | GET | Write | |
+
+---
+
+## updates
+
+| Path | Method | Permission |
+|------|--------|------------|
+| `api/updates` | GET | System |
+| `api/updates/{id}` | GET | System |
+| `api/updates/resources` | GET | Public |
+
+---
+
+## users
+
+| Path | Method | Permission | Notes |
+|------|--------|------------|-------|
+| `api/users` | GET | Project | System for auth provider info |
+| `api/users` | POST | Organization | Cannot grant permissions you don't have |
+| `api/users/{id}` | GET | Public | Own record; Project for others |
+| `api/users/{id}` | PUT | Public | Own limited fields; Organization for others |
+| `api/users/{id}` | DELETE | Organization | |
+| `api/users/{id}/searches` | GET | Read | Own search history only |
+| `api/users/{id}/searches` | DELETE | Write | Own search history only |
+| `api/users/{id}/searches/update` | POST | Write | Own search history only |
+| `api/users/{id}/unlinkauthenticationprovider` | POST | System | |
+| `api/users/current` | GET | Public | Logged-in user only |
+| `api/users/login` | POST | Public | |
+| `api/users/logout` | POST | Public | Allows cross-site POSTs |
+| `api/users/providers` | GET | Public | |
+| `api/users/resources` | GET | Public | |
+| `api/users/template` | GET | Organization | |
+
+---
+
+## workspaces
+
+Same ownership/sharing rules as signals, dashboards, etc.
+
+| Path | Method | Permission | Notes |
+|------|--------|------------|-------|
+| `api/workspaces` | GET | Read | Shared + own only |
+| `api/workspaces` | POST | Write | Project for protected |
+| `api/workspaces/{id}` | GET | Read | Shared + own only |
+| `api/workspaces/{id}` | PUT | Write | Project for protected |
+| `api/workspaces/{id}` | DELETE | Write | Project for protected |
+| `api/workspaces/resources` | GET | Public | |
+| `api/workspaces/template` | GET | Write | |
+
+---
+
+## health
+
+| Path | Method | Permission | Notes |
+|------|--------|------------|-------|
+| `health` | GET | Public | Returns 200 or 503 |
+| `health/cluster` | GET | Public | Cluster health |
+
+---
+
+## ingestion
+
+| Path | Method | Permission | Notes |
+|------|--------|------------|-------|
+| `ingest/clef` | POST | Public* | CLEF format; cross-site allowed |
+| `ingest/otlp/v1/logs` | POST | Public* | OpenTelemetry logs |
+| `ingest/otlp/v1/traces` | POST | Public* | OpenTelemetry traces |
+| `ingest/otlp/v1/metrics` | POST | Public* | OpenTelemetry metrics |
+
+*If `RequireApiKeyForWritingEvents` is enabled, Ingest permission is required.
+
+---
+
+## other
+
+| Path | Method | Permission | Notes |
+|------|--------|------------|-------|
+| `integrated` | GET | Public | Windows integrated auth |
+| `oidc/challenge` | GET | Public | OpenID Connect |
+| `oidc/challenge` | POST | Public | OpenID Connect |
+| `theme/styles.css` | GET | Public | Custom theme CSS |
--- a/skills/seq-api/references/ingestion.md
+++ b/skills/seq-api/references/ingestion.md
@@ -0,0 +1,144 @@
+# Seq Ingestion Reference — CLEF Format & HTTP Details
+
+## Endpoint
+
+```
+POST {SEQ_URL}/ingest/clef
+```
+
+## Headers
+
+| Header | Value | Required |
+|--------|-------|----------|
+| `Content-Type` | `application/vnd.serilog.clef` (batch) or `application/json` (single event) | Yes |
+| `X-Seq-ApiKey` | Your API key | Only if `RequireApiKeyForWritingEvents` is enabled |
+
+Alternatively, the API key can be passed as a query parameter: `?apiKey={key}`
+
+## CLEF Format
+
+Events are newline-delimited JSON documents (one JSON object per line). Each object represents one log event.
+
+### Batch Example
+
+```
+{"@t":"2024-01-15T10:30:00.000Z","@mt":"Hello, {User}","User":"alice"}
+{"@t":"2024-01-15T10:30:01.123Z","@mt":"Processing order {OrderId}","OrderId":42,"@l":"Information"}
+{"@t":"2024-01-15T10:30:02.456Z","@mt":"Failed to process {OrderId}","OrderId":42,"@l":"Error","@x":"System.Exception: Something went wrong\n   at MyApp.OrderProcessor.Process()"}
+```
+
+### Reified Properties (Special @ Properties)
+
+Any JSON property at the top level is treated as a regular event property, **except** the following special properties:
+
+| Property | Name | Description | Required? |
+|----------|------|-------------|-----------|
+| `@t` | Timestamp | ISO 8601 timestamp | **Yes** |
+| `@m` | Message | Fully-rendered message text | No (use `@mt` or `@m`) |
+| `@mt` | Message Template | [Message template](http://messagetemplates.org) with named holes like `{User}` | No (alternative to `@m`) |
+| `@l` | Level | Log level string: `Verbose`, `Debug`, `Information`, `Warning`, `Error`, `Fatal` | No (defaults to Information) |
+| `@x` | Exception | Error/backtrace as a string | No |
+| `@i` | Event ID | Event type identifier (numeric or hex string) | No |
+| `@r` | Renderings | Pre-rendered values for format tokens in `@mt` | No |
+| `@tr` | Trace ID | Groups spans/logs in the same trace | Required for spans |
+| `@sp` | Span ID | Unique span identifier | Required for spans |
+| `@ps` | Parent Span ID | Parent span's ID; absent = root span | No |
+| `@st` | Span Start | ISO 8601 start timestamp of the span | Required for spans |
+| `@sc` | Instrumentation Scope | App-local component name | No |
+| `@ra` | Resource Attributes | System-level component descriptor | No |
+| `@sk` | Span Kind | `Client`, `Server`, `Internal`, `Producer`, or `Consumer` | No |
+
+### Escaping @ in Property Names
+
+To use a property name starting with `@`, double it: `@@myProp` becomes `@myProp` in Seq.
+
+### Batch Delimiters
+
+Use `\n` or `\r\n` between JSON objects. No trailing delimiter is required but is harmless.
+
+## Status Codes
+
+| Code | Meaning |
+|------|---------|
+| **201** Created | Events ingested successfully |
+| **400** Bad Request | Malformed payload or event exceeds max size |
+| **401** Unauthorized | API key missing or invalid |
+| **403** Forbidden | API key lacks Ingest permission |
+| **413** Request Entity Too Large | Payload exceeds configured max size |
+| **500** Internal Server Error | Server-side error; check Seq diagnostics |
+| **503** Service Unavailable | Server starting up, or storage space below threshold |
+
+## Response Format
+
+### Success (201)
+
+```json
+{"MinimumLevelAccepted": null}
+```
+
+`MinimumLevelAccepted` will be one of `Verbose`, `Debug`, `Information`, `Warning`, `Error`, `Fatal` if a level filter is applied to the API key, or `null` if no filtering. Clients can use this to pre-filter events and reduce bandwidth.
+
+### Error (4xx/5xx)
+
+```json
+{"Error": "Description of what went wrong"}
+```
+
+## OpenTelemetry Ingestion
+
+Seq also accepts OpenTelemetry Protocol (OTLP) payloads:
+
+| Path | Purpose |
+|------|---------|
+| `ingest/otlp/v1/logs` | OTLP logs |
+| `ingest/otlp/v1/traces` | OTLP traces |
+| `ingest/otlp/v1/metrics` | OTLP metrics |
+
+These follow the standard OTLP HTTP specification. The same API key authentication rules apply.
+
+## Raw Events Endpoint (Legacy)
+
+The older `api/events/raw` endpoint also accepts event ingestion with cross-site POST support. The `/ingest/clef` endpoint is preferred for new integrations.
+
+## Common curl Examples
+
+### Send a single event
+
+```bash
+curl -X POST "https://seq.example.com/ingest/clef" \
+  -H "Content-Type: application/vnd.serilog.clef" \
+  -H "X-Seq-ApiKey: YOUR_API_KEY" \
+  -d '{"@t":"2024-01-15T10:30:00Z","@mt":"Deployment started for {App}","App":"myservice","@l":"Information"}'
+```
+
+### Send a batch
+
+```bash
+curl -X POST "https://seq.example.com/ingest/clef" \
+  -H "Content-Type: application/vnd.serilog.clef" \
+  -H "X-Seq-ApiKey: YOUR_API_KEY" \
+  -d '{"@t":"2024-01-15T10:30:00Z","@mt":"Step 1 complete","@l":"Information"}
+{"@t":"2024-01-15T10:30:01Z","@mt":"Step 2 complete","@l":"Information"}
+{"@t":"2024-01-15T10:30:02Z","@mt":"All steps done","@l":"Information"}'
+```
+
+### Send with an API key in the query string
+
+```bash
+curl -X POST "https://seq.example.com/ingest/clef?apiKey=YOUR_API_KEY" \
+  -H "Content-Type: application/vnd.serilog.clef" \
+  -d '{"@t":"2024-01-15T10:30:00Z","@mt":"Hello from curl"}'
+```
+
+### Query events via the data API
+
+```bash
+curl "https://seq.example.com/api/data?q=select%20count(*)%20from%20stream%20group%20by%20%40Level&rangeStartUtc=2024-01-01&rangeEndUtc=2024-01-02" \
+  -H "X-Seq-ApiKey: YOUR_API_KEY"
+```
+
+### Check server health
+
+```bash
+curl https://seq.example.com/health
+```