# Submission API

Use `POST /api/submit` to send benchmark results to the server.

## Endpoint

- Method: `POST`
- URL: `/api/submit`
- Content-Types:
  - `application/json`
  - `multipart/form-data`

## Schema

- Import URL: `/api/schema`
- Source file in repo: `docs/submit-schema.json`

## JSON format

Clients can send either:

1. An envelope with `submitter`, `platform`, optional `systemInfo`, and nested `benchmark`
2. A flat benchmark payload with optional `submitter`, `platform`, and optional `systemInfo`

Example envelope:

```json
{
  "submitter": "AMD Bazzite",
  "platform": "linux",
  "systemInfo": {
    "hostname": "bench-rig-01",
    "osName": "Bazzite",
    "osVersion": "41",
    "distro": "Fedora Atomic",
    "kernelVersion": "6.14.2-300.fc41.x86_64",
    "kernelArch": "x86_64",
    "architecture": "amd64",
    "locale": "en-US",
    "timezone": "Europe/Bucharest",
    "country": "Romania",
    "city": "Bucharest",
    "clientVersion": "1.4.0",
    "appVersion": "desktop-1.4.0",
    "sessionID": "session-123",
    "userID": "anonymous-user",
    "extra": {
      "gpuDriver": "Mesa 25.0.3",
      "desktopEnvironment": "KDE Plasma"
    }
  },
  "benchmark": {
    "config": {
      "durationSecs": 10,
      "intensity": 1,
      "coreFilter": 0,
      "multiCore": true
    },
    "cpuInfo": {
      "brandString": "AMD Ryzen 9 9950X3D 16-Core Processor",
      "vendorID": "AuthenticAMD",
      "physicalCores": 16,
      "logicalCores": 32,
      "baseClockMHz": 5756,
      "boostClockMHz": 0,
      "l1DataKB": 48,
      "l2KB": 1024,
      "l3MB": 32,
      "isHybrid": false,
      "has3DVCache": true,
      "supportedFeatures": ["SSE4.2", "AVX", "AVX2"]
    },
    "startedAt": "2026-04-17T13:20:09.170770511+03:00",
    "duration": 10003356676,
    "totalOps": 543678267392,
    "mOpsPerSec": 54349.58334499758,
    "score": 5434958,
    "coreResults": [
      {
        "logicalID": 0,
        "coreType": "Standard",
        "mOpsPerSec": 1642.986525056302,
        "totalOps": 16435380224
      }
    ]
  }
}
```

## Multipart format

Multipart requests may include:

- `submitter`: text field
- `platform`: text field
- `systemInfo`: JSON text field
- `benchmark`, `file`, or `benchmarkFile`: benchmark JSON file field

Example `systemInfo` field value:

```json
{
  "osName": "Windows",
  "osVersion": "11 24H2",
  "kernelVersion": "10.0.26100",
  "architecture": "amd64",
  "locale": "en-US",
  "timezone": "America/New_York"
}
```

## Notes

- `systemInfo` is optional. Older clients do not need to send it.
- The server may enrich stored analytics with request metadata such as `ipAddress`, `forwardedFor`, `userAgent`, and `locale`.
- `baseClockMHz` and related CPU clock fields currently expect integer MHz values.
- Full JSON Schema is available in [submit-schema.json](./submit-schema.json) and is served by `GET /api/schema`.