{"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"},"example":"gold_ohlcv_1m"}],"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"},"example":"gold_ohlcv_1m"},{"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"},"example":"gold_ohlcv_1m"},{"name":"coin","in":"path","description":"Coin symbol, e.g. BTC","required":true,"schema":{"type":"string"},"example":"BTC"},{"name":"month","in":"path","description":"Partition month, YYYY-MM","required":true,"schema":{"type":"string"},"example":"2026-08"}],"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":[]}]}},"/v1/datasets/{asset}/{month}/download":{"get":{"tags":["datasets"],"summary":"Download a market-wide (coinless) partition.","description":"Same as [`download_url`] but for datasets with no coin dimension (one row per\nmonth). The path has no `{coin}` segment.","operationId":"download_url_coinless","parameters":[{"name":"asset","in":"path","description":"Market-wide dataset name (coinless; none currently published)","required":true,"schema":{"type":"string"}},{"name":"month","in":"path","description":"Partition month, YYYY-MM","required":true,"schema":{"type":"string"},"example":"2026-08"}],"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."},"window":{"type":["string","null"],"description":"Temporal window of this group's fields relative to the timestamp label:\none of `point_in_time`, `backward`, `forward`, `contemporaneous`,\n`static`. Null when the dataset-level `temporal.convention` covers them."}}},"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":"How frequently the data is sampled, e.g. \"1-minute bars\"."},"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."},"direct_answer":{"type":"string","description":"40-60 word keyword-first lead answer — the definitional \"what is this\"\nblurb, and the strongest AI-citation extraction target. Defaulted for\nforward/backward compatibility with snapshots predating the field."},"keywords":{"type":"array","items":{"type":"string"},"description":"Per-dataset discovery keywords (schema.org keywords on the web)."},"name":{"type":"string","description":"Dataset name, exactly as `list_datasets` reports it."},"note":{"type":["string","null"],"description":"Optional \"how to use this\" callout."},"seo_title":{"type":"string","description":"Keyword-first SEO title tag (web `<title>`). Defaulted so older snapshots\nwithout the field still deserialize."},"summary":{"type":"string","description":"One-line intuitive summary — the catalog card."},"temporal":{"$ref":"#/components/schemas/Temporal","description":"Machine-readable timestamp/interval contract: what the label marks and\nhow to join without leaking the future. Defaulted so snapshots predating\nthe field still deserialize."},"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)\"."},"use_case":{"type":"string","description":"One-line \"what you'd use it for\" (buyer-intent) copy."}}},"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":["month","size_bytes"],"properties":{"coin":{"type":["string","null"],"description":"Coin symbol, e.g. `BTC`. Absent (`None`) for market-wide (coinless)\ndatasets whose parquet is one row per month with no coin dimension —\nnone are currently published.","example":"BTC"},"coverage":{"type":["number","null"],"format":"double","description":"Fraction of the expected time-buckets that are populated (`rows` ÷\nelapsed buckets) — the tradable-universe signal: the 1-minute grid is\ntrade-driven and gappy on thin coins, the hourly grids near-complete.\nPresent alongside `rows`; `None` elsewhere."},"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"},"rows":{"type":["integer","null"],"format":"int64","description":"Row count (parquet `num_rows`). Present only for the time-series tiles\n(`gold_ohlcv_1m`, `gold_funding_1h`, `gold_positioning_1h`) from v3\nmanifests; `None` elsewhere and in older manifests."},"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"}}}},"Temporal":{"type":"object","description":"The dataset's temporal contract — what the timestamp column marks and the\nlook-ahead-safety rules for joining. Mirror of the resolver's `temporal`\nblock (`semantic/__init__.py`).","required":["grain","timestamp_field","label","convention"],"properties":{"convention":{"type":"string","description":"One-paragraph plain-English join / look-ahead contract."},"grain":{"type":"string","description":"Observation width, e.g. `1m`, `1h`, `1d`, `1mo`."},"label":{"type":"string","description":"What the label marks: one of `interval_start`, `interval_end`,\n`snapshot`, `forecast_target`."},"timestamp_field":{"type":"string","description":"Which column carries the label, e.g. `time`, `day`, `month_start`."}}}},"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)."}]}