1 files changed, 49 insertions, 0 deletions
diff --git a/docs/guides/data-formats.md b/docs/guides/data-formats.md
new file mode 100644
index 0000000..24d7755
--- /dev/null
+++ b/docs/guides/data-formats.md
@@ -0,0 +1,49 @@
+# Data Formats
+
+Epimetheus accepts CSV and JSON input for **auto mode** (and for **watch mode**, watch uses tabular CSV; see [CSV Format Flexibility](csv-format-flexibility.md)).
+
+## Epimetheus CSV (auto mode)
+
+Format: one metric per line with explicit metric name, labels, value, and optional timestamp.
+
+```csv
+# Format: metric_name,labels,value,timestamp_ms
+# Labels: key1=value1;key2=value2
+epimetheus_test_requests_total,instance=web1;env=prod,100,1767125148000
+epimetheus_test_temperature_celsius,instance=web2,22.5,1767038748000
+
+# Timestamp optional (uses "now" if omitted)
+epimetheus_test_active_connections,instance=web3,42,
+```
+
+- **metric_name** – Prometheus metric name.
+- **labels** – Semicolon-separated `key=value` pairs.
+- **value** – Numeric value.
+- **timestamp_ms** – Unix milliseconds. Omit or leave empty for "now".
+
+## JSON (auto mode)
+
+Array of objects with `metric`, `labels`, `value`, and optional `timestamp_ms`:
+
+```json
+[
+  {
+    "metric": "epimetheus_test_requests_total",
+    "labels": {"instance": "web1", "env": "prod"},
+    "value": 100,
+    "timestamp_ms": 1767125148000
+  },
+  {
+    "metric": "epimetheus_test_temperature_celsius",
+    "labels": {"instance": "web2"},
+    "value": 22.5,
+    "timestamp_ms": 1767038748000
+  }
+]
+```
+
+Omit `timestamp_ms` for "now".
+
+## Watch mode CSV
+
+Watch mode uses **tabular CSV**: first row = headers, following rows = data. Numeric columns become metrics (with `-metric-name` as prefix), string columns become labels. See [CSV Format Flexibility](csv-format-flexibility.md).