Update API ref docs

content/docs/api/index.mdx

@@ -6,7 +6,9 @@ redirect_from:
 
 import { Card, Cards } from 'fumadocs-ui/components/card';
 
-This section provides detailed information about the available API endpoints for interacting with Parseable.
+This section is the quickest way to understand how data reaches Parseable and which HTTP endpoint fits your integration.
+
+Most teams do not need every route listed here. In practice, you usually start with one ingestion path, send data into a dataset, and then use the query and dataset APIs only when you need direct control from your own tooling.
 
 ## Getting Started
 
@@ -15,70 +17,96 @@ Before you begin, make sure you have:
 - The base URL of your Parseable server
 - Required authentication credentials (if authentication is enabled)
 
-## API Endpoints
+Most integrations fall into one of these paths:
+
+- Use `/api/v1/ingest` when your application already has JSON events and you want to route them with headers.
+- Use `/v1/logs`, `/v1/traces`, or `/v1/metrics` when your collector or SDK is already sending native OTLP data.
+- Use `/v1/prometheus/write` when Prometheus or another compatible system is forwarding metrics through Remote Write.
+- Use `/api/v1/query` and `/api/v1/logstream/{stream_name}` when you need SQL queries or direct dataset management from your own code.
+
+If you are deciding where to start, the simplest rule is this:
+
+- JSON events from an app or script: `/api/v1/ingest`
+- OpenTelemetry logs: `/v1/logs`
+- OpenTelemetry traces: `/v1/traces`
+- OpenTelemetry metrics: `/v1/metrics`
+- Prometheus Remote Write metrics: `/v1/prometheus/write`
+
+## Ingestion APIs
 
 <Cards>
   <Card 
-    href="/docs/api/v1/logstream/stream_name/put"
-    title="Create log dataset"
+    href="/api/v1/ingestLogsWithHeaders"
+    title="Ingest JSON events with headers"
   >
-    Create a new log dataset with the specified name and configuration.
+    Send JSON events and route them with the `X-P-Stream` header.
   </Card>
   <Card 
-    href="/docs/api/v1/logstream/stream_name/post"
-    title="Send logs to a dataset"
+    href="/api/v1/ingestOtlpLogs"
+    title="Ingest OTLP logs"
   >
-    Send logs to an existing log dataset.
+    Send OpenTelemetry logs to Parseable using the native `/v1/logs` endpoint.
   </Card>
-
   <Card 
-    href="/docs/api/v1/logstream/stream_name/delete"
-    title="Delete log dataset"
+    href="/api/v1/ingestOtlpTraces"
+    title="Ingest OTLP traces"
   >
-    Delete an existing log dataset and all its associated data.
+    Send OpenTelemetry traces to Parseable using the native `/v1/traces` endpoint.
   </Card>
-
   <Card 
-    href="/docs/api/v1/ingest"
-    title="Ingest logs with headers"
+    href="/api/v1/ingestOtlpMetrics"
+    title="Ingest OTLP metrics"
   >
-    Send log data to a specific log dataset using HTTP headers.
+    Send OpenTelemetry metrics to Parseable using the native `/v1/metrics` endpoint.
   </Card>
+  <Card
+    href="/api/v1/prometheusRemoteWrite"
+    title="Prometheus Remote Write"
+  >
+    Send snappy-compressed Prometheus Remote Write payloads to `/v1/prometheus/write`.
+  </Card>
+</Cards>
 
+## Query and Dataset APIs
+
+<Cards>
+  <Card 
+    href="/api/v1/queryLogStream"
+    title="Query a dataset with SQL"
+  >
+    Run SQL queries across datasets. The dataset is selected inside the `FROM` clause.
+  </Card>
   <Card 
-    href="/docs/api/v1/query"
-    title="Query API"
+    href="/api/v1/sendLogsToStream"
+    title="Send JSON events to a dataset"
   >
-    Query data from log streams using SQL.
+    Send JSON events directly to an existing dataset by path.
+  </Card>
+  <Card 
+    href="/api/v1/createLogStream"
+    title="Create a dataset"
+  >
+    Create a dataset before writing events directly to `/api/v1/logstream/{stream_name}`.
+  </Card>
+  <Card 
+    href="/api/v1/deleteLogStream"
+    title="Delete a dataset"
+  >
+    Delete a dataset and its associated data.
   </Card>
 </Cards>
 
 ## Authentication
 
-API reference endpoints require authentication. The OpenAPI reference uses HTTP Basic authentication by default:
+These endpoints require authentication. The reference uses HTTP Basic authentication in the examples:
 
 ```bash
 Authorization: Basic <base64-encoded-credentials>
 ```
 
 If you use Parseable API keys, send the key in the `X-API-Key` header as described in the [API Keys](/docs/user-guide/api-keys) guide.
 
-## Rate Limiting
-
-API requests are subject to rate limiting. The default rate limit is 100 requests per minute per IP address.
-
-## Error Handling
-
-All error responses follow a standard format:
-
-```json
-{
-  "error": {
-    "code": "error_code",
-    "message": "Human-readable error message"
-  }
-}
-```
+For ingestion endpoints, the other header to pay attention to is usually `X-P-Stream`. That header tells Parseable which dataset should receive the payload. OTLP routes also use `X-P-Log-Source` to identify whether the payload is logs, traces, or metrics.
 
 ## Need Help?
 

content/docs/api/meta.json

@@ -3,9 +3,13 @@
   "pages": [
     "---v1---",
     "v1/ingestLogsWithHeaders",
+    "v1/ingestOtlpLogs",
+    "v1/ingestOtlpTraces",
+    "v1/ingestOtlpMetrics",
+    "v1/prometheusRemoteWrite",
     "v1/queryLogStream",
-    "v1/deleteLogStream",
     "v1/sendLogsToStream",
-    "v1/createLogStream"
+    "v1/createLogStream",
+    "v1/deleteLogStream"
   ]
 }

content/docs/api/v1/createLogStream.mdx

@@ -1,5 +1,5 @@
 ---
-title: Create a log dataset
+title: Create a dataset
 full: true
 _openapi:
   method: PUT
@@ -8,20 +8,16 @@ _openapi:
     headings: []
     contents:
       - content: >
-          This endpoint is used to create a new log dataset within Parseable.  
-
-          A **log dataset** is a group of similar logs. For example, you can
-          create a log dataset for a specific application's logs, another log
-          dataset for your database logs, and so on. You can create as many log
-          streams as needed to organize and manage logs efficiently.
+          Create a dataset in Parseable using the dataset name in the path.
 ---
 {/* Define variables for path parameters */}
 export const stream_name = "stream_name";
 
 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
 
-This endpoint is used to create a new log dataset within Parseable.  
-A **log dataset** is a group of similar logs. For example, you can create a log dataset for a specific application's logs, another log dataset for your database logs, and so on. You can create as many log streams as needed to organize and manage logs efficiently.  
+Create a dataset before you start sending data directly to a named stream endpoint.
+
+Use this route when you want the dataset name to be part of the URL itself, for example before writing JSON events to `/api/v1/logstream/{stream_name}`. Once the dataset exists, other ingestion calls can target it normally.
 
 
-<APIPage document={"./public/parseable-api-schema-cleaned.yaml"} operations={[{"path":"/api/v1/logstream/{stream_name}","method":"put"}]} />
+<APIPage document={"./public/parseable-api-schema-cleaned.yaml"} operations={[{"path":"/api/v1/logstream/{stream_name}","method":"put"}]} />

content/docs/api/v1/deleteLogStream.mdx

@@ -1,5 +1,5 @@
 ---
-title: Delete a log dataset
+title: Delete a dataset
 full: true
 _openapi:
   method: DELETE
@@ -8,18 +8,19 @@ _openapi:
     headings: []
     contents:
       - content: >
-          This endpoint is used to delete an existing log dataset.
+          Delete an existing dataset.
 
-          When a log dataset is deleted, all associated data is permanently
+          When a dataset is deleted, all associated data is permanently
           removed.
 ---
 {/* Define variables for path parameters */}
 export const stream_name = "stream_name";
 
 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
 
-This endpoint is used to delete an existing log dataset.
-When a log dataset is deleted, all associated data is permanently removed.
+Delete an existing dataset when you no longer want to keep its data or accept new writes to it.
 
+This is a destructive operation. Once a dataset is deleted, the associated data is removed as well, so this route is usually used from admin tooling or controlled cleanup workflows.
 
-<APIPage document={"./public/parseable-api-schema-cleaned.yaml"} operations={[{"path":"/api/v1/logstream/{stream_name}","method":"delete"}]} />
+
+<APIPage document={"./public/parseable-api-schema-cleaned.yaml"} operations={[{"path":"/api/v1/logstream/{stream_name}","method":"delete"}]} />

content/docs/api/v1/ingestLogsWithHeaders.mdx

@@ -1,5 +1,5 @@
 ---
-title: Ingest logs with headers
+title: Ingest JSON events with headers
 full: true
 _openapi:
   method: POST
@@ -8,94 +8,16 @@ _openapi:
     headings: []
     contents:
       - content: >
-          **Log Ingestion API via Custom Headers**  
+          Send JSON events and route them with request headers.
 
-          This approach allows you to send logs to Parseable using custom
-          headers to specify the target dataset.  
-
-
-          Required headers:
-
-          - **X-P-Stream**: The name of the dataset to ingest logs into
-
-
-          The API accepts logs in JSON format. You can send single log entries
-          or arrays of log entries.
-
-
-          Example:
-
-          ```json
-
-          {
-            "level": "info",
-            "message": "User logged in",
-            "timestamp": "2023-01-01T12:00:00Z",
-            "user_id": "user123"
-          }
-
-          ```
-
-
-          Or as an array:
-
-          ```json
-
-          [
-            {
-              "level": "info",
-              "message": "User logged in",
-              "timestamp": "2023-01-01T12:00:00Z",
-              "user_id": "user123"
-            },
-            {
-              "level": "error",
-              "message": "Failed to process request",
-              "timestamp": "2023-01-01T12:01:00Z",
-              "error_code": "ERR-1001"
-            }
-          ]
-
-          ```
+          Use `X-P-Stream` to specify the destination dataset.
 ---
 
 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
 
-**Log Ingestion API via Custom Headers**  
-This approach allows you to send logs to Parseable using custom headers to specify the target dataset.  
-
-Required headers:
-- **X-P-Stream**: The name of the dataset to ingest logs into
-
-The API accepts logs in JSON format. You can send single log entries or arrays of log entries.
-
-Example:
-```json
-{
-  "level": "info",
-  "message": "User logged in",
-  "timestamp": "2023-01-01T12:00:00Z",
-  "user_id": "user123"
-}
-```
+Use this route when your application already produces plain JSON and you want Parseable to store it without going through an OTLP pipeline.
 
-Or as an array:
-```json
-[
-  {
-    "level": "info",
-    "message": "User logged in",
-    "timestamp": "2023-01-01T12:00:00Z",
-    "user_id": "user123"
-  },
-  {
-    "level": "error",
-    "message": "Failed to process request",
-    "timestamp": "2023-01-01T12:01:00Z",
-    "error_code": "ERR-1001"
-  }
-]
-```
+The important header here is `X-P-Stream`. It tells Parseable which dataset should receive the payload. This route works well for custom app logs, quick integrations, scripts, and services that already emit JSON records.
 
 
-<APIPage document={"./public/parseable-api-schema-cleaned.yaml"} operations={[{"path":"/api/v1/ingest","method":"post"}]} />
+<APIPage document={"./public/parseable-api-schema-cleaned.yaml"} operations={[{"path":"/api/v1/ingest","method":"post"}]} />

content/docs/api/v1/ingestOtlpLogs.mdx

@@ -0,0 +1,20 @@
+---
+title: Ingest OTLP logs
+full: true
+_openapi:
+  method: POST
+  toc: []
+  structuredData:
+    headings: []
+    contents:
+      - content: >
+          Send OpenTelemetry logs to Parseable using the native `/v1/logs`
+          endpoint. Use `X-P-Stream` to choose the destination dataset and
+          `X-P-Log-Source: otel-logs` to identify the payload type.
+---
+
+Use this route when your collector or SDK is already exporting OpenTelemetry logs in OTLP format.
+
+`X-P-Stream` chooses the destination dataset, and `X-P-Log-Source: otel-logs` tells Parseable how to interpret the payload. This is the route to use when you want native OTLP logs rather than custom JSON ingestion.
+
+<APIPage document={"./public/parseable-api-schema-cleaned.yaml"} operations={[{"path":"/v1/logs","method":"post"}]} />

content/docs/api/v1/ingestOtlpMetrics.mdx

@@ -0,0 +1,20 @@
+---
+title: Ingest OTLP metrics
+full: true
+_openapi:
+  method: POST
+  toc: []
+  structuredData:
+    headings: []
+    contents:
+      - content: >
+          Send OpenTelemetry metrics to Parseable using the native `/v1/metrics`
+          endpoint. Use `X-P-Stream` to choose the destination dataset and
+          `X-P-Log-Source: otel-metrics` to identify the payload type.
+---
+
+Use this route when OpenTelemetry metrics are being forwarded directly to Parseable.
+
+`X-P-Stream` chooses the destination dataset, and `X-P-Log-Source: otel-metrics` marks the payload as OTLP metrics. This route is useful when metrics are already in the OpenTelemetry pipeline and do not need Prometheus Remote Write.
+
+<APIPage document={"./public/parseable-api-schema-cleaned.yaml"} operations={[{"path":"/v1/metrics","method":"post"}]} />

content/docs/api/v1/ingestOtlpTraces.mdx

@@ -0,0 +1,20 @@
+---
+title: Ingest OTLP traces
+full: true
+_openapi:
+  method: POST
+  toc: []
+  structuredData:
+    headings: []
+    contents:
+      - content: >
+          Send OpenTelemetry traces to Parseable using the native `/v1/traces`
+          endpoint. Use `X-P-Stream` to choose the destination dataset and
+          `X-P-Log-Source: otel-traces` to identify the payload type.
+---
+
+Use this route when your collector or SDK is exporting OpenTelemetry traces and you want Parseable to receive them directly.
+
+`X-P-Stream` chooses the destination dataset, and `X-P-Log-Source: otel-traces` identifies the payload type. This is the endpoint to use for native OTLP traces instead of custom event ingestion.
+
+<APIPage document={"./public/parseable-api-schema-cleaned.yaml"} operations={[{"path":"/v1/traces","method":"post"}]} />