> ## Documentation Index
> Fetch the complete documentation index at: https://opendata.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Remote write

> Ingest time series data using the
[Prometheus Remote Write 1.0](https://prometheus.io/docs/specs/prw/remote_write_spec/)
protocol.

The request body must be a **Snappy-compressed** protobuf `WriteRequest`
message (as defined by the Prometheus remote write specification). Each
`WriteRequest` contains one or more `TimeSeries` messages, each with a
set of labels and one or more timestamp/value sample pairs.

This endpoint is designed for integration with Prometheus remote-write
compatible agents and collectors. It is not intended as a general-purpose
high-throughput ingestion path — for bulk data loading, prefer dedicated
import tooling.

This endpoint is only available when the server is built with
the `remote-write` feature.




## OpenAPI

````yaml /openapi/timeseries.yaml post /api/v1/write
openapi: 3.1.0
info:
  title: OpenData Timeseries API
  version: 1.0.0
  description: |
    Prometheus-compatible HTTP API for the OpenData Timeseries service.

    Query endpoints accept both GET (query parameters) and POST
    (application/x-www-form-urlencoded body) with identical parameters.
    This spec documents the GET form; POST is always available as an
    alternative for large queries that may exceed URL character limits.

    ## Timestamp formats

    All timestamp parameters accept either **RFC 3339** format
    (e.g. `2024-01-20T00:00:00Z`) or **Unix seconds** as a float
    (e.g. `1705708800` or `1705708800.123`). Timestamps in responses are
    always Unix seconds.

    ## Duration format

    Duration parameters use PromQL duration syntax: an integer followed by a
    unit suffix. Supported units are `ms` (milliseconds), `s` (seconds),
    `m` (minutes), `h` (hours), `d` (days), `w` (weeks), and `y` (years).
    Examples: `30s`, `5m`, `1h30m`.

    ## Sample values

    Sample values are always transferred as JSON strings (not numbers) to
    allow special values such as `"NaN"`, `"+Inf"`, and `"-Inf"`.

    ## Response envelope

    Every JSON response follows a common envelope:
    ```json
    {
      "status": "success" | "error",
      "data": <payload>,
      "errorType": "<string>",
      "error": "<string>",
      "warnings": ["<string>"]
    }
    ```
    The `error` and `errorType` fields are only present when `status` is
    `"error"`. The `warnings` array may be present on successful responses
    when the query engine has non-fatal issues to report (e.g. partial
    results due to unavailable shards).
servers:
  - url: http://localhost:9090
    description: Local development server
security: []
paths:
  /api/v1/write:
    post:
      summary: Remote write
      description: >
        Ingest time series data using the

        [Prometheus Remote Write
        1.0](https://prometheus.io/docs/specs/prw/remote_write_spec/)

        protocol.


        The request body must be a **Snappy-compressed** protobuf `WriteRequest`

        message (as defined by the Prometheus remote write specification). Each

        `WriteRequest` contains one or more `TimeSeries` messages, each with a

        set of labels and one or more timestamp/value sample pairs.


        This endpoint is designed for integration with Prometheus remote-write

        compatible agents and collectors. It is not intended as a
        general-purpose

        high-throughput ingestion path — for bulk data loading, prefer dedicated

        import tooling.


        This endpoint is only available when the server is built with

        the `remote-write` feature.
      operationId: remoteWrite
      parameters:
        - name: Content-Type
          in: header
          required: true
          description: Must be `application/x-protobuf`.
          schema:
            type: string
            enum:
              - application/x-protobuf
        - name: Content-Encoding
          in: header
          required: true
          description: Must be `snappy`.
          schema:
            type: string
            enum:
              - snappy
      requestBody:
        required: true
        content:
          application/x-protobuf:
            schema:
              type: string
              format: binary
              description: |
                Snappy-compressed protobuf `WriteRequest` message. The
                protobuf schema is defined by the Prometheus remote write
                specification.
      responses:
        '204':
          description: Samples ingested successfully (empty body).
        '400':
          description: |
            Invalid request. Possible causes include wrong `Content-Type`,
            Snappy decompression failure, protobuf decode error, or invalid
            sample data (e.g. missing labels). The `errorType` will be
            `bad_data`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error. The `errorType` will be `internal`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: |
            Service unavailable. The server is under backpressure and cannot
            accept writes at this time. Clients should back off and retry.
            The `errorType` will be `unavailable`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ErrorResponse:
      type: object
      description: |
        Prometheus-compatible error response. Returned for all non-2xx
        responses. The `errorType` indicates the category:

        - `bad_data` (HTTP 400/422): The request was malformed or the
          expression could not be executed.
        - `internal` (HTTP 500): An unexpected server-side error occurred.
        - `unavailable` (HTTP 503): The server is temporarily unable to
          handle the request due to backpressure or a query timeout.
      properties:
        status:
          type: string
          example: error
        errorType:
          type: string
          description: |
            Error category. Maps to HTTP status codes:
            - `bad_data` → 400 or 422
            - `internal` → 500
            - `unavailable` → 503
          enum:
            - bad_data
            - internal
            - unavailable
        error:
          type: string
          description: Human-readable error message describing what went wrong.
      required:
        - status
        - errorType
        - error

````