{
 "openapi": "3.1.0",
 "info": {
  "title": "Annalist static API",
  "version": "v1",
  "description": "Company fundamentals from official filings, published as versioned snapshots. Every figure carries the id of its source document. Read-only, no authentication. An MCP server with the same data is at /mcp (Streamable HTTP). Figures come from official filings and are provided as they are, without warranty of accuracy or completeness. They are not investment advice."
 },
 "servers": [
  {
   "url": "https://annalist-fin.pages.dev"
  }
 ],
 "paths": {
  "/api/v1/companies.json": {
   "get": {
    "operationId": "listCompanies",
    "summary": "Company universe with each latest snapshot",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Company universe with each latest snapshot",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/CompanyList"
        }
       }
      }
     },
     "404": {
      "description": "not found"
     }
    }
   }
  },
  "/api/v1/companies/{company}/latest.json": {
   "get": {
    "operationId": "getLatestSnapshot",
    "summary": "Pointer to the latest snapshot",
    "parameters": [
     {
      "name": "company",
      "in": "path",
      "required": true,
      "description": "company id",
      "schema": {
       "type": "string",
       "enum": [
        "mizuho",
        "amazon",
        "walmart",
        "unitedhealth",
        "apple",
        "alphabet",
        "cvs-health",
        "berkshire-hathaway",
        "mckesson",
        "exxon-mobil",
        "cencora"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Pointer to the latest snapshot",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Latest"
        }
       }
      }
     },
     "404": {
      "description": "not found"
     }
    }
   }
  },
  "/api/v1/companies/{company}/snapshots/{snapshot}/info.json": {
   "get": {
    "operationId": "getSnapshotInfo",
    "summary": "Snapshot summary",
    "parameters": [
     {
      "name": "company",
      "in": "path",
      "required": true,
      "description": "company id",
      "schema": {
       "type": "string",
       "enum": [
        "mizuho",
        "amazon",
        "walmart",
        "unitedhealth",
        "apple",
        "alphabet",
        "cvs-health",
        "berkshire-hathaway",
        "mckesson",
        "exxon-mobil",
        "cencora"
       ]
      }
     },
     {
      "name": "snapshot",
      "in": "path",
      "required": true,
      "description": "snapshot id from latest.json, for example FY2026Q2_0a602300",
      "schema": {
       "type": "string",
       "pattern": "^FY[0-9]{4}Q[1-4]_[0-9a-f]{8}$"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Snapshot summary",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SnapshotInfo"
        }
       }
      }
     },
     "404": {
      "description": "not found"
     }
    }
   }
  },
  "/api/v1/companies/{company}/snapshots/{snapshot}/statements/{section}.json": {
   "get": {
    "operationId": "getStatement",
    "summary": "One statement with its item definitions",
    "parameters": [
     {
      "name": "company",
      "in": "path",
      "required": true,
      "description": "company id",
      "schema": {
       "type": "string",
       "enum": [
        "mizuho",
        "amazon",
        "walmart",
        "unitedhealth",
        "apple",
        "alphabet",
        "cvs-health",
        "berkshire-hathaway",
        "mckesson",
        "exxon-mobil",
        "cencora"
       ]
      }
     },
     {
      "name": "snapshot",
      "in": "path",
      "required": true,
      "description": "snapshot id from latest.json, for example FY2026Q2_0a602300",
      "schema": {
       "type": "string",
       "pattern": "^FY[0-9]{4}Q[1-4]_[0-9a-f]{8}$"
      }
     },
     {
      "name": "section",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "enum": [
        "pl_quarterly",
        "pl_annual",
        "balance_sheet",
        "cf_quarterly",
        "cf_annual",
        "capital",
        "npl",
        "shares",
        "annual_highlights"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "One statement with its item definitions",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Statement"
        }
       }
      }
     },
     "404": {
      "description": "not found"
     }
    }
   }
  },
  "/api/v1/companies/{company}/snapshots/{snapshot}/documents.json": {
   "get": {
    "operationId": "getDocuments",
    "summary": "Source documents",
    "parameters": [
     {
      "name": "company",
      "in": "path",
      "required": true,
      "description": "company id",
      "schema": {
       "type": "string",
       "enum": [
        "mizuho",
        "amazon",
        "walmart",
        "unitedhealth",
        "apple",
        "alphabet",
        "cvs-health",
        "berkshire-hathaway",
        "mckesson",
        "exxon-mobil",
        "cencora"
       ]
      }
     },
     {
      "name": "snapshot",
      "in": "path",
      "required": true,
      "description": "snapshot id from latest.json, for example FY2026Q2_0a602300",
      "schema": {
       "type": "string",
       "pattern": "^FY[0-9]{4}Q[1-4]_[0-9a-f]{8}$"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Source documents",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Documents"
        }
       }
      }
     },
     "404": {
      "description": "not found"
     }
    }
   }
  },
  "/api/v1/companies/{company}/snapshots/{snapshot}/ratios/index.json": {
   "get": {
    "operationId": "getRatioCatalogue",
    "summary": "Ratio catalogue and frequencies",
    "parameters": [
     {
      "name": "company",
      "in": "path",
      "required": true,
      "description": "company id",
      "schema": {
       "type": "string",
       "enum": [
        "mizuho",
        "amazon",
        "walmart",
        "unitedhealth",
        "apple",
        "alphabet",
        "cvs-health",
        "berkshire-hathaway",
        "mckesson",
        "exxon-mobil",
        "cencora"
       ]
      }
     },
     {
      "name": "snapshot",
      "in": "path",
      "required": true,
      "description": "snapshot id from latest.json, for example FY2026Q2_0a602300",
      "schema": {
       "type": "string",
       "pattern": "^FY[0-9]{4}Q[1-4]_[0-9a-f]{8}$"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Ratio catalogue and frequencies",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "404": {
      "description": "not found"
     }
    }
   }
  },
  "/api/v1/companies/{company}/snapshots/{snapshot}/ratios/{frequency}.json": {
   "get": {
    "operationId": "getRatios",
    "summary": "Ratio values of one frequency with their inputs",
    "parameters": [
     {
      "name": "company",
      "in": "path",
      "required": true,
      "description": "company id",
      "schema": {
       "type": "string",
       "enum": [
        "mizuho",
        "amazon",
        "walmart",
        "unitedhealth",
        "apple",
        "alphabet",
        "cvs-health",
        "berkshire-hathaway",
        "mckesson",
        "exxon-mobil",
        "cencora"
       ]
      }
     },
     {
      "name": "snapshot",
      "in": "path",
      "required": true,
      "description": "snapshot id from latest.json, for example FY2026Q2_0a602300",
      "schema": {
       "type": "string",
       "pattern": "^FY[0-9]{4}Q[1-4]_[0-9a-f]{8}$"
      }
     },
     {
      "name": "frequency",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "enum": [
        "annual",
        "quarterly",
        "ttm"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Ratio values of one frequency with their inputs",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "404": {
      "description": "not found"
     }
    }
   }
  },
  "/api/v1/companies/{company}/snapshots/{snapshot}/dataset.json": {
   "get": {
    "operationId": "getDataset",
    "summary": "Full dataset (schema annalist.dataset/0.1)",
    "parameters": [
     {
      "name": "company",
      "in": "path",
      "required": true,
      "description": "company id",
      "schema": {
       "type": "string",
       "enum": [
        "mizuho",
        "amazon",
        "walmart",
        "unitedhealth",
        "apple",
        "alphabet",
        "cvs-health",
        "berkshire-hathaway",
        "mckesson",
        "exxon-mobil",
        "cencora"
       ]
      }
     },
     {
      "name": "snapshot",
      "in": "path",
      "required": true,
      "description": "snapshot id from latest.json, for example FY2026Q2_0a602300",
      "schema": {
       "type": "string",
       "pattern": "^FY[0-9]{4}Q[1-4]_[0-9a-f]{8}$"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Full dataset (schema annalist.dataset/0.1)",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "404": {
      "description": "not found"
     }
    }
   }
  },
  "/api/v1/companies/{company}/snapshots/{snapshot}/{table}.csv": {
   "get": {
    "operationId": "getTable",
    "summary": "Long-format CSV table described in tables.json",
    "parameters": [
     {
      "name": "company",
      "in": "path",
      "required": true,
      "description": "company id",
      "schema": {
       "type": "string",
       "enum": [
        "mizuho",
        "amazon",
        "walmart",
        "unitedhealth",
        "apple",
        "alphabet",
        "cvs-health",
        "berkshire-hathaway",
        "mckesson",
        "exxon-mobil",
        "cencora"
       ]
      }
     },
     {
      "name": "snapshot",
      "in": "path",
      "required": true,
      "description": "snapshot id from latest.json, for example FY2026Q2_0a602300",
      "schema": {
       "type": "string",
       "pattern": "^FY[0-9]{4}Q[1-4]_[0-9a-f]{8}$"
      }
     },
     {
      "name": "table",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Long-format CSV table described in tables.json",
      "content": {
       "text/csv": {
        "schema": {
         "type": "string"
        }
       }
      }
     },
     "404": {
      "description": "not found"
     }
    }
   }
  }
 },
 "components": {
  "schemas": {
   "CompanyList": {
    "type": "object",
    "properties": {
     "companies": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Company"
      }
     }
    }
   },
   "Company": {
    "type": "object",
    "required": [
     "id",
     "name"
    ],
    "properties": {
     "id": {
      "type": "string"
     },
     "name": {
      "type": "string"
     },
     "country": {
      "type": "string"
     },
     "cik": {
      "type": [
       "string",
       "null"
      ]
     },
     "tickers": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "groups": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "sources": {
      "type": "string"
     },
     "latest": {
      "type": [
       "object",
       "null"
      ]
     }
    }
   },
   "Latest": {
    "type": "object",
    "required": [
     "company",
     "snapshot",
     "as_of"
    ],
    "properties": {
     "company": {
      "type": "string"
     },
     "snapshot": {
      "type": "string"
     },
     "as_of": {
      "$ref": "#/components/schemas/AsOf"
     },
     "dataset_sha256": {
      "type": "string"
     },
     "info": {
      "type": "string"
     },
     "dataset": {
      "type": "string"
     }
    }
   },
   "AsOf": {
    "type": "object",
    "properties": {
     "period": {
      "type": "string"
     },
     "period_end": {
      "type": "string",
      "format": "date"
     },
     "release_date": {
      "type": [
       "string",
       "null"
      ],
      "format": "date"
     }
    }
   },
   "SnapshotInfo": {
    "type": "object",
    "properties": {
     "snapshot": {
      "type": "string"
     },
     "as_of": {
      "$ref": "#/components/schemas/AsOf"
     },
     "conventions": {
      "type": "object"
     },
     "validation": {
      "type": "object"
     },
     "statements": {
      "type": "array",
      "items": {
       "type": "object"
      }
     },
     "files": {
      "type": "array",
      "items": {
       "type": "object"
      }
     },
     "citation": {
      "type": "object"
     }
    }
   },
   "Statement": {
    "type": "object",
    "required": [
     "company",
     "snapshot",
     "statement",
     "items",
     "rows"
    ],
    "properties": {
     "company": {
      "type": "string"
     },
     "snapshot": {
      "type": "string"
     },
     "statement": {
      "type": "string"
     },
     "frequency": {
      "type": "string"
     },
     "items": {
      "type": "object",
      "additionalProperties": {
       "type": "object",
       "properties": {
        "label": {
         "type": "string"
        },
        "unit": {
         "type": "string"
        }
       }
      }
     },
     "rows": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Row"
      }
     }
    }
   },
   "Row": {
    "type": "object",
    "properties": {
     "period": {
      "type": "string"
     },
     "fiscal_year": {
      "type": "integer"
     },
     "quarter": {
      "type": "integer"
     },
     "start": {
      "type": "string",
      "format": "date"
     },
     "end": {
      "type": "string",
      "format": "date"
     },
     "date": {
      "type": "string",
      "format": "date"
     },
     "method": {
      "type": "string"
     },
     "values": {
      "type": "object",
      "additionalProperties": {
       "type": [
        "number",
        "null"
       ]
      }
     },
     "sources": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "value_sources": {
      "type": "object"
     },
     "value_methods": {
      "type": "object"
     },
     "concepts": {
      "type": "object"
     }
    }
   },
   "Documents": {
    "type": "object",
    "properties": {
     "documents": {
      "type": "object",
      "additionalProperties": {
       "type": "object",
       "properties": {
        "url": {
         "type": [
          "string",
          "null"
         ]
        },
        "sha256": {
         "type": "string"
        },
        "release_date": {
         "type": [
          "string",
          "null"
         ]
        },
        "filed": {
         "type": [
          "string",
          "null"
         ]
        }
       }
      }
     }
    }
   }
  }
 }
}