{
  "openapi": "3.1.0",
  "info": {
    "title": "BFF ingestor",
    "version": "3.2.18",
    "description": "The platform's one way in for data. A feeder signs in by client credentials and pushes under its own namespaces. A push is stored whole or not at all for each series it carries, with its receipt, and is safe sent again: an acknowledged push is stored.\nErrors: every operation may answer `unauthenticated`, `insufficient_scope`, `access_denied`, `feeder_not_registered`, `feeder_suspended`, `feeder_retired`, `rate_limited`, `invalid_request`, `store_unavailable` and `internal`; each names the codes it adds."
  },
  "servers": [
    {
      "url": "http://127.0.0.1:8614",
      "description": "Development"
    }
  ],
  "security": [
    {
      "oauth2": [
        "ingest:push"
      ]
    }
  ],
  "paths": {
    "/v1/pushes": {
      "post": {
        "operationId": "createPush",
        "summary": "Push series",
        "description": "Up to 100 series, column by column. Each series is stored whole or not at all, and the receipt says which of each: so that the series of one push need not share one transaction when the store is spread over several nodes. A value that is `null` says why in `status`. The same `batch_id` sent again answers its receipt, `is_repeated`. A series refused for its data is refused in the receipt, with its problem, as docs/errors.md lists them for the data: among them `known_in_future`, `duplicate_versions` and `absence_unstated`. Each series refused is announced, as `bff.data.rejected`, and logged as a read `rejected` for the valid times it held. A series the push cannot name (`invalid_series`, `invalid_series_info`: no object, or no name) refuses the push whole, as the request's own errors do; then nothing is stored, and no receipt is kept.\nA copy of a feeder that holds its lease names itself (`Lease-Holder`), and its push is stored only while it holds it: once another copy took the lease, or it ended, the push is refused (`lease_lost`, 409) and nothing of it is stored, not even a receipt. The last quiet push of a catch-up sums it up (`catch_up`), and the ingestor announces the summary once, with that push, as `bff.data.filled` (the events' schema 2.1.0), for each series of it that was written.\nErrors: `invalid_batch_id`, `invalid_series_name`, `duplicate_series`, `invalid_series`, `invalid_series_info`, `payload_too_large`, `series_not_allowed`, `timeline_not_allowed`, `lease_lost`, `push_timeout`.",
        "parameters": [
          {
            "$ref": "#/components/parameters/idempotency_key"
          },
          {
            "$ref": "#/components/parameters/lease_holder"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Push"
              },
              "example": {
                "batch_id": "entsoe-20261119-1205-a44",
                "series": [
                  {
                    "info": {
                      "name": "entsoe.de_lu_price",
                      "kind": "number",
                      "unit": "EUR/MWh",
                      "description": "Day-ahead price, DE-LU (DE-AT-LU before October 2018), in the steps the source publishes. ENTSO-E Transparency Platform.",
                      "market": "DE-LU",
                      "product": "day-ahead"
                    },
                    "valid_at": [
                      "2026-11-20T00:00:00+01:00",
                      "2026-11-20T00:15:00+01:00"
                    ],
                    "known_at": [
                      "2026-11-19T13:00:00+01:00",
                      "2026-11-19T13:00:00+01:00"
                    ],
                    "value": [
                      96.12,
                      91.4
                    ],
                    "known_by": [
                      "due",
                      "due"
                    ]
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The receipt",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Receipt"
                },
                "example": {
                  "batch_id": "entsoe-20261119-1205-a44",
                  "timeline": "live",
                  "received_at": "2026-11-19T12:05:31Z",
                  "is_repeated": false,
                  "outcome": "written",
                  "series": {
                    "entsoe.de_lu_price": {
                      "outcome": "written",
                      "sent": 2,
                      "new": 2,
                      "problem": null
                    }
                  }
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/pushes/{batch_id}": {
      "get": {
        "operationId": "getPush",
        "summary": "One of your pushes, by its receipt",
        "description": "Kept 90 days, as receipts are today (`PF_INGEST_RECEIPT_DAYS`).\nErrors: `unknown_receipt`.",
        "security": [
          {
            "oauth2": [
              "ingest:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "batch_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_.:-]{1,100}$"
            },
            "example": "entsoe-20261119-1205-a44",
            "description": "The push's `batch_id`."
          }
        ],
        "responses": {
          "200": {
            "description": "The receipt",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Receipt"
                },
                "example": {
                  "batch_id": "entsoe-20261119-1205-a44",
                  "timeline": "live",
                  "received_at": "2026-11-19T12:05:31Z",
                  "is_repeated": false,
                  "outcome": "partial",
                  "series": {
                    "entsoe.de_lu_price": {
                      "outcome": "written",
                      "sent": 96,
                      "new": 96,
                      "problem": null
                    },
                    "entsoe.de_lu_load_forecast": {
                      "outcome": "rejected",
                      "sent": 96,
                      "new": 0,
                      "problem": {
                        "type": "/problems/known-in-future",
                        "title": "Known in future",
                        "status": 422,
                        "detail": "entsoe.de_lu_load_forecast is known at 2026-11-19T14:00:00Z, after the clock.",
                        "instance": "/v1/pushes/entsoe-20261119-1205-a44",
                        "code": "known_in_future",
                        "class": "DataContractError",
                        "details": {
                          "series": "entsoe.de_lu_load_forecast",
                          "known_at": "2026-11-19T14:00:00Z"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/series": {
      "get": {
        "operationId": "listOwnSeries",
        "summary": "Your series",
        "description": "Each with its description and its newest card, in the order of their names.\nErrors: `invalid_cursor`.",
        "security": [
          {
            "oauth2": [
              "ingest:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/series_limit"
          },
          {
            "$ref": "#/components/parameters/cursor"
          }
        ],
        "responses": {
          "200": {
            "description": "A page of series",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OwnSeriesList"
                },
                "example": {
                  "series": [
                    {
                      "name": "entsoe.de_lu_load_forecast",
                      "kind": "number",
                      "unit": "MW",
                      "errors": {},
                      "description": "Day-ahead forecast of the total load, DE-LU. ENTSO-E Transparency Platform.",
                      "market": "DE-LU",
                      "product": "day-ahead",
                      "card": {
                        "set_at": "2026-11-02T09:14:07Z",
                        "grid": "PT15M",
                        "zone": "Europe/Berlin",
                        "publishes": {
                          "day_before": "10:00"
                        },
                        "revises": true,
                        "origin": "fetched",
                        "lineage": "RAW-07"
                      }
                    }
                  ],
                  "next_cursor": "eyJrIjpbImVudHNvZS5kZV9sdV9sb2FkX2ZvcmVjYXN0Il0sImwiOiJpbmdlc3Quc2VyaWVzIiwicSI6IjJkYTIyOWUwYmQ0NTA2ZWIiLCJ2IjoxfQ"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/PageRefused"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/values": {
      "get": {
        "operationId": "readOwnValues",
        "summary": "Read your own series",
        "description": "What the store holds of them, every column, so that a feeder can tell what it has pushed from what is new. Cut by `recorded_after`, the answer says how far it is whole (`recorded_until`): the next read's cursor. It reaches at most to now less the longest a push may take, so that no push still in hand is passed.\nErrors: `series_not_allowed`, `invalid_series_name`, `invalid_time`, `invalid_cursor`.",
        "security": [
          {
            "oauth2": [
              "ingest:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/own_timeline"
          },
          {
            "name": "series",
            "in": "query",
            "required": true,
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "minItems": 1,
              "maxItems": 20
            },
            "style": "form",
            "explode": false,
            "description": "Your series, by their names, separated by commas; one at least, and at most 20 (`invalid_request` otherwise). A name under another's namespace is refused (`series_not_allowed`), whether it exists or not."
          },
          {
            "name": "start",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "The first valid time, included; from the first if absent."
          },
          {
            "name": "end",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "The last valid time, excluded; to the last if absent."
          },
          {
            "name": "recorded_after",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Only rows recorded after this, and no later than the answer's `recorded_until`: pass the `recorded_until` of the read before."
          },
          {
            "$ref": "#/components/parameters/ingest_rows_limit"
          },
          {
            "$ref": "#/components/parameters/cursor"
          }
        ],
        "responses": {
          "200": {
            "description": "A page of values",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OwnValuesPage"
                },
                "example": {
                  "series": {
                    "entsoe.de_lu_price": {
                      "info": {
                        "name": "entsoe.de_lu_price",
                        "kind": "number",
                        "unit": "EUR/MWh",
                        "errors": {},
                        "description": "Day-ahead price, DE-LU (DE-AT-LU before October 2018), in the steps the source publishes. ENTSO-E Transparency Platform.",
                        "market": "DE-LU",
                        "product": "day-ahead",
                        "card": null
                      },
                      "valid_at": [
                        "2026-11-19T23:00:00Z",
                        "2026-11-19T23:15:00Z"
                      ],
                      "known_at": [
                        "2026-11-19T12:00:00Z",
                        "2026-11-19T12:00:00Z"
                      ],
                      "recorded_at": [
                        "2026-11-19T12:05:31Z",
                        "2026-11-19T12:05:31Z"
                      ],
                      "value": [
                        96.12,
                        91.4
                      ],
                      "status": [
                        null,
                        null
                      ],
                      "known_by": [
                        "due",
                        "due"
                      ]
                    }
                  },
                  "recorded_until": "2026-11-19T14:04:00Z",
                  "next_cursor": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/PageRefused"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/progress": {
      "get": {
        "operationId": "readProgress",
        "summary": "How far each of your series has come",
        "description": "The latest known and recorded time of each, and how many values: kept as pushes are stored, not counted at each asking. A feeder resumes from it, and from its own last reads, as its heartbeats told them. In the order of the series' names.\nErrors: `invalid_cursor`.",
        "security": [
          {
            "oauth2": [
              "ingest:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/own_timeline"
          },
          {
            "$ref": "#/components/parameters/series_limit"
          },
          {
            "$ref": "#/components/parameters/cursor"
          }
        ],
        "responses": {
          "200": {
            "description": "A page of series",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Progress"
                },
                "example": {
                  "series": {
                    "entsoe.de_lu_load_forecast": {
                      "latest_known_at": "2026-11-19T09:00:00Z",
                      "latest_recorded_at": "2026-11-19T09:01:12Z",
                      "rows": 386112
                    },
                    "entsoe.de_lu_price": {
                      "latest_known_at": "2026-11-19T12:00:00Z",
                      "latest_recorded_at": "2026-11-19T12:05:31Z",
                      "rows": 112404
                    }
                  },
                  "reads": {
                    "entsoe.de_lu_price": {
                      "read_at": "2026-11-19T12:05:30Z",
                      "start": "2026-11-16T12:00:00Z",
                      "end": "2026-11-21T12:00:00Z"
                    }
                  },
                  "next_cursor": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/PageRefused"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/reads": {
      "get": {
        "operationId": "listReads",
        "summary": "The log of reads of a source",
        "description": "Every read a feeder made of its source, and every push of its refused for its data: what was asked, when, and how it ended. Newest first. A feeder reads its own; a person or the publisher, those of the series under its namespaces. `filter` takes `series`, `outcome`, `code`, `read_at`, `recorded_at`, `window_start`, `window_end`, `rows`, `batch_id` and `timeline`, as in `outcome = failed AND read_at >= \"2026-11-19T00:00:00Z\"`. It is what tells an outage (`failed`) from a source's silence (`empty`), and what a reader's `source_down` and `rejected` are worked out from.\nErrors: `invalid_filter`, `invalid_cursor`.",
        "security": [
          {
            "oauth2": [
              "ingest:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/filter"
          },
          {
            "$ref": "#/components/parameters/reads_limit"
          },
          {
            "$ref": "#/components/parameters/cursor"
          }
        ],
        "responses": {
          "200": {
            "description": "A page of reads",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReadList"
                },
                "example": {
                  "reads": [
                    {
                      "series": "entsoe.de_lu_load_forecast",
                      "read_at": "2026-11-19T12:05:33Z",
                      "recorded_at": "2026-11-19T12:05:35Z",
                      "window_start": "2026-11-16T12:00:00Z",
                      "window_end": "2026-11-21T12:00:00Z",
                      "outcome": "failed",
                      "code": "source_failed",
                      "rows": null,
                      "batch_id": null
                    },
                    {
                      "series": "entsoe.de_lu_price",
                      "read_at": "2026-11-19T12:05:30Z",
                      "recorded_at": "2026-11-19T12:05:35Z",
                      "window_start": "2026-11-16T12:00:00Z",
                      "window_end": "2026-11-21T12:00:00Z",
                      "outcome": "values",
                      "code": null,
                      "rows": 96,
                      "batch_id": "entsoe-20261119-1205-a44"
                    }
                  ],
                  "next_cursor": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/PageRefused"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      },
      "post": {
        "operationId": "recordReads",
        "summary": "Record reads of a source",
        "description": "A feeder says what it read, a series each, once the pushes of what it read are done: values, new or not; none; a failure; or a refusal; with the valid times it asked for. Every read is recorded this way, a read that found values too: its window, and the values it found that the store held already, are the feeder's to know. A push refused for its data is recorded by the ingestor, as `rejected`, and is not sent. A failed read writes no value: readers see its due times as `source_down`, and the values stored before stay as they are. A read is its own key: the same read (its series, `read_at`, window and outcome) sent again, by any `Idempotency-Key` or none, is recorded once. At most 1,000 reads a request; more are refused (`payload_too_large`). Only a feeder records reads; another caller is refused (`access_denied`).\nErrors: `access_denied`, `series_not_allowed`, `invalid_series_name`, `payload_too_large`.",
        "parameters": [
          {
            "$ref": "#/components/parameters/idempotency_key"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "reads"
                ],
                "description": "Reads, up to 1,000 a request. A read that does not fit is refused (`invalid_request`), with `field` naming its member, as `reads[1].code`, and none of the request is recorded.",
                "properties": {
                  "reads": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/ReadReport"
                    },
                    "minItems": 1,
                    "maxItems": 1000,
                    "description": "The reads, in any order; one twice in a request is one read."
                  }
                }
              },
              "example": {
                "reads": [
                  {
                    "series": "entsoe.de_lu_price",
                    "read_at": "2026-11-19T13:05:30+01:00",
                    "window_start": "2026-11-16T13:00:00+01:00",
                    "window_end": "2026-11-21T13:00:00+01:00",
                    "outcome": "values",
                    "rows": 96,
                    "batch_id": "entsoe-20261119-1205-a44"
                  },
                  {
                    "series": "entsoe.de_lu_load_forecast",
                    "read_at": "2026-11-19T13:05:33+01:00",
                    "window_start": "2026-11-16T13:00:00+01:00",
                    "window_end": "2026-11-21T13:00:00+01:00",
                    "outcome": "failed",
                    "code": "source_failed"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Recorded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "recorded"
                  ],
                  "description": "How many reads were recorded.",
                  "properties": {
                    "recorded": {
                      "type": "integer",
                      "format": "int64",
                      "minimum": 0,
                      "description": "The reads new to the log; one recorded before is not counted again."
                    }
                  }
                },
                "example": {
                  "recorded": 2
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/leases/{feeder}": {
      "put": {
        "operationId": "takeLease",
        "summary": "Take, or keep, a feeder's lease",
        "description": "One copy of a feeder runs at a time: the one that holds its lease (docs/audit-horizontal-scaling.md, a feeder). A copy asks for it before a run, under a name of its own (`holder`), and keeps it by asking again before `ttl` has passed, in a run and between runs; a lease not asked for again ends by itself, so a copy that stops without a word holds the others up for one lease at most. A `ttl` of `PT0S` gives it back: a copy that stops well hands over at once. Two copies that ask at once get one winner. A copy that is refused (`is_yours` false) reads nothing from its source, and asks again later, when the lease ends at the latest. While it holds the lease, a copy names itself in its pushes and heartbeats (`Lease-Holder`), so that once it has lost the lease nothing it sends is stored.\nThe platform's feeder asks for two minutes (`PT2M`) every 30 seconds, a quarter of it, so that three askings may fail in a row before the lease is lost. It counts the lease from the moment it asked, and stops reading a tenth of it before its end, so that it has stopped before the ingestor would let another copy take over.\nErrors: `lease_not_allowed`.",
        "parameters": [
          {
            "name": "feeder",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "feeder.entsoe",
            "description": "The feeder whose lease it is: the caller's own. Another's, or a caller that is no feeder, is refused (`lease_not_allowed`)."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "holder",
                  "ttl"
                ],
                "description": "The copy that asks, and how long it asks for.",
                "properties": {
                  "holder": {
                    "type": "string",
                    "pattern": "^[A-Za-z0-9_.:-]{1,100}$",
                    "description": "A name of the copy's own, made when it starts: its host, its process and a few random characters, say. Another form is refused (`invalid_request`)."
                  },
                  "ttl": {
                    "type": "string",
                    "pattern": "^P(?!$)(\\d+D)?(T(?=\\d)(\\d+H)?(\\d+M)?(\\d+S)?)?$",
                    "description": "How long the lease lasts unless it is asked for again, an ISO 8601 duration of whole days, hours, minutes and seconds, from `PT1S` to `PT10M`, the longest the others wait for a copy that stopped. Another is refused (`invalid_request`). `PT0S` gives the lease back, if the copy holds it."
                  }
                }
              },
              "example": {
                "holder": "feeder-entsoe-1-3f2a9c1e",
                "ttl": "PT2M"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The lease, whoever holds it",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "holder",
                    "is_yours",
                    "expires_at"
                  ],
                  "description": "The lease as it stands.",
                  "properties": {
                    "holder": {
                      "type": "string",
                      "description": "The copy that holds the lease, or held it last."
                    },
                    "is_yours": {
                      "type": "boolean",
                      "description": "Whether the copy that asked holds it now. A copy that does not reads nothing; one that gave it back holds it no more."
                    },
                    "expires_at": {
                      "type": "string",
                      "format": "date-time",
                      "description": "When the lease ends, unless its holder asks for it again: the moment another copy may take it. Given back, the moment it was."
                    }
                  }
                },
                "example": {
                  "holder": "feeder-entsoe-1-3f2a9c1e",
                  "is_yours": true,
                  "expires_at": "2026-11-19T12:02:00Z"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/heartbeats": {
      "post": {
        "operationId": "createHeartbeat",
        "summary": "A feeder's heartbeat",
        "description": "After every run, well or not, as today: whether it went well, or the problem that ended it, and each series' last read. A run of failing heartbeats is announced once (`bff.feeder.failed`). A copy of a feeder that names itself (`Lease-Holder`) is heard only while it holds the feeder's lease (`lease_lost`, 409, otherwise): a copy that lost it does not speak for the runs of the one that took it.\nErrors: `access_denied`, `lease_lost`.",
        "parameters": [
          {
            "$ref": "#/components/parameters/lease_holder"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Heartbeat"
              },
              "example": {
                "is_ok": true,
                "reads": {
                  "entsoe.de_lu_price": {
                    "read_at": "2026-11-19T12:05:30Z",
                    "start": "2026-11-19T23:00:00Z",
                    "end": "2026-11-20T23:00:00Z"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "Taken"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/me": {
      "get": {
        "operationId": "getMe",
        "summary": "Who you are to the ingestor",
        "description": "Your identity, your namespaces and whether you may push, as before. Any valid token may ask, with no scope; a suspended or retired feeder is answered too, so that it may learn why.\nErrors: `unauthenticated` alone.",
        "security": [
          {
            "oauth2": []
          }
        ],
        "responses": {
          "200": {
            "description": "The caller",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Me"
                },
                "example": {
                  "identity": "feeder.entsoe",
                  "feeder_id": "feeder.entsoe",
                  "namespaces": [
                    "entsoe"
                  ],
                  "status": "active",
                  "scopes": [
                    "ingest:push",
                    "ingest:read"
                  ],
                  "timelines": [
                    "live"
                  ]
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/status": {
      "get": {
        "operationId": "getStatus",
        "summary": "The ingestor's state",
        "description": "Whether it takes pushes (`accepting`), takes them while its announcements wait (`degraded`) or cannot reach its database (`unavailable`); the database's clock, which a feeder compares its own with; and the limits a push and a read are held to. Any valid token may ask, with no scope. As before 3.2.18, at `/status`.\nErrors: `unauthenticated` alone.",
        "security": [
          {
            "oauth2": []
          }
        ],
        "responses": {
          "200": {
            "description": "The state",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IngestorStatus"
                },
                "example": {
                  "state": "accepting",
                  "version": "3.2.18",
                  "server_time": "2026-11-19T12:05:31.204118Z",
                  "limits": {
                    "max_bytes": 33554432,
                    "max_series": 100,
                    "max_rows": 100000,
                    "max_read_rows": 500000,
                    "clock_skew_seconds": 60.0,
                    "requests_per_minute": 1200,
                    "transaction_seconds": 30.0
                  },
                  "announcements": {
                    "pending": 0,
                    "oldest_pending_seconds": 0.0
                  }
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/health": {
      "get": {
        "operationId": "getHealth",
        "summary": "Whether the process runs (liveness)",
        "description": "Whether the process runs (liveness): always 200 while it does. Whether it can serve is `/ready`.",
        "responses": {
          "200": {
            "description": "OK"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        },
        "security": []
      }
    },
    "/ready": {
      "get": {
        "operationId": "getReadiness",
        "summary": "Whether it can serve: the database answers within 2 seconds (readiness)",
        "description": "Whether it can serve (readiness): 200 while the database answers within 2 seconds, and `store_unavailable`, 503, while it does not. Docker reads it, and what waits for the service waits for this.",
        "security": [],
        "responses": {
          "200": {
            "description": "Ready",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status"
                  ],
                  "properties": {
                    "status": {
                      "const": "ok"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "The database does not answer (`store_unavailable`)",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "oauth2": {
        "type": "oauth2",
        "description": "Tokens from the platform's Keycloak; a feeder uses client credentials.",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "http://localhost:8180/realms/bff/protocol/openid-connect/token",
            "scopes": {
              "ingest:push": "Push series",
              "ingest:read": "Read one's own series, receipts and reads"
            }
          }
        }
      }
    },
    "parameters": {
      "own_timeline": {
        "name": "timeline",
        "in": "query",
        "schema": {
          "type": "string",
          "default": "live"
        },
        "description": "The timeline read, alone: `live` unless given. One's own series hold rows on the timelines one may push on: a feeder on `live`, a person on `live` and simulations of their own, the publisher on its forecasts'. Not the read API's `timeline`, which shows a simulation over `live`."
      },
      "idempotency_key": {
        "name": "Idempotency-Key",
        "in": "header",
        "schema": {
          "type": "string"
        },
        "description": "A key of the caller's own: a write sent again with the same key is done once, and answered as the first time it was. Where the body names a key of its own, as a push's `batch_id`, that key serves."
      },
      "lease_holder": {
        "name": "Lease-Holder",
        "in": "header",
        "schema": {
          "type": "string",
          "pattern": "^[A-Za-z0-9_.:-]{1,100}$"
        },
        "example": "feeder-entsoe-1-3f2a9c1e",
        "description": "The copy of the feeder that sends it, as it named itself when it took the lease (`PUT /v1/leases/{feeder}`); another form is refused (`invalid_request`). Named, the request is taken only while that copy holds the lease: once another copy holds it, or it ended, the request is refused (`lease_lost`) and nothing of it is stored. The lease is checked last, just before the request is stored, and no other copy may take it in between. Not named, the request is held to no lease: a feeder of one's own that takes none, or one written before leases."
      },
      "filter": {
        "name": "filter",
        "in": "query",
        "schema": {
          "type": "string"
        },
        "description": "Which items: comparisons of a field and a value (`=`, `!=`, `<`, `<=`, `>`, `>=`, and `:` for a text that holds the value), joined by `AND`, `OR` and `NOT` (or `-`), with parentheses; `OR` binds tighter than `AND` (RFC 012, R4: AIP-160's subset). A value is a word, a number, true or false, or a text in double quotes; a time is RFC 3339, with its offset. The fields a list filters by are named in its description. At most 2,000 characters and 50 comparisons. A filter that does not read, names another field, or compares a field by an operator or a value not of its kind is refused (`invalid_filter`, with its `position`)."
      },
      "series_limit": {
        "name": "limit",
        "in": "query",
        "schema": {
          "type": "integer",
          "format": "int32",
          "minimum": 1,
          "default": 500,
          "x-bff-maximum": 1000
        },
        "description": "The most series in a page: 500 unless given, and at most 1,000. One above the maximum is lowered to it, not refused; one that is no whole number from 1 is refused (`invalid_request`)."
      },
      "reads_limit": {
        "name": "limit",
        "in": "query",
        "schema": {
          "type": "integer",
          "format": "int32",
          "minimum": 1,
          "default": 500,
          "x-bff-maximum": 1000
        },
        "description": "The most reads in a page: 500 unless given, and at most 1,000. One above the maximum is lowered to it, not refused; one that is no whole number from 1 is refused (`invalid_request`)."
      },
      "ingest_rows_limit": {
        "name": "limit",
        "in": "query",
        "schema": {
          "type": "integer",
          "format": "int32",
          "minimum": 1,
          "default": 100000,
          "x-bff-maximum": 500000
        },
        "description": "The most rows in a page, across its series: 100,000 unless given, the most rows one push holds, so that a feeder reads back in one page what it pushes in one; and at most 500,000, the most one read holds today (`PF_INGEST_MAX_READ_ROWS`), so that no page is larger than a read is now. One above the maximum is lowered to it, not refused; one that is no whole number from 1 is refused (`invalid_request`)."
      },
      "cursor": {
        "name": "cursor",
        "in": "query",
        "schema": {
          "type": "string"
        },
        "description": "The `next_cursor` of the page before, as it was; without it, the first page. It is opaque, and whole in itself: it carries where the page before ended, and any copy of the service answers it. Send it with the same parameters as the page before. One that this list did not give for this request is refused (`invalid_cursor`)."
      }
    },
    "responses": {
      "PageRefused": {
        "description": "A page this list cannot give: a `cursor` that it did not give for this request (`invalid_cursor`: another list's, the same list's asked with other parameters, one of another release, or none at all); a `limit` that is no whole number from 1 (`invalid_request`); or another parameter of the request that is wrong, as the operation's errors name it.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "Problem": {
        "description": "A refusal or a failure, as a problem",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            },
            "example": {
              "type": "/problems/invalid-batch-id",
              "title": "Invalid batch id",
              "status": 400,
              "detail": "A batch_id is 1 to 100 characters of A-Z a-z 0-9 _ . : -, not 'entsoe 2026-11-19'.",
              "instance": "/v1/pushes",
              "code": "invalid_batch_id",
              "class": "InvalidRequest",
              "details": {
                "field": "batch_id"
              }
            }
          }
        }
      }
    },
    "schemas": {
      "Problem": {
        "type": "object",
        "required": [
          "type",
          "title",
          "status",
          "detail",
          "code",
          "class",
          "details"
        ],
        "description": "An error, as RFC 9457 writes it (`application/problem+json`), with the platform's three members: `code` for programs, `class` for who is at fault, `details` for debugging. `detail` is for people, and may be reworded. As the built contracts have it.",
        "properties": {
          "type": {
            "type": "string",
            "format": "uri-reference",
            "description": "`/problems/` and the code with dashes for its underscores: the page that explains the code.",
            "examples": [
              "/problems/unknown-series"
            ]
          },
          "title": {
            "type": "string",
            "description": "The code in words. The same for every occurrence of the code.",
            "examples": [
              "Unknown series"
            ]
          },
          "status": {
            "type": "integer",
            "format": "int32",
            "description": "The HTTP status the problem is answered with.",
            "examples": [
              400
            ]
          },
          "detail": {
            "type": "string",
            "description": "What went wrong this time, for a person.",
            "examples": [
              "No series [\"wind\"] to read."
            ]
          },
          "instance": {
            "type": "string",
            "format": "uri-reference",
            "description": "The occurrence: the path of the request that was refused, without its query.",
            "examples": [
              "/v1/values"
            ]
          },
          "code": {
            "type": "string",
            "description": "The stable code a program tests (docs/errors.md). An open list: a client treats a code it does not know by its `status`.",
            "examples": [
              "unknown_series"
            ]
          },
          "class": {
            "type": "string",
            "x-extensible-enum": [
              "InvalidRequest",
              "AccessDenied",
              "DataContractError",
              "SourceError",
              "InternalError",
              "RemoteError",
              "ServiceError",
              "ModelError"
            ],
            "description": "Who is at fault, which decides the status. An open list: a client treats a class it does not know by its `status`.",
            "examples": [
              "InvalidRequest"
            ]
          },
          "details": {
            "type": "object",
            "additionalProperties": true,
            "x-bff-open": "Facts for a debugger differ by code; docs/errors.md names each code's.",
            "description": "Facts for a debugger, by name. They differ by code."
          }
        }
      },
      "NextCursor": {
        "type": [
          "string",
          "null"
        ],
        "description": "The cursor of the page after this one: send it as `cursor`, with the same parameters. Null on the last page."
      },
      "Status": {
        "type": [
          "string",
          "null"
        ],
        "x-extensible-enum": [
          "preliminary",
          "provisional",
          "final",
          "no_data",
          "cancelled",
          "withdrawn",
          "partial",
          "unstated",
          "not_covered",
          "not_due",
          "late",
          "source_down",
          "rejected"
        ],
        "description": "Where a value is in its life, or why there is none (docs/plan-trading-requirements.md, 2.1 to 2.4). With a value: null where the source says nothing of it, or `preliminary`, `provisional` or `final`. Without one, as the source or a definition states it: `no_data`, `cancelled`, `withdrawn` or `partial`; `unstated` for a row stored before 3.2.14. Without one, worked out at the read, as of its cut: `not_covered`, `not_due`, `late`, `source_down` or `rejected`. An open list: a client treats a status it does not know beside a value as none, and beside no value as an absence.",
        "examples": [
          "final",
          "cancelled",
          "late"
        ]
      },
      "Value": {
        "description": "One value, of its series' kind: an IEEE double for `number`, a text for `text`, a rectangular array of numbers for `array`; null where there is none, the row's status saying why.",
        "oneOf": [
          {
            "type": "number",
            "format": "double"
          },
          {
            "type": "string"
          },
          {
            "$ref": "#/components/schemas/Numbers"
          },
          {
            "type": "null"
          }
        ]
      },
      "Numbers": {
        "type": "array",
        "description": "A rectangular array of finite numbers, of one dimension or more.",
        "items": {
          "oneOf": [
            {
              "type": "number",
              "format": "double"
            },
            {
              "$ref": "#/components/schemas/Numbers"
            }
          ]
        }
      },
      "Card": {
        "type": "object",
        "additionalProperties": false,
        "required": [],
        "description": "What a series' feeder says of it, beyond its values: one version of its card, in force from `valid_from` (docs/plan-trading-requirements.md, 2.3). Every field is optional: a card says what its feeder knows. As the built contract's `Card`, with `set_at`.",
        "properties": {
          "valid_from": {
            "type": "string",
            "format": "date-time",
            "description": "From which valid time this version holds; absent, from the beginning of time. The version in force for a valid time is the one with the latest `valid_from` at or before it."
          },
          "set_at": {
            "type": "string",
            "format": "date-time",
            "description": "When this version was stored; a version corrected later has a later one."
          },
          "grid": {
            "type": "string",
            "pattern": "^P(?!$)(\\d+Y)?(\\d+M)?(\\d+W)?(\\d+D)?(T(?=\\d)(\\d+H)?(\\d+M)?(\\d+(\\.\\d+)?S)?)?$",
            "description": "The step between the series' values, an ISO 8601 duration of local days and clock time, such as `PT15M`, `PT1H` or `P1D`, in the calendar of `zone`: `P1D` keeps its local hour when the clocks change, and a day of `PT15M` has 92, 96 or 100 quarter-hours. Absent for a series with no regular step."
          },
          "zone": {
            "type": "string",
            "description": "The time zone its days and clock times are in, an IANA name such as Europe/Berlin."
          },
          "publishes": {
            "type": "object",
            "minProperties": 1,
            "maxProperties": 1,
            "additionalProperties": false,
            "required": [],
            "description": "When a value becomes known, by one of three rules. A clock time needs `zone`.",
            "properties": {
              "day_before": {
                "type": "string",
                "pattern": "^[0-2][0-9]:[0-5][0-9]$",
                "description": "The values of a day are known on the day before, at this clock time."
              },
              "same_day": {
                "type": "string",
                "pattern": "^[0-2][0-9]:[0-5][0-9]$",
                "description": "The values of a day are known on that day, at this clock time (IDCC(c) at 05:00, IDA3 at 10:00)."
              },
              "after": {
                "type": "string",
                "pattern": "^P(?!$)(\\d+Y)?(\\d+M)?(\\d+W)?(\\d+D)?(T(?=\\d)(\\d+H)?(\\d+M)?(\\d+(\\.\\d+)?S)?)?$",
                "description": "A value is known this long after the moment it is for, a duration."
              }
            }
          },
          "revises": {
            "type": "boolean",
            "description": "Whether the source ever corrects a value it has published."
          },
          "grace": {
            "type": "string",
            "pattern": "^P(?!$)(\\d+Y)?(\\d+M)?(\\d+W)?(\\d+D)?(T(?=\\d)(\\d+H)?(\\d+M)?(\\d+(\\.\\d+)?S)?)?$",
            "description": "How long after its due time a value is late, a duration; two hours where absent."
          },
          "covers": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "string",
              "pattern": "^[0-2][0-9]:[0-5][0-9]-[0-2][0-9]:[0-5][0-9]$"
            },
            "description": "The parts of each day the source gives by design, local times of `zone`, such as `12:00-24:00` for IDA3. A time outside them is not covered, never late. All of the day where absent."
          },
          "calendar": {
            "type": "string",
            "pattern": "^[A-Za-z][A-Za-z0-9_.-]{0,63}$",
            "description": "The publication calendar the source keeps, by name, such as TARGET: its days without a publication are not late."
          },
          "origin": {
            "type": "string",
            "x-extensible-enum": [
              "fetched",
              "computed",
              "forecast",
              "imported"
            ],
            "description": "Where the values come from: fetched from a source, computed by a definition, forecast by a model, or imported by a person. Not the series' `kind`, which says what a value is."
          },
          "lineage": {
            "type": "string",
            "pattern": "^[A-Z]{2,4}-[0-9]{2,3}$",
            "description": "The requirement the series answers, such as RAW-01 or CMP-08."
          }
        }
      },
      "Push": {
        "type": "object",
        "required": [
          "batch_id",
          "series"
        ],
        "additionalProperties": false,
        "description": "Series pushed together, each stored whole or not at all. A member not named here is refused (`invalid_request`), so that one in the words before 3.2.18, `quiet`, is told, and not read as loud.",
        "properties": {
          "batch_id": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_.:-]{1,100}$",
            "description": "The push's key, the same when the batch is sent again; another form is refused (`invalid_batch_id`)."
          },
          "timeline": {
            "type": "string",
            "default": "live",
            "description": "Where it is stored: a feeder pushes on `live` alone; a person on `live` or a simulation of their own."
          },
          "is_quiet": {
            "type": "boolean",
            "default": false,
            "description": "History: stored, and not announced row by row."
          },
          "series": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/PushedSeries"
            },
            "description": "The series, each once (`duplicate_series`)."
          },
          "catch_up": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CatchUp"
            },
            "description": "With the last quiet push of a catch-up: its summary, a series each. The ingestor announces it once, with this push, as `bff.data.filled` (the events' schema 2.1.0): a reader learns that a range was filled without hearing of each row; a series of it that was refused is not announced. Only in a quiet push (`is_quiet`), each naming a series of the push, once (`invalid_request` otherwise). A push sent again is answered by its receipt, and announces nothing more."
          }
        }
      },
      "CatchUp": {
        "type": "object",
        "required": [
          "series",
          "first_valid_at",
          "last_valid_at",
          "latest_known_at",
          "rows"
        ],
        "description": "One series' catch-up, as its feeder sums it up: the rows of a series the store held, known before the feeder's look-back, pushed quiet after an outage or a pause. A series' first load is not summed up. As the built contract's `CatchUp`.",
        "properties": {
          "series": {
            "type": "string",
            "description": "A series of the push, by its name as the push names it."
          },
          "first_valid_at": {
            "type": "string",
            "format": "date-time",
            "description": "The first valid time the catch-up filled."
          },
          "last_valid_at": {
            "type": "string",
            "format": "date-time",
            "description": "The last valid time it filled, itself included; not before `first_valid_at`."
          },
          "latest_known_at": {
            "type": "string",
            "format": "date-time",
            "description": "The latest known time of its rows; not ahead of the ingestor's clock by more than a minute."
          },
          "rows": {
            "type": "integer",
            "format": "int64",
            "minimum": 1,
            "description": "The rows it pushed, in this push and the quiet ones before it."
          }
        },
        "examples": [
          {
            "series": "entsoe.de_lu_load_forecast",
            "first_valid_at": "2026-11-12T10:15:00Z",
            "last_valid_at": "2026-11-15T23:45:00Z",
            "latest_known_at": "2026-11-16T01:00:00Z",
            "rows": 326
          }
        ]
      },
      "PushedSeries": {
        "type": "object",
        "required": [
          "info",
          "valid_at",
          "known_at",
          "value"
        ],
        "description": "A series, column by column, as the built contract's `Series`: every list of one length, row i one value and its times. Each declared error estimate adds a list of its name; a column the contract does not name is refused (`unknown_column`).",
        "properties": {
          "info": {
            "$ref": "#/components/schemas/SeriesInfo",
            "description": "What the series is."
          },
          "valid_at": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "date-time"
            },
            "description": "The moment each value describes, with its offset."
          },
          "known_at": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "date-time"
            },
            "description": "When each value became known, as the source says; never later than the ingestor's clock plus the allowed skew (`known_in_future`)."
          },
          "value": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Value"
            },
            "description": "The values, of the series' kind; null where missing, and then the row's status says why (`absence_unstated` otherwise)."
          },
          "valid_until": {
            "type": "array",
            "items": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time"
            },
            "description": "The end of each period, when it is not `valid_at` plus the card's step; after `valid_at`."
          },
          "status": {
            "type": "array",
            "items": {
              "type": [
                "string",
                "null"
              ],
              "enum": [
                "preliminary",
                "provisional",
                "final",
                "no_data",
                "cancelled",
                "withdrawn",
                "partial",
                null
              ]
            },
            "description": "With a value: null, `preliminary`, `provisional` or `final`. Without one, required: `no_data`, `cancelled`, `withdrawn` or `partial`. The platform's own absences are worked out when read, never pushed."
          },
          "flags": {
            "type": "array",
            "items": {
              "type": [
                "array",
                "null"
              ],
              "items": {
                "type": "string",
                "enum": [
                  "held",
                  "carried",
                  "derived",
                  "interpolated",
                  "estimated",
                  "outlier"
                ]
              }
            },
            "description": "What may be said of each value's quality, apart from its status."
          },
          "flag_reason": {
            "type": "array",
            "items": {
              "type": [
                "string",
                "null"
              ]
            },
            "description": "Why the flags are set."
          },
          "published_at": {
            "type": "array",
            "items": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time"
            },
            "description": "When the source says it published each value, or a quote's as-of time; at or before `known_at`."
          },
          "known_by": {
            "type": "array",
            "items": {
              "type": [
                "string",
                "null"
              ],
              "enum": [
                "stated",
                "due",
                "first_seen",
                "first_seen_late",
                "revision",
                "computed",
                null
              ]
            },
            "description": "How each `known_at` was set."
          },
          "run_id": {
            "type": "array",
            "items": {
              "type": [
                "string",
                "null"
              ]
            },
            "description": "The model run or computation that made each value."
          }
        },
        "additionalProperties": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/Value"
          }
        }
      },
      "SeriesInfo": {
        "type": "object",
        "required": [
          "name"
        ],
        "description": "What a pushed series is, as the built contract has it.",
        "properties": {
          "name": {
            "type": "string",
            "description": "A local name, or one under the caller's namespace, such as entsoe.de_lu_price."
          },
          "kind": {
            "type": "string",
            "enum": [
              "number",
              "text",
              "array"
            ],
            "default": "number",
            "description": "What a value is."
          },
          "unit": {
            "type": "string",
            "default": "",
            "description": "The unit of its values; empty for none."
          },
          "errors": {
            "type": "object",
            "description": "Its error estimates, by name and kind; each adds a column of its name.",
            "additionalProperties": {
              "type": "string",
              "enum": [
                "number",
                "text",
                "array"
              ]
            }
          },
          "description": {
            "type": "string",
            "default": "",
            "description": "What it is. A description other than the stored one is refused (`series_redefined`)."
          },
          "market": {
            "type": "string",
            "default": "",
            "maxLength": 64,
            "description": "The market it belongs to, such as DE-LU: one line. One stored with a market may not change it."
          },
          "product": {
            "type": "string",
            "default": "",
            "maxLength": 64,
            "description": "The product, such as day-ahead; one line, as the market."
          },
          "card": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/CardVersion"
              },
              {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/CardVersion"
                }
              },
              {
                "type": "null"
              }
            ],
            "description": "Its card: one version, from the beginning of time, or a list of versions by valid time; an empty list states none. A push without one leaves the card stored as it is."
          }
        }
      },
      "CardVersion": {
        "type": "object",
        "additionalProperties": false,
        "required": [],
        "description": "One version of a series' card, as a feeder states it, as the built contract has it: what it says from its valid time on.",
        "properties": {
          "valid_from": {
            "type": "string",
            "format": "date-time",
            "description": "From which valid time this version holds; absent, from the beginning of time."
          },
          "grid": {
            "type": "string",
            "pattern": "^P(?!$)(\\d+Y)?(\\d+M)?(\\d+W)?(\\d+D)?(T(?=\\d)(\\d+H)?(\\d+M)?(\\d+(\\.\\d+)?S)?)?$",
            "description": "The step between the series' values, an ISO 8601 duration of local days and clock time."
          },
          "step": {
            "type": "string",
            "deprecated": true,
            "pattern": "^P(?!$)(\\d+Y)?(\\d+M)?(\\d+W)?(\\d+D)?(T(?=\\d)(\\d+H)?(\\d+M)?(\\d+(\\.\\d+)?S)?)?$",
            "description": "The grid's name until 3.2.14, read as the grid; a card may not state both."
          },
          "zone": {
            "type": "string",
            "description": "The time zone its days and clock times are in, such as Europe/Berlin."
          },
          "publishes": {
            "type": "object",
            "minProperties": 1,
            "maxProperties": 1,
            "additionalProperties": false,
            "required": [],
            "description": "When a value becomes known, by one of three rules. A clock time needs `zone`.",
            "properties": {
              "day_before": {
                "type": "string",
                "pattern": "^[0-2][0-9]:[0-5][0-9]$",
                "description": "The values of a day are known on the day before, at this clock time."
              },
              "same_day": {
                "type": "string",
                "pattern": "^[0-2][0-9]:[0-5][0-9]$",
                "description": "The values of a day are known on that day, at this clock time."
              },
              "after": {
                "type": "string",
                "pattern": "^P(?!$)(\\d+Y)?(\\d+M)?(\\d+W)?(\\d+D)?(T(?=\\d)(\\d+H)?(\\d+M)?(\\d+(\\.\\d+)?S)?)?$",
                "description": "A value is known this long after the moment it is for, a duration."
              }
            }
          },
          "revises": {
            "type": "boolean",
            "description": "Whether the source ever corrects a value it has published."
          },
          "grace": {
            "type": "string",
            "pattern": "^P(?!$)(\\d+Y)?(\\d+M)?(\\d+W)?(\\d+D)?(T(?=\\d)(\\d+H)?(\\d+M)?(\\d+(\\.\\d+)?S)?)?$",
            "description": "How long after its due time a value is late, a duration; two hours where absent."
          },
          "covers": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "string",
              "pattern": "^[0-2][0-9]:[0-5][0-9]-[0-2][0-9]:[0-5][0-9]$"
            },
            "description": "The parts of each day the source gives by design, local times of `zone`."
          },
          "calendar": {
            "type": "string",
            "pattern": "^[A-Za-z][A-Za-z0-9_.-]{0,63}$",
            "description": "The publication calendar the source keeps, by name, such as TARGET."
          },
          "origin": {
            "type": "string",
            "enum": [
              "fetched",
              "computed",
              "forecast",
              "imported"
            ],
            "description": "Where the values come from. Not the series' `kind`, which says what a value is."
          },
          "lineage": {
            "type": "string",
            "pattern": "^[A-Z]{2,4}-[0-9]{2,3}$",
            "description": "The requirement the series answers, such as RAW-01."
          }
        }
      },
      "Receipt": {
        "type": "object",
        "required": [
          "batch_id",
          "timeline",
          "received_at",
          "is_repeated",
          "outcome",
          "series"
        ],
        "description": "What became of a push, a series at a time.",
        "properties": {
          "batch_id": {
            "type": "string",
            "description": "The push's key."
          },
          "timeline": {
            "type": "string",
            "description": "The timeline it was pushed on."
          },
          "received_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the ingestor received it; every row it stored is recorded then."
          },
          "is_repeated": {
            "type": "boolean",
            "description": "Whether this batch was received before; then this is the first receipt."
          },
          "outcome": {
            "type": "string",
            "x-extensible-enum": [
              "written",
              "partial",
              "rejected"
            ],
            "description": "Whether every series was written, some were refused (`partial`), or none was written (`rejected`)."
          },
          "series": {
            "type": "object",
            "description": "Each series' own outcome, by its name. A receipt kept from before 3.2.18 names a series it refused only where its problem named it.",
            "additionalProperties": {
              "type": "object",
              "required": [
                "outcome",
                "sent",
                "new",
                "problem"
              ],
              "properties": {
                "outcome": {
                  "type": "string",
                  "x-extensible-enum": [
                    "written",
                    "rejected"
                  ],
                  "description": "Whether the series was written whole, or not at all."
                },
                "sent": {
                  "type": [
                    "integer",
                    "null"
                  ],
                  "format": "int64",
                  "description": "The rows pushed of it; null in a receipt kept from before 3.2.18, which did not count them."
                },
                "new": {
                  "type": "integer",
                  "format": "int64",
                  "description": "The rows new to the store; a row stored before is not new."
                },
                "problem": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/Problem"
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "Why it was refused, as a problem whose `instance` is the receipt; null where it was written."
                }
              }
            }
          }
        }
      },
      "OwnSeries": {
        "type": "object",
        "required": [
          "name",
          "kind",
          "unit",
          "errors",
          "description",
          "market",
          "product",
          "card"
        ],
        "description": "One of the caller's series, as it is stored, with its newest card.",
        "properties": {
          "name": {
            "type": "string",
            "description": "Its qualified name."
          },
          "kind": {
            "type": "string",
            "x-extensible-enum": [
              "number",
              "text",
              "array"
            ],
            "description": "What a value is."
          },
          "unit": {
            "type": "string",
            "description": "The unit of its values; empty for none."
          },
          "errors": {
            "type": "object",
            "description": "Its error estimates, by name and kind.",
            "additionalProperties": {
              "type": "string",
              "x-extensible-enum": [
                "number",
                "text",
                "array"
              ]
            }
          },
          "description": {
            "type": "string",
            "description": "What it is, as first stored."
          },
          "market": {
            "type": "string",
            "description": "Its market; empty if it names none."
          },
          "product": {
            "type": "string",
            "description": "Its product; empty if it names none."
          },
          "card": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Card"
              },
              {
                "type": "null"
              }
            ],
            "description": "Its newest card: the version from the latest valid time, as it was set last; null where it has none."
          }
        }
      },
      "OwnSeriesList": {
        "type": "object",
        "required": [
          "series",
          "next_cursor"
        ],
        "description": "A page of the caller's series.",
        "properties": {
          "series": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OwnSeries"
            },
            "description": "The series, in the order of their names."
          },
          "next_cursor": {
            "$ref": "#/components/schemas/NextCursor"
          }
        }
      },
      "StoredValues": {
        "type": "object",
        "required": [
          "info",
          "valid_at",
          "known_at",
          "recorded_at",
          "value",
          "status"
        ],
        "description": "One series as the store holds it, in the wire format of a push with one more list, `recorded_at`: every column, a row a version.",
        "properties": {
          "info": {
            "$ref": "#/components/schemas/OwnSeries",
            "description": "What the series is."
          },
          "valid_at": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "date-time"
            },
            "description": "The moment each value describes."
          },
          "known_at": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "date-time"
            },
            "description": "When each value became known."
          },
          "recorded_at": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "date-time"
            },
            "description": "When the platform stored each, the same for every row of a receipt."
          },
          "value": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Value"
            },
            "description": "The values; null where a row states an absence."
          },
          "valid_until": {
            "type": "array",
            "items": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time"
            },
            "description": "The end of each period, where it is not `valid_at` plus the card's step."
          },
          "status": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Status"
            },
            "description": "Each row's status, as pushed; `unstated` for a null row stored before 3.2.14."
          },
          "flags": {
            "type": "array",
            "items": {
              "type": [
                "array",
                "null"
              ],
              "items": {
                "type": "string",
                "x-extensible-enum": [
                  "held",
                  "carried",
                  "derived",
                  "interpolated",
                  "estimated",
                  "outlier"
                ]
              }
            },
            "description": "Each row's flags; null where none was stated, which no flag contradicts."
          },
          "flag_reason": {
            "type": "array",
            "items": {
              "type": [
                "string",
                "null"
              ]
            },
            "description": "Why each row's flags are set."
          },
          "published_at": {
            "type": "array",
            "items": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time"
            },
            "description": "When the source says it published each."
          },
          "known_by": {
            "type": "array",
            "items": {
              "type": [
                "string",
                "null"
              ],
              "x-extensible-enum": [
                "stated",
                "due",
                "first_seen",
                "first_seen_late",
                "revision",
                "computed"
              ]
            },
            "description": "How each `known_at` was set."
          },
          "run_id": {
            "type": "array",
            "items": {
              "type": [
                "string",
                "null"
              ]
            },
            "description": "The model run or computation that made each."
          }
        },
        "additionalProperties": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/Value"
          }
        }
      },
      "OwnValuesPage": {
        "type": "object",
        "required": [
          "series",
          "recorded_until",
          "next_cursor"
        ],
        "description": "A page of the caller's values, by series.",
        "properties": {
          "series": {
            "type": "object",
            "description": "The series read, by name.",
            "additionalProperties": {
              "$ref": "#/components/schemas/StoredValues"
            }
          },
          "recorded_until": {
            "type": "string",
            "format": "date-time",
            "description": "How far the store is whole by `recorded_at`: no row recorded at or before it is still to come. The next read's `recorded_after`."
          },
          "next_cursor": {
            "$ref": "#/components/schemas/NextCursor"
          }
        }
      },
      "Progress": {
        "type": "object",
        "required": [
          "series",
          "reads",
          "next_cursor"
        ],
        "description": "A page of how far each of the caller's series has come.",
        "properties": {
          "series": {
            "type": "object",
            "description": "Each series that holds rows, by name.",
            "additionalProperties": {
              "type": "object",
              "required": [
                "latest_known_at",
                "latest_recorded_at",
                "rows"
              ],
              "properties": {
                "latest_known_at": {
                  "type": "string",
                  "format": "date-time",
                  "description": "The latest known time among its rows."
                },
                "latest_recorded_at": {
                  "type": "string",
                  "format": "date-time",
                  "description": "The latest recorded time among its rows."
                },
                "rows": {
                  "type": "integer",
                  "format": "int64",
                  "description": "How many rows it holds."
                }
              }
            }
          },
          "reads": {
            "type": "object",
            "description": "The caller's own last read of each series, as its heartbeats told them; none for a caller that is no feeder. A page holds those of the names it spans, from where its cursor ends to its last series, and the last page those of every name after: the pages together hold each read once, also of a series that has no row yet.",
            "additionalProperties": {
              "$ref": "#/components/schemas/LastRead"
            }
          },
          "next_cursor": {
            "$ref": "#/components/schemas/NextCursor"
          }
        }
      },
      "IngestorStatus": {
        "type": "object",
        "required": [
          "state",
          "version",
          "server_time",
          "limits",
          "announcements"
        ],
        "description": "The ingestor's state, as `GET /v1/status` answers it.",
        "properties": {
          "state": {
            "type": "string",
            "x-extensible-enum": [
              "accepting",
              "degraded",
              "unavailable"
            ],
            "description": "Whether it takes pushes; takes them while its announcements have waited more than a minute; or cannot reach its database."
          },
          "version": {
            "type": "string",
            "description": "The ingestor's version."
          },
          "server_time": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "The database's clock; null while it cannot be reached."
          },
          "limits": {
            "type": "object",
            "required": [
              "max_bytes",
              "max_series",
              "max_rows",
              "max_read_rows",
              "clock_skew_seconds",
              "requests_per_minute",
              "transaction_seconds"
            ],
            "description": "The limits a push and a read are held to (docs/ingestion.md, \"Limits\").",
            "properties": {
              "max_bytes": {
                "type": "integer",
                "format": "int64",
                "description": "The most bytes a request's body holds."
              },
              "max_series": {
                "type": "integer",
                "format": "int32",
                "description": "The most series a push holds."
              },
              "max_rows": {
                "type": "integer",
                "format": "int32",
                "description": "The most rows a push holds."
              },
              "max_read_rows": {
                "type": "integer",
                "format": "int64",
                "description": "The most rows a page of values holds."
              },
              "clock_skew_seconds": {
                "type": "number",
                "format": "double",
                "description": "How far a known time may run ahead of the database's clock."
              },
              "requests_per_minute": {
                "type": "integer",
                "format": "int32",
                "description": "The most requests a caller makes in a minute."
              },
              "transaction_seconds": {
                "type": "number",
                "format": "double",
                "description": "The longest a push's transaction may last."
              }
            }
          },
          "announcements": {
            "oneOf": [
              {
                "type": "object",
                "required": [
                  "pending",
                  "oldest_pending_seconds"
                ],
                "description": "The announcements not yet sent to the bus.",
                "properties": {
                  "pending": {
                    "type": "integer",
                    "format": "int64",
                    "description": "How many wait."
                  },
                  "oldest_pending_seconds": {
                    "type": "number",
                    "format": "double",
                    "description": "How long the oldest has waited."
                  }
                }
              },
              {
                "type": "null"
              }
            ],
            "description": "The announcements that wait; null while the database cannot be reached."
          }
        }
      },
      "Read": {
        "type": "object",
        "required": [
          "series",
          "read_at",
          "recorded_at",
          "window_start",
          "window_end",
          "outcome",
          "code",
          "rows",
          "batch_id"
        ],
        "description": "One read of a source for one series, or one push refused for its data: a row of `obs.reads` (docs/plan-trading-requirements.md, 2.3), as the built contract's `Read` answers it. Its timeline is not answered; the log's `filter` takes it.",
        "properties": {
          "series": {
            "type": "string",
            "description": "The series read, by its qualified name."
          },
          "read_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the source was read: when its answer came, or the read failed. For a push refused, when it was refused."
          },
          "recorded_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the log took it."
          },
          "window_start": {
            "type": "string",
            "format": "date-time",
            "description": "The first valid time the read asked for, or the push held."
          },
          "window_end": {
            "type": "string",
            "format": "date-time",
            "description": "The valid time the read asked up to, itself excluded. A file is read whole, and a push refused holds what it holds: their window ends just after the last valid time they hold of the series."
          },
          "outcome": {
            "type": "string",
            "x-extensible-enum": [
              "values",
              "empty",
              "failed",
              "refused",
              "rejected"
            ],
            "description": "How it ended: the source answered with values or stated absences, new or not; it answered with none; it did not answer, or answered what could not be read; it would not answer for this series; or the ingestor refused the push of what was read, for its data, the ingestor's own. A reader's `source_down` is worked out from a failure and a refusal, its `rejected` from a push refused."
          },
          "code": {
            "type": [
              "string",
              "null"
            ],
            "description": "Why the read failed, was refused or was rejected: the error's code, such as source_failed. Null otherwise."
          },
          "rows": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32",
            "minimum": 0,
            "description": "With values: the rows pushed of what was read, which may be none. Of a push refused: the rows refused. Null otherwise."
          },
          "batch_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "With values: the last batch pushed of what was read, the store's `receipt`. Of a push refused: the batch refused. Null otherwise."
          }
        }
      },
      "ReadList": {
        "type": "object",
        "required": [
          "reads",
          "next_cursor"
        ],
        "description": "A page of the log of reads.",
        "properties": {
          "reads": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Read"
            },
            "description": "The reads, newest first."
          },
          "next_cursor": {
            "$ref": "#/components/schemas/NextCursor"
          }
        }
      },
      "ReadReport": {
        "type": "object",
        "required": [
          "series",
          "read_at",
          "window_start",
          "window_end",
          "outcome"
        ],
        "additionalProperties": false,
        "description": "A read, as a feeder records it, with values or without: the members of a `Read`, as the built contract takes them. A push refused is the ingestor's to record, not the feeder's. A member not named here is refused (`invalid_request`).",
        "properties": {
          "series": {
            "type": "string",
            "description": "The series read, by its qualified name, under the feeder's namespaces (`series_not_allowed` otherwise)."
          },
          "read_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the source was read: when its answer came, or the read failed. Not more than a minute ahead of the ingestor's clock."
          },
          "recorded_at": {
            "type": "string",
            "format": "date-time",
            "description": "Taken and not read, so that a read answered may be sent back as it is; the log sets its own."
          },
          "window_start": {
            "type": "string",
            "format": "date-time",
            "description": "The first valid time the read asked for."
          },
          "window_end": {
            "type": "string",
            "format": "date-time",
            "description": "The valid time the read asked up to, itself excluded; not before `window_start`. A file is read whole: its window ends just after the last valid time it holds of the series."
          },
          "outcome": {
            "type": "string",
            "enum": [
              "values",
              "empty",
              "failed",
              "refused"
            ],
            "description": "The source answered with values or stated absences, new or not; it answered with none; it did not answer, or answered what could not be read; or it would not answer for this series. A push refused for its data is the ingestor's own, never sent."
          },
          "code": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^[a-z_]{1,64}$",
            "description": "Why the read failed or was refused: the error's code, such as source_failed. Required with a failure and a refusal; with values or none, absent or null."
          },
          "rows": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32",
            "minimum": 0,
            "description": "With values: the rows pushed of what was read, which may be none. With another outcome, absent or null."
          },
          "batch_id": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^[A-Za-z0-9_.:-]{1,100}$",
            "description": "With values: the last batch pushed of what was read. With another outcome, absent or null."
          }
        }
      },
      "Heartbeat": {
        "type": "object",
        "required": [
          "is_ok"
        ],
        "description": "A feeder's run, as it ended: as today, with its `ok` named `is_ok` by RFC 012's rule 2, as `is_quiet` and `is_repeated` are named.",
        "properties": {
          "is_ok": {
            "type": "boolean",
            "description": "Whether the run went well."
          },
          "problem": {
            "$ref": "#/components/schemas/Problem",
            "description": "Where it did not, what ended the run, as a problem. Its `code`, `class`, `detail` and `details` are kept; a class the platform does not know is kept as `InternalError`."
          },
          "reads": {
            "type": "object",
            "maxProperties": 1000,
            "description": "Each series' last read of the source whose rows were all stored, by the series' qualified name. `GET /v1/progress` gives the feeder's own back when it starts again.",
            "additionalProperties": {
              "$ref": "#/components/schemas/LastRead"
            }
          },
          "skipped": {
            "type": "object",
            "maxProperties": 1000,
            "description": "What the run's reads left out, by the series' qualified name and then by a reason in snake case, as built in 3.2.16: what the source gave that is no value of the series, such as a JAO product that is no hour. The ingestor keeps the last heartbeat's, and the feeder's record shows it. Leaving something out is no failure, and `is_ok` says nothing of it.",
            "additionalProperties": {
              "type": "object",
              "minProperties": 1,
              "maxProperties": 32,
              "propertyNames": {
                "type": "string",
                "pattern": "^[a-z][a-z0-9_]{0,63}$"
              },
              "description": "A series' reasons, each with its count.",
              "additionalProperties": {
                "$ref": "#/components/schemas/Skip"
              }
            }
          }
        }
      },
      "Skip": {
        "type": "object",
        "required": [
          "count",
          "first_at",
          "last_at"
        ],
        "additionalProperties": false,
        "description": "How many a read left out for one reason, and the first and last valid times concerned.",
        "properties": {
          "count": {
            "type": "integer",
            "format": "int64",
            "minimum": 1,
            "description": "How many were left out."
          },
          "first_at": {
            "type": "string",
            "format": "date-time",
            "description": "The first valid time concerned."
          },
          "last_at": {
            "type": "string",
            "format": "date-time",
            "description": "The last valid time concerned, not before the first."
          }
        }
      },
      "LastRead": {
        "type": "object",
        "required": [
          "read_at",
          "start",
          "end"
        ],
        "description": "A series' last read of the source whose rows were all stored: where the next read starts, and what was missing at it. As the built contract's `LastRead`, which is not the log's `Read`.",
        "properties": {
          "read_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the source was read."
          },
          "start": {
            "type": "string",
            "format": "date-time",
            "description": "The first time the read was of."
          },
          "end": {
            "type": "string",
            "format": "date-time",
            "description": "The time the read ended before."
          }
        }
      },
      "Me": {
        "type": "object",
        "required": [
          "identity",
          "feeder_id",
          "namespaces",
          "status",
          "scopes",
          "timelines"
        ],
        "description": "The caller, as the ingestor sees it.",
        "properties": {
          "identity": {
            "type": "string",
            "description": "The identity its token names."
          },
          "feeder_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Its feeder's id; null for a caller who is no feeder."
          },
          "namespaces": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The namespaces it may push under."
          },
          "status": {
            "type": "string",
            "x-extensible-enum": [
              "active",
              "suspended",
              "retired"
            ],
            "description": "Its feeder's status in the registry; `active` for a caller who is no feeder."
          },
          "scopes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The scopes its token holds."
          },
          "timelines": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The timelines it may push on."
          }
        }
      }
    }
  }
}
