{"openapi":"3.1.0","info":{"title":"Tessera Analytics API","description":"Customer-facing REST API for Tessera Analytics' gold Hyperliquid datasets. Browse the catalog, list partitions, and mint presigned download URLs. Download this document at `/v1/openapi.json` to generate a client.","license":{"name":"MIT","identifier":"MIT"},"version":"1.0.0"},"servers":[{"url":"/","description":"Same-origin (production fronts the API via CloudFront)"}],"paths":{"/v1/catalog":{"get":{"tags":["catalog"],"summary":"List the data catalog.","description":"Public (no API key). Returns every customer-facing dataset with an intuitive\nsummary and its tier — the high-level catalog. Drill into\n`/v1/catalog/{asset}` for the per-column data dictionary. This is\ndocumentation only; it advertises Pro datasets to everyone. Actual data\naccess stays gated on `/v1/datasets/*`.","operationId":"catalog_index","responses":{"200":{"description":"The data catalog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogResponse"}}}},"503":{"description":"Catalog dictionary unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/v1/catalog/{asset}":{"get":{"tags":["catalog"],"summary":"Get a dataset's data dictionary.","description":"Public (no API key). Returns the full dictionary for one dataset: dataset\nprose plus every column's type, nullability, technical description, and\nplain-English meaning, grouped for presentation. Unknown or non-customer-\nfacing assets return 404.","operationId":"catalog_dataset","parameters":[{"name":"asset","in":"path","description":"Dataset name, e.g. gold_ohlcv_1m","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The dataset's data dictionary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetDoc"}}}},"404":{"description":"Unknown dataset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"503":{"description":"Catalog dictionary unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/v1/datasets":{"get":{"tags":["datasets"],"summary":"List datasets.","description":"Returns every gold dataset visible to the caller's policy, with a partition\ncount, the distinct coins, and the month range available.","operationId":"list_datasets","responses":{"200":{"description":"Datasets visible to the caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetsResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"503":{"description":"Catalog manifest unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"security":[{"api_key":[]}]}},"/v1/datasets/{asset}":{"get":{"tags":["datasets"],"summary":"List partitions for a dataset.","description":"Returns the partitions (coin × month) of `asset` visible to the caller,\noptionally narrowed by the `coin` and `month` query filters.","operationId":"list_partitions","parameters":[{"name":"asset","in":"path","description":"Dataset name, e.g. gold_ohlcv_1m","required":true,"schema":{"type":"string"}},{"name":"coin","in":"query","description":"Only return partitions for this coin, e.g. `BTC`.","required":false,"schema":{"type":"string"}},{"name":"month","in":"query","description":"Only return partitions for this month (`YYYY-MM`).","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Partitions for the dataset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartitionsResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Dataset not permitted by the caller's policy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Unknown or hidden dataset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"503":{"description":"Catalog manifest unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"security":[{"api_key":[]}]}},"/v1/datasets/{asset}/{coin}/{month}/download":{"get":{"tags":["datasets"],"summary":"Download a partition.","description":"Mints a short-lived presigned URL for the parquet object of a single\n`(asset, coin, month)` partition. By default this **302-redirects** to that\nURL, so `curl -L`/`wget` download the file in one step. Send\n`Accept: application/json` to get the URL (and its expiry) as a JSON body\ninstead — useful for programmatic callers.","operationId":"download_url","parameters":[{"name":"asset","in":"path","description":"Dataset name, e.g. gold_ohlcv_1m","required":true,"schema":{"type":"string"}},{"name":"coin","in":"path","description":"Coin symbol, e.g. BTC","required":true,"schema":{"type":"string"}},{"name":"month","in":"path","description":"Partition month, YYYY-MM","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Presigned download URL as JSON. Returned only when the request sends `Accept: application/json`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DownloadResponse"}}}},"302":{"description":"Redirect (Location header) to the presigned parquet URL. The default — follow it with `curl -L`."},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Dataset not permitted by the caller's policy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Partition not found or hidden by policy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"503":{"description":"Catalog manifest unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"security":[{"api_key":[]}]}}},"components":{"schemas":{"CatalogEntry":{"type":"object","description":"A dataset's catalog card (the high-level list view). Drill into\n`/v1/catalog/{name}` for the full column dictionary.","required":["name","title","category","cadence","summary","tier","column_count"],"properties":{"cadence":{"type":"string","description":"Granularity + partitioning."},"category":{"type":"string","description":"Presentation category, e.g. `raw-tiles` / `forecast-layer`."},"column_count":{"type":"integer","description":"Number of documented columns.","minimum":0},"name":{"type":"string","description":"Dataset name / asset key, e.g. `gold_ohlcv_1m`.","example":"gold_ohlcv_1m"},"summary":{"type":"string","description":"One-line intuitive summary."},"tier":{"type":"string","description":"Display tier badge (`free` / `pro`), derived from the access policy."},"title":{"type":"string","description":"Human-friendly title."}}},"CatalogResponse":{"type":"object","required":["generated_at","datasets"],"properties":{"datasets":{"type":"array","items":{"$ref":"#/components/schemas/CatalogEntry"}},"generated_at":{"type":"string","description":"RFC3339 timestamp the dictionary was generated."}}},"ColumnDoc":{"type":"object","description":"One column's dictionary entry: the engineering facts (type/nullability/how\nit's computed) plus the plain-English `meaning` (what it is and why you'd care).","required":["name","type","nullable","meaning"],"properties":{"description":{"type":["string","null"],"description":"Technical description — *how* the column is computed. May be absent."},"meaning":{"type":"string","description":"Plain-English meaning — *what* the column is and why it's useful."},"name":{"type":"string","description":"Column name."},"nullable":{"type":"boolean","description":"Whether the column may be null."},"type":{"type":"string","description":"Arrow type string, e.g. `float64`, `timestamp[us]`."}}},"ColumnGroup":{"type":"object","description":"A labelled section of columns within a dataset.","required":["columns"],"properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/ColumnDoc"}},"label":{"type":["string","null"],"description":"Section heading, or `null` for a single unlabelled group."},"meaning":{"type":["string","null"],"description":"Group-level plain-English meaning, used for large column families (e.g.\nthe residualized factor backbone) where a per-column line adds no value."}}},"DatasetDoc":{"type":"object","description":"One dataset's catalog entry + full data dictionary.","required":["name","title","category","cadence","summary","description","tier","column_count","column_groups"],"properties":{"cadence":{"type":"string","description":"Granularity + partitioning, e.g. \"1-minute bars, partitioned per (coin, month)\"."},"category":{"type":"string","description":"Presentation category, e.g. `raw-tiles` or `forecast-layer`."},"column_count":{"type":"integer","description":"Number of documented columns.","minimum":0},"column_groups":{"type":"array","items":{"$ref":"#/components/schemas/ColumnGroup"},"description":"Columns, grouped for presentation, in schema order."},"description":{"type":"string","description":"Longer prose — the dictionary page header."},"name":{"type":"string","description":"Dataset name / asset key, e.g. `gold_ohlcv_1m`.","example":"gold_ohlcv_1m"},"note":{"type":["string","null"],"description":"Optional \"how to use this\" callout."},"summary":{"type":"string","description":"One-line intuitive summary — the catalog card."},"tier":{"type":"string","description":"Display tier: `free` or `pro`. Re-derived from `policy.rs` on read, so it\nalways matches actual entitlement regardless of the on-disk value."},"title":{"type":"string","description":"Human-friendly title, e.g. \"Order-flow OHLCV (1-minute)\"."}}},"DatasetSummary":{"type":"object","required":["name","partition_count","coins","months"],"properties":{"coins":{"type":"array","items":{"type":"string"},"description":"Distinct coins present, sorted."},"months":{"$ref":"#/components/schemas/MonthRange"},"name":{"type":"string","description":"Dataset name, e.g. `gold_ohlcv_1m`.","example":"gold_ohlcv_1m"},"partition_count":{"type":"integer","description":"Number of partitions visible to the caller.","minimum":0}}},"DatasetsResponse":{"type":"object","required":["generated_at","datasets"],"properties":{"datasets":{"type":"array","items":{"$ref":"#/components/schemas/DatasetSummary"}},"generated_at":{"type":"string","description":"RFC3339 timestamp the catalog manifest was generated."}}},"DownloadResponse":{"type":"object","required":["url","expires_at"],"properties":{"expires_at":{"type":"string","description":"RFC3339 timestamp at which the URL expires."},"url":{"type":"string","description":"Presigned Tigris URL for the parquet object."}}},"ErrorBody":{"type":"object","description":"The error response body. Every error variant serialises to this shape —\na single machine-readable `error` code. Declared as a real struct (rather\nthan the inline `json!` below) only so it can be referenced as a response\n`body` in the OpenAPI spec; `into_response` still emits the same JSON.","required":["error"],"properties":{"error":{"type":"string","description":"Machine-readable error code, e.g. `not_found`, `unauthorized`.","example":"not_found"}}},"MonthRange":{"type":"object","properties":{"earliest":{"type":["string","null"],"description":"Earliest partition month (`YYYY-MM`), if any."},"latest":{"type":["string","null"],"description":"Latest partition month (`YYYY-MM`), if any."}}},"Partition":{"type":"object","required":["coin","month","size_bytes"],"properties":{"coin":{"type":"string","description":"Coin symbol, e.g. `BTC`.","example":"BTC"},"is_open":{"type":["boolean","null"],"description":"Whether this is the current, in-progress month — its parquet is\nre-materialised daily (part-month freshness) and therefore grows under\nthe customer. Absent (`None`) in older (v1) manifests."},"modified_at":{"type":["string","null"],"description":"RFC3339 timestamp of the last write, if known."},"month":{"type":"string","description":"Partition month, `YYYY-MM`.","example":"2025-09"},"size_bytes":{"type":"integer","format":"int64","description":"Parquet object size in bytes."}}},"PartitionsResponse":{"type":"object","required":["asset","generated_at","partitions"],"properties":{"asset":{"type":"string","description":"Dataset name the partitions belong to."},"generated_at":{"type":"string","description":"RFC3339 timestamp the catalog manifest was generated."},"partitions":{"type":"array","items":{"$ref":"#/components/schemas/Partition"}}}}},"securitySchemes":{"api_key":{"type":"http","scheme":"bearer","description":"Raw API key sent as a bearer token."}}},"tags":[{"name":"catalog","description":"Public data catalog and per-column data dictionary (no API key required)."},{"name":"datasets","description":"Browse and download gold datasets (authenticated with an API key)."}]}