From 55da2b74a43272b5b6fd80044f7f7f7161d7096f Mon Sep 17 00:00:00 2001 From: Misaka_Company Date: Mon, 13 Apr 2026 14:34:10 +0800 Subject: [PATCH] =?UTF-8?q?=E2=9C=A8=20feat:=20Add=20seq-api=20skill=20for?= =?UTF-8?q?=20Seq=20structured=20log=20server=20HTTP=20API?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- skills/seq-api/SKILL.md | 201 ++++++++++ skills/seq-api/references/endpoints.md | 488 +++++++++++++++++++++++++ skills/seq-api/references/ingestion.md | 144 ++++++++ 3 files changed, 833 insertions(+) create mode 100644 skills/seq-api/SKILL.md create mode 100644 skills/seq-api/references/endpoints.md create mode 100644 skills/seq-api/references/ingestion.md diff --git a/skills/seq-api/SKILL.md b/skills/seq-api/SKILL.md new file mode 100644 index 0000000..9308c25 --- /dev/null +++ b/skills/seq-api/SKILL.md @@ -0,0 +1,201 @@ +--- +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. diff --git a/skills/seq-api/references/endpoints.md b/skills/seq-api/references/endpoints.md new file mode 100644 index 0000000..272bde7 --- /dev/null +++ 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 | diff --git a/skills/seq-api/references/ingestion.md b/skills/seq-api/references/ingestion.md new file mode 100644 index 0000000..8bfea72 --- /dev/null +++ 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 +```