# Payload


## Endpoint

`POST https://ingress.flareapp.io/v1/logs`

### Headers

| Header         | Value              | Description |
|----------------|--------------------|-------------|
| `Content-Type` | `application/json` | Required    |
| `Accept`       | `application/json` | Required    |
| `x-api-token`  | `{apiToken}`       | API token   |

## Authentication

Authenticate using your project's **private API key** in the `x-api-token` header. 

## Payload

The log payload follows the OpenTelemetry protocol structure.

| Field          | Type  | Validation          | Description                       |
|----------------|-------|---------------------|-----------------------------------|
| `resourceLogs` | array | required, non-empty | Array of resource log objects |

### Resource Logs

| Field       | Type   | Validation          | Description                           |
|-------------|--------|---------------------|---------------------------------------|
| `resource`  | object | required            | The resource producing these logs     |
| `scopeLogs` | array  | required, non-empty | Array of scope log objects            |

#### Resource

A resource represents the entity producing telemetry data (your application/service). For a list of common resource attributes, see [Resources](/docs/protocol/general/resources).

| Field                    | Type  | Validation | Description                |
|--------------------------|-------|------------|----------------------------|
| `attributes`             | array | required   | OTEL-format key-value pairs |
| `droppedAttributesCount` | int   | optional   | Number of dropped attributes |

### Scope Logs

| Field        | Type   | Validation          | Description                    |
|--------------|--------|---------------------|--------------------------------|
| `scope`      | object | required            | The instrumentation scope      |
| `logRecords` | array  | required, non-empty | Array of log record objects    |

#### Scope

A scope represents the instrumentation library that produced the logs.

| Field                    | Type          | Validation          | Description                       |
|--------------------------|---------------|---------------------|-----------------------------------|
| `name`                   | string        | required, non-empty | Instrumentation scope name        |
| `version`                | string/number | optional            | Instrumentation scope version     |
| `attributes`             | array         | optional            | OTEL-format key-value pairs       |
| `droppedAttributesCount` | int           | optional            | Number of dropped attributes      |

### Log Records

A log record represents a single log entry. Each record must have at least one timestamp field (`timeUnixNano` or `observedTimeUnixNano`).

| Field                    | Type        | Validation                                            | Description                                         |
|--------------------------|-------------|-------------------------------------------------------|-----------------------------------------------------|
| `timeUnixNano`           | string      | required if `observedTimeUnixNano` is absent          | Time the event occurred, in nanoseconds             |
| `observedTimeUnixNano`   | string      | required if `timeUnixNano` is absent                  | Time the log was observed/collected, in nanoseconds |
| `severityNumber`         | int         | optional                                              | Numeric severity (1-24, see below)                  |
| `severityText`           | string      | optional                                              | Human-readable severity (e.g. `INFO`, `ERROR`)      |
| `body`                   | value       | optional                                              | The log message body (see [Attribute Formats](/docs/protocol/general/attribute-formats#value-types)) |
| `attributes`             | array       | optional                                              | OTEL-format key-value pairs                         |
| `droppedAttributesCount` | int         | optional                                              | Number of dropped attributes                        |
| `flags`                  | int         | optional                                              | Log record flags                                    |
| `traceId`                | string      | optional                                              | Trace identifier for log-trace correlation          |
| `spanId`                 | string      | optional                                              | Span identifier for log-trace correlation           |

#### Severity Numbers

Severity numbers follow the [OpenTelemetry severity mapping](https://opentelemetry.io/docs/specs/otel/logs/data-model/#severity-fields):

| Range | Name    |
|-------|---------|
| 1-4   | TRACE   |
| 5-8   | DEBUG   |
| 9-12  | INFO    |
| 13-16 | WARN    |
| 17-20 | ERROR   |
| 21-24 | FATAL   |

### Attribute Format

All attributes and the log record `body` field use the OpenTelemetry typed attribute format. See [Attribute Formats](/docs/protocol/general/attribute-formats) for the full format specification and value types.

### Entry Point

A log record produced inside a request, command, or job may carry the `flare.entry_point.*` attributes that describe the surrounding work. This lets logs be filtered alongside the errors and traces from the same source. See [Entry points](/docs/protocol/general/entry-points) for the schema.

## Responses

All responses include CORS headers (`Access-Control-Allow-Origin: *`) and return `application/json`.

| Status | Description                                                                           |
|--------|---------------------------------------------------------------------------------------|
| `201`  | Log accepted                                                                          |
| `401`  | Missing API key                                                                       |
| `403`  | Invalid API key                                                                       |
| `405`  | HTTP method not allowed (only `POST` is accepted)                                     |
| `422`  | Validation error (missing `resourceLogs`, missing log records, missing timestamp)     |
| `429`  | Rate limit or log quota exceeded                                                      |

Success response:

```json
{}
```

Validation error responses include the field path and a description of the issue:

```json
{
    "message": "The given data was invalid.",
    "errors": {
        "resourceLogs.0.scopeLogs.0.logRecords.0.timeUnixNano": [
            "Either timeUnixNano or observedTimeUnixNano is required."
        ]
    }
}
```

## Example

```json
{
    "resourceLogs": [
        {
            "resource": {
                "attributes": [
                    { "key": "service.name", "value": { "stringValue": "My Application" } },
                    { "key": "service.version", "value": { "stringValue": "1.0.0" } },
                    { "key": "service.stage", "value": { "stringValue": "production" } },
                    { "key": "telemetry.sdk.language", "value": { "stringValue": "PHP" } },
                    { "key": "telemetry.sdk.name", "value": { "stringValue": "spatie/flare-client-php" } },
                    { "key": "telemetry.sdk.version", "value": { "stringValue": "1.0.0" } }
                ],
                "droppedAttributesCount": 0
            },
            "scopeLogs": [
                {
                    "scope": {
                        "name": "spatie/laravel-flare",
                        "version": "1.0.0"
                    },
                    "logRecords": [
                        {
                            "timeUnixNano": "1710252000000000000",
                            "observedTimeUnixNano": "1710252000000000000",
                            "severityNumber": 9,
                            "severityText": "INFO",
                            "body": {
                                "stringValue": "User logged in successfully"
                            },
                            "attributes": [
                                { "key": "user.id", "value": { "intValue": 42 } },
                                { "key": "http.route", "value": { "stringValue": "/login" } }
                            ],
                            "droppedAttributesCount": 0,
                            "traceId": "a1b2c3d4e5f67890a1b2c3d4e5f67890",
                            "spanId": "1234567890abcdef"
                        },
                        {
                            "timeUnixNano": "1710252001000000000",
                            "observedTimeUnixNano": "1710252001000000000",
                            "severityNumber": 17,
                            "severityText": "ERROR",
                            "body": {
                                "stringValue": "Failed to send welcome email"
                            },
                            "attributes": [
                                { "key": "exception.type", "value": { "stringValue": "Swift_TransportException" } },
                                { "key": "exception.message", "value": { "stringValue": "Connection refused" } }
                            ],
                            "droppedAttributesCount": 0
                        }
                    ]
                }
            ]
        }
    ]
}
```