{
  "openapi": "3.1.0",
  "info": {
    "title": "tipsheet data",
    "version": "1",
    "summary": "Read-only JSON and CSV files of every series published on tipsheet.markets.",
    "description": "Static files on a CDN: no key, no rate limit beyond fair use, cross-origin requests allowed. Read the manifest to find a dataset's current file; files are content-hashed and never change once published. Guide: https://tipsheet.markets/data/",
    "contact": {
      "url": "https://tipsheet.markets/about/"
    }
  },
  "servers": [
    {
      "url": "https://tipsheet.markets"
    }
  ],
  "paths": {
    "/data/v1/manifest.json": {
      "get": {
        "operationId": "getManifest",
        "summary": "Every dataset by stable name, with the path of its current file",
        "responses": {
          "200": {
            "description": "The manifest",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Manifest"
                }
              }
            }
          }
        }
      }
    },
    "/data/v1/status.json": {
      "get": {
        "operationId": "getStatus",
        "summary": "When each source was last updated, and whether the latest refresh succeeded",
        "responses": {
          "200": {
            "description": "Refresh status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/data/readings.json": {
      "get": {
        "operationId": "getReadings",
        "summary": "Every reading on the site: today's value, its date, what it means in a sentence, its percentile in its own history, its source, and the addresses of its page, history and CSV",
        "responses": {
          "200": {
            "description": "The readings",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "count": {
                      "type": "integer"
                    },
                    "readings": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/data/v1/{file}": {
      "get": {
        "operationId": "getDataset",
        "summary": "One dataset file, at the path the manifest gives (for example activity/exchanges/monthly.35025b80b188.json)",
        "parameters": [
          {
            "name": "file",
            "in": "path",
            "required": true,
            "description": "A value from the manifest's files map. It contains slashes; send it unescaped.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The dataset",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/Series"
                    },
                    {
                      "$ref": "#/components/schemas/Statistic"
                    },
                    {
                      "$ref": "#/components/schemas/Table"
                    },
                    {
                      "type": "object",
                      "description": "A composite dataset; its meta says what each key holds"
                    }
                  ]
                }
              }
            }
          },
          "404": {
            "description": "No such file (an old hash: read the manifest again)"
          }
        }
      }
    },
    "/i/{slug}/data.csv": {
      "get": {
        "operationId": "getReadingCsv",
        "summary": "The full history of one reading as CSV (slugs are listed at /indicators/ and in /llms.txt)",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "nifty-50-pe"
          }
        ],
        "responses": {
          "200": {
            "description": "date,value rows",
            "content": {
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/{page}/index.md": {
      "get": {
        "operationId": "getPageMarkdown",
        "summary": "Any page as Markdown: its text, tables, sources and a citation (front matter: title, url, description, updated, cite)",
        "parameters": [
          {
            "name": "page",
            "in": "path",
            "required": true,
            "description": "The page's path without slashes at either end, for example valuation or i/nifty-50-pe",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The page as Markdown",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Manifest": {
        "type": "object",
        "required": [
          "files"
        ],
        "properties": {
          "schema": {
            "type": [
              "integer",
              "string"
            ]
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "files": {
            "type": "object",
            "description": "Stable dataset name to the current file path under /data/v1/",
            "additionalProperties": {
              "type": "string"
            }
          }
        }
      },
      "Meta": {
        "type": "object",
        "description": "Source, method and notes on units",
        "properties": {
          "source": {
            "type": "string"
          },
          "method": {
            "type": "string"
          },
          "notes": {
            "type": [
              "array",
              "string"
            ]
          },
          "credit": {
            "type": "string"
          }
        },
        "additionalProperties": true
      },
      "Series": {
        "type": "object",
        "required": [
          "dates",
          "series"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "resolution": {
            "type": "string",
            "examples": [
              "daily",
              "weekly",
              "monthly",
              "quarterly"
            ]
          },
          "generated_at": {
            "type": "string",
            "format": "date-time"
          },
          "meta": {
            "$ref": "#/components/schemas/Meta"
          },
          "dates": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "date"
            }
          },
          "series": {
            "type": "object",
            "description": "Column name to values, one per date; null where there is no value",
            "additionalProperties": {
              "type": "array",
              "items": {
                "type": [
                  "number",
                  "null"
                ]
              }
            }
          }
        }
      },
      "Statistic": {
        "type": "object",
        "required": [
          "latest",
          "as_of",
          "history"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "meta": {
            "$ref": "#/components/schemas/Meta"
          },
          "as_of": {
            "type": "string",
            "format": "date"
          },
          "latest": {
            "type": "number"
          },
          "value_ago": {
            "type": "object",
            "properties": {
              "1w": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "1m": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "1y": {
                "type": [
                  "number",
                  "null"
                ]
              }
            }
          },
          "history": {
            "type": "object",
            "properties": {
              "start": {
                "type": "string",
                "format": "date"
              },
              "observations": {
                "type": "integer"
              },
              "min": {
                "type": "number"
              },
              "min_date": {
                "type": "string",
                "format": "date"
              },
              "max": {
                "type": "number"
              },
              "max_date": {
                "type": "string",
                "format": "date"
              },
              "median": {
                "type": "number"
              },
              "percentile_full_history": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "percentile_last_5y": {
                "type": [
                  "number",
                  "null"
                ]
              }
            }
          }
        }
      },
      "Table": {
        "type": "object",
        "required": [
          "rows"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "meta": {
            "$ref": "#/components/schemas/Meta"
          },
          "columns": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "rows": {
            "type": "array",
            "items": {
              "type": "array"
            }
          }
        }
      }
    }
  }
}
