# 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
```