tessera-api 0.3.1

High-performance Rust client for the Tessera API — Hyperliquid datasets straight into Polars & DuckDB.
Documentation
1
{"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. 1.1.0: a partition may be day-backed (`Partition.days`), and the download route answers such a partition with one presigned URL per day (`200` JSON, no redirect) instead of the single-url/`302` shape every finalised month still uses.","license":{"name":"MIT","identifier":"MIT"},"version":"1.1.0"},"servers":[{"url":"/","description":"Same-origin (production fronts the API via CloudFront)"}],"paths":{"/v1/bundles":{"get":{"tags":["catalog"],"summary":"List the one-off download bundles.","description":"Public (no API key) — the same discovery-surface rationale as `/v1/catalog`.\nEvery count is derived from the manifest at request time, so a displayed\ntile count cannot lie, and the per-dataset coverage block is the §6.1\ndisclosure: a buyer going straight to download still sees which partitions\nare materially below their calendar expectation.","operationId":"bundle_catalogue","responses":{"200":{"description":"The one-off bundles available for purchase","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BundleCatalogueResponse"}}}},"503":{"description":"Catalog manifest unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/v1/catalog":{"get":{"tags":["catalog"],"summary":"List the data catalog.","description":"Public (no API key). Returns every customer-facing dataset with an intuitive\nsummary — the high-level catalog. Drill into `/v1/catalog/{asset}` for the\nper-column data dictionary. This is documentation only. Actual data access\nstays 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":"JSON download body. One of two shapes: a single presigned URL for a month-grain partition, or one URL per day object for a day-backed partition (the open month, which has no single parquet). Returned for a month-grain partition only when the request sends `Accept: application/json`; a day-backed partition is always JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DownloadBody"}}}},"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":"JSON download body. One of two shapes: a single presigned URL for a month-grain partition, or one URL per day object for a day-backed partition (the open month, which has no single parquet). Returned for a month-grain partition only when the request sends `Accept: application/json`; a day-backed partition is always JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DownloadBody"}}}},"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":{"BundleCatalogueEntry":{"type":"object","required":["bundle","name","price_cents","currency","datasets","max_month","partitions","size_bytes","months","coverage"],"properties":{"bundle":{"type":"string","description":"Stable token: `majors` | `hip3` | `all`."},"coin_count":{"type":["integer","null"],"description":"Distinct coins with at least one partition in the sold months.\n`null` when the bundle is the whole universe.","minimum":0},"coverage":{"type":"array","items":{"$ref":"#/components/schemas/DatasetCoverage"},"description":"Per-dataset coverage over the bundle's partitions — the §6.1 disclosure."},"currency":{"type":"string"},"datasets":{"type":"array","items":{"type":"string"},"description":"Datasets carried (always the three customer-facing ones)."},"max_month":{"type":"string","description":"Newest month the bundle sells, `YYYY-MM`."},"months":{"$ref":"#/components/schemas/MonthRange"},"name":{"type":"string"},"partitions":{"type":"integer","description":"Partitions (asset × coin × month) in the bundle.","minimum":0},"price_cents":{"type":"integer","format":"int64","description":"Price in cents."},"size_bytes":{"type":"integer","format":"int64"}}},"BundleCatalogueResponse":{"type":"object","required":["generated_at","bundles"],"properties":{"bundles":{"type":"array","items":{"$ref":"#/components/schemas/BundleCatalogueEntry"}},"generated_at":{"type":"string","description":"Manifest `generated_at` — every count below is derived from it."}}},"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","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."},"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."}}},"DatasetCoverage":{"type":"object","required":["asset","partitions","under_floor","worst"],"properties":{"asset":{"type":"string"},"median_coverage":{"type":["number","null"],"format":"double","description":"Median of the manifest `coverage` values; `null` when none are present."},"min_coverage":{"type":["number","null"],"format":"double"},"partitions":{"type":"integer","minimum":0},"under_floor":{"type":"integer","description":"Count of partitions whose `coverage` is below [`BUNDLE_COVERAGE_FLOOR`].","minimum":0},"worst":{"type":"array","items":{"$ref":"#/components/schemas/LowCoveragePartition"},"description":"The worst `under_floor` partitions, ascending by coverage, capped at\n[`MAX_DISCLOSED_PARTITIONS`]. `under_floor` is the exact count, so the\ndisclosure is complete-by-count and representative-by-list."}}},"DatasetDoc":{"type":"object","description":"One dataset's catalog entry + full data dictionary.","required":["name","title","category","cadence","summary","description","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."},"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."}}},"DayDownload":{"type":"object","description":"One day object of a day-backed partition: where to fetch it and until when.","required":["date","url","expires_at"],"properties":{"date":{"type":"string","description":"The day this object covers, `YYYY-MM-DD`."},"expires_at":{"type":"string","description":"RFC3339 timestamp at which the URL expires."},"url":{"type":"string","description":"Presigned Tigris URL for that day's parquet."}}},"DayDownloadResponse":{"type":"object","description":"The shape a **day-backed** partition's download returns: one presigned URL per\nday object, because the open month is a set of day objects rather than one\nparquet.\n\nAlways JSON, never a redirect: a single `Location` header cannot carry N URLs,\nand the API never proxies or concatenates the bytes — each URL is one object\nthe client fetches directly from Tigris.","required":["asset","month","is_open","days"],"properties":{"asset":{"type":"string"},"coin":{"type":["string","null"]},"days":{"type":"array","items":{"$ref":"#/components/schemas/DayDownload"}},"is_open":{"type":"boolean","description":"Whether this is the current, in-progress month. A finalised month is\ncompacted to one object, so `false` here means the month closed since the\nlast compaction: the data is complete, the layout is not yet folded."},"month":{"type":"string"}}},"DownloadBody":{"oneOf":[{"$ref":"#/components/schemas/DownloadResponse","description":"A single-object partition (every finalised month): one parquet, and a 302\nto it by default."},{"$ref":"#/components/schemas/DayDownloadResponse","description":"A day-backed partition (the open month): one parquet per day."}],"description":"The 200 body of a download route, whichever shape the partition has.\n\nOnly the OpenAPI components: the handler builds one variant or the other\ndirectly, so this exists solely so the generated document names both."},"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, and nothing else. Declared as a real\nstruct (rather than the inline `json!` below) only so it can be referenced as\na response `body` in the OpenAPI spec; `into_response` still emits the same\nJSON.","required":["error"],"properties":{"error":{"type":"string","description":"Machine-readable error code, e.g. `not_found`, `unauthorized`.","example":"not_found"}}},"LowCoveragePartition":{"type":"object","required":["asset","month","coverage"],"properties":{"asset":{"type":"string"},"coin":{"type":["string","null"]},"coverage":{"type":"number","format":"double"},"month":{"type":"string"}}},"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."},"days":{"type":["array","null"],"items":{"type":"string"},"description":"The `YYYY-MM-DD` day objects this partition is made of, when it is\n**day-backed**. The open month has no single object: it is one parquet per\nday until the month closes, and a download of it is one presigned URL per\nentry here. Absent (from a v5 and older manifest) means the partition is a\nsingle month object — the shape every finalised month has once compacted."},"is_open":{"type":["boolean","null"],"description":"Whether this is the current, in-progress month. A finalised month is one\nparquet; the open month is **day-backed** (see `days`) and has no month\nobject, so it is materialised continuously and grows under the customer.\nAbsent (`None`) in older (v1) manifests."},"last_time":{"type":["string","null"],"description":"RFC3339 UTC timestamp of the newest row in the partition's data (the max\nof the footers' `time` statistics) — how far this partition's data\nreaches. The point of the field is the **open month**: it is updated as\nthe day arrives, so `last_time` tells a consumer that today's bars are\nalready downloadable (and how far they run). For a finalised month it is\nthat month's last bar. Present only on the time-series tiles, from v4\nmanifests; `None` elsewhere, and for a partition whose footer carries no\n`time` statistics."},"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)."}]}