{ "openapi": "3.1.0", "info": { "title": "cotfin API Reference", "version": "0.1.0", "description": "CFTC source API for bluedoor Financial Data.\nOfficial CFTC positioning data with consistent report-family routing.\nCoverage: Commitments of Traders reports; Report families; CFTC product hierarchy; SoQL-style filters.\nGenerated from the live source contract and representative live API responses on 2026-06-07T01:30:59.456Z." }, "servers": [ { "url": "https://api.cotfin.bluedoor.sh", "description": "cotfin source API" } ], "externalDocs": { "description": "CFTC source API docs", "url": "https://bluedoor.sh/apis/financial-data/sources/cotfin" }, "tags": [ { "name": "Reports" } ], "paths": { "/v1/product-hierarchy": { "get": { "parameters": [ { "description": "Socrata row cap; defaults to 100.", "in": "query", "name": "limit", "required": false, "schema": { "type": "string" } }, { "name": "x-cotfin-contact", "in": "header", "required": false, "schema": { "type": "string", "format": "email" }, "description": "Optional contact email for higher public rate limits and support diagnostics." }, { "name": "authorization", "in": "header", "required": false, "schema": { "type": "string", "example": "Bearer " }, "description": "Optional API-key authorization for higher-volume access tiers." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cotfin_get_product_hierarchyResponse" }, "examples": { "live": { "summary": "Live response", "value": { "meta": { "product": "cotfin", "source": "cftc_cot", "endpoint_id": "cftc.cot_product_hierarchy", "family": "commitments-of-traders", "route": "/v1/product-hierarchy", "path_params": {}, "status": "ok", "cache": "hit", "identity_tier": "contact", "generated_at": "2026-06-07T01:33:18.641Z", "freshness": { "max_age_seconds": 3600, "stale_while_revalidate_seconds": 86400, "stale": false }, "rate_plan": { "public_request_budget_per_user_rpm": 200 } }, "data": { "rows": [ { "contract_market_code": "001601", "commodity_name": "WHEAT", "commodity_subgroup_name": "GRAINS", "commodity_group_name": "AGRICULTURE" }, { "contract_market_code": "001602", "commodity_name": "WHEAT", "commodity_subgroup_name": "GRAINS", "commodity_group_name": "AGRICULTURE" }, { "contract_market_code": "001603", "commodity_name": "WHEAT", "commodity_subgroup_name": "GRAINS", "commodity_group_name": "AGRICULTURE" } ], "normalized": [ { "contract_market_code": "001601", "commodity_name": "WHEAT", "commodity_subgroup_name": "GRAINS", "commodity_group_name": "AGRICULTURE" }, { "contract_market_code": "001602", "commodity_name": "WHEAT", "commodity_subgroup_name": "GRAINS", "commodity_group_name": "AGRICULTURE" }, { "contract_market_code": "001603", "commodity_name": "WHEAT", "commodity_subgroup_name": "GRAINS", "commodity_group_name": "AGRICULTURE" } ] } } } } } }, "description": "Successful response." }, "400": { "content": { "application/json": { "schema": { "properties": { "data": {}, "error": { "type": "object" }, "meta": { "type": "object" } }, "type": "object" } } }, "description": "JSON envelope" }, "401": { "description": "Unauthorized. API-key authenticated tiers use an Authorization bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "default": { "summary": "HTTP 401 error", "value": { "ok": false, "error": { "code": "unauthorized", "message": "A valid API key is required for this tier." } } } } } } }, "404": { "content": { "application/json": { "schema": { "properties": { "data": {}, "error": { "type": "object" }, "meta": { "type": "object" } }, "type": "object" } } }, "description": "JSON envelope" }, "405": { "description": "Method not allowed. Source API routes are documented as HTTP GET unless otherwise specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "default": { "summary": "HTTP 405 error", "value": { "ok": false, "error": { "code": "method_not_allowed", "message": "This route does not support the requested HTTP method." } } } } } } }, "429": { "description": "Rate limited. Retry after the limit reset or include the documented contact/API-key headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "default": { "summary": "HTTP 429 error", "value": { "ok": false, "error": { "code": "rate_limited", "message": "Too many requests. Retry after the rate-limit reset." } } } } } } }, "502": { "content": { "application/json": { "schema": { "properties": { "data": {}, "error": { "type": "object" }, "meta": { "type": "object" } }, "type": "object" } } }, "description": "JSON envelope" }, "503": { "description": "Service unavailable. The source API or an upstream dependency is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "default": { "summary": "HTTP 503 error", "value": { "ok": false, "error": { "code": "service_unavailable", "message": "The service is temporarily unavailable." } } } } } } }, "504": { "description": "Upstream timeout. The upstream source did not return within the source API timeout window.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "default": { "summary": "HTTP 504 error", "value": { "ok": false, "error": { "code": "upstream_timeout", "message": "The upstream source timed out." } } } } } } } }, "summary": "Product hierarchy", "security": [ {}, { "ContactEmail": [] }, { "BearerAuth": [] }, { "CotfinApiKey": [] } ], "operationId": "cotfin_get_product_hierarchy", "description": "Returns product hierarchy with source-native fields and identifiers.", "x-source-api": "cotfin", "x-source-name": "CFTC", "x-source-upstream": "cftc.gov", "x-docs-example-url": "https://api.cotfin.bluedoor.sh/v1/product-hierarchy?limit=3", "x-docs-example-status": 200, "x-docs-captured-at": "2026-06-07T01:33:18.654Z" } }, "/v1/report-families": { "get": { "parameters": [ { "name": "x-cotfin-contact", "in": "header", "required": false, "schema": { "type": "string", "format": "email" }, "description": "Optional contact email for higher public rate limits and support diagnostics." }, { "name": "authorization", "in": "header", "required": false, "schema": { "type": "string", "example": "Bearer " }, "description": "Optional API-key authorization for higher-volume access tiers." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cotfin_get_report_familiesResponse" }, "examples": { "live": { "summary": "Live response", "value": { "meta": { "product": "cotfin", "source": "cftc_cot", "route": "report_families" }, "data": [ { "family": "tff-futures-only", "id": "cftc.cot_tff_futures_only", "label": "TFF Futures Only", "fields": [ "report_date_as_yyyy_mm_dd", "market_and_exchange_names", "contract_market_name" ] }, { "family": "tff-combined", "id": "cftc.cot_tff_combined", "label": "TFF Combined", "fields": [ "report_date_as_yyyy_mm_dd", "market_and_exchange_names", "contract_market_name" ] }, { "family": "tff-all", "id": "cftc.cot_tff_all", "label": "TFF All", "fields": [ "report_date_as_yyyy_mm_dd", "market_and_exchange_names", "contract_market_name" ] } ] } } } } }, "description": "Successful response." }, "400": { "content": { "application/json": { "schema": { "properties": { "data": {}, "error": { "type": "object" }, "meta": { "type": "object" } }, "type": "object" } } }, "description": "JSON envelope" }, "401": { "description": "Unauthorized. API-key authenticated tiers use an Authorization bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "default": { "summary": "HTTP 401 error", "value": { "ok": false, "error": { "code": "unauthorized", "message": "A valid API key is required for this tier." } } } } } } }, "404": { "content": { "application/json": { "schema": { "properties": { "data": {}, "error": { "type": "object" }, "meta": { "type": "object" } }, "type": "object" } } }, "description": "JSON envelope" }, "405": { "description": "Method not allowed. Source API routes are documented as HTTP GET unless otherwise specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "default": { "summary": "HTTP 405 error", "value": { "ok": false, "error": { "code": "method_not_allowed", "message": "This route does not support the requested HTTP method." } } } } } } }, "429": { "description": "Rate limited. Retry after the limit reset or include the documented contact/API-key headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "default": { "summary": "HTTP 429 error", "value": { "ok": false, "error": { "code": "rate_limited", "message": "Too many requests. Retry after the rate-limit reset." } } } } } } }, "502": { "content": { "application/json": { "schema": { "properties": { "data": {}, "error": { "type": "object" }, "meta": { "type": "object" } }, "type": "object" } } }, "description": "JSON envelope" }, "503": { "description": "Service unavailable. The source API or an upstream dependency is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "default": { "summary": "HTTP 503 error", "value": { "ok": false, "error": { "code": "service_unavailable", "message": "The service is temporarily unavailable." } } } } } } }, "504": { "description": "Upstream timeout. The upstream source did not return within the source API timeout window.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "default": { "summary": "HTTP 504 error", "value": { "ok": false, "error": { "code": "upstream_timeout", "message": "The upstream source timed out." } } } } } } } }, "summary": "Families", "security": [ {}, { "ContactEmail": [] }, { "BearerAuth": [] }, { "CotfinApiKey": [] } ], "operationId": "cotfin_get_report_families", "description": "Returns families with source-native report rows, filters, and metadata fields.", "tags": [ "Reports" ], "x-source-api": "cotfin", "x-source-name": "CFTC", "x-source-upstream": "cftc.gov", "x-docs-example-url": "https://api.cotfin.bluedoor.sh/v1/report-families", "x-docs-example-status": 200, "x-docs-captured-at": "2026-06-07T01:33:18.870Z" } }, "/v1/reports/{family}": { "get": { "parameters": [ { "description": "COT report family slug.", "in": "path", "name": "family", "required": true, "schema": { "enum": [ "tff-futures-only", "tff-combined", "tff-all", "disaggregated-futures-only", "disaggregated-combined", "disaggregated-all", "legacy-futures-only", "legacy-combined", "legacy-all", "supplemental-cit", "cit-all" ], "type": "string" } }, { "description": "Socrata row cap; defaults to 100.", "in": "query", "name": "limit", "required": false, "schema": { "type": "string" } }, { "description": "Socrata row offset.", "in": "query", "name": "offset", "required": false, "schema": { "type": "string" } }, { "description": "SoQL where clause.", "in": "query", "name": "where", "required": false, "schema": { "type": "string" } }, { "description": "SoQL select clause.", "in": "query", "name": "select", "required": false, "schema": { "type": "string" } }, { "description": "SoQL order clause.", "in": "query", "name": "order", "required": false, "schema": { "type": "string" } }, { "name": "x-cotfin-contact", "in": "header", "required": false, "schema": { "type": "string", "format": "email" }, "description": "Optional contact email for higher public rate limits and support diagnostics." }, { "name": "authorization", "in": "header", "required": false, "schema": { "type": "string", "example": "Bearer " }, "description": "Optional API-key authorization for higher-volume access tiers." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cotfin_get_reports_familyResponse" }, "examples": { "live": { "summary": "Live response", "value": { "meta": { "product": "cotfin", "source": "cftc_cot", "endpoint_id": "cftc.cot_tff_futures_only", "family": "tff-futures-only", "route": "/v1/reports/{family}", "path_params": { "family": "tff-futures-only" }, "status": "ok", "cache": "hit", "identity_tier": "contact", "generated_at": "2026-06-07T01:33:19.094Z", "freshness": { "max_age_seconds": 3600, "stale_while_revalidate_seconds": 86400, "stale": false }, "rate_plan": { "public_request_budget_per_user_rpm": 200 } }, "data": { "rows": [ { "id": "220913020601F", "market_and_exchange_names": "UST BOND - CHICAGO BOARD OF TRADE", "report_date_as_yyyy_mm_dd": "2022-09-13T00:00:00.000", "yyyy_report_week_ww": "2022 Report Week 37", "contract_market_name": "UST BOND", "cftc_contract_market_code": "020601", "cftc_market_code": "CBT ", "cftc_region_code": "CHI", "cftc_commodity_code": "020 ", "commodity_name": "T-BONDS", "open_interest_all": "1225024", "dealer_positions_long_all": "21636", "dealer_positions_short_all": "149374", "dealer_positions_spread_all": "1393", "asset_mgr_positions_long": "591919", "asset_mgr_positions_short": "257837", "asset_mgr_positions_spread": "206578", "lev_money_positions_long": "111379", "lev_money_positions_short": "329268", "lev_money_positions_spread": "39023", "other_rept_positions_long": "81550", "other_rept_positions_short": "98448", "other_rept_positions_spread": "0", "tot_rept_positions_long_all": "1053478", "tot_rept_positions_short": "1081921", "nonrept_positions_long_all": "171546", "nonrept_positions_short_all": "143103", "change_in_open_interest_all": "15684", "change_in_dealer_long_all": "2112", "change_in_dealer_short_all": "20182", "change_in_dealer_spread_all": "-73", "change_in_asset_mgr_long": "5132", "change_in_asset_mgr_short": "-3403", "change_in_asset_mgr_spread": "2170", "change_in_lev_money_long": "4435", "change_in_lev_money_short": "3021", "change_in_lev_money_spread": "-4183", "change_in_other_rept_long": "2505", "change_in_other_rept_short": "1784", "change_in_other_rept_spread": "0", "change_in_tot_rept_long_all": "12098", "change_in_tot_rept_short": "19498", "change_in_nonrept_long_all": "3586", "change_in_nonrept_short_all": "-3814", "pct_of_open_interest_all": "100.0", "pct_of_oi_dealer_long_all": "1.8", "pct_of_oi_dealer_short_all": "12.2", "pct_of_oi_dealer_spread_all": "0.1", "pct_of_oi_asset_mgr_long": "48.3", "pct_of_oi_asset_mgr_short": "21.0", "pct_of_oi_asset_mgr_spread": "16.9", "pct_of_oi_lev_money_long": "9.1", "pct_of_oi_lev_money_short": "26.9", "pct_of_oi_lev_money_spread": "3.2", "pct_of_oi_other_rept_long": "6.7", "pct_of_oi_other_rept_short": "8.0", "pct_of_oi_other_rept_spread": "0.0", "pct_of_oi_tot_rept_long_all": "86.0", "pct_of_oi_tot_rept_short": "88.3", "pct_of_oi_nonrept_long_all": "14.0", "pct_of_oi_nonrept_short_all": "11.7", "traders_tot_all": "183", "traders_dealer_long_all": "8", "traders_dealer_short_all": "19", "traders_asset_mgr_long_all": "63", "traders_asset_mgr_short_all": "26", "traders_asset_mgr_spread": "59", "traders_lev_money_long_all": "23", "traders_lev_money_short_all": "31", "traders_lev_money_spread": "21", "traders_other_rept_long_all": "5", "traders_other_rept_short": "8", "traders_other_rept_spread": "0", "traders_tot_rept_long_all": "132", "traders_tot_rept_short_all": "134", "conc_gross_le_4_tdr_long": "21.7", "conc_gross_le_4_tdr_short": "26.2", "conc_gross_le_8_tdr_long": "34.8", "conc_gross_le_8_tdr_short": "36.4", "conc_net_le_4_tdr_long_all": "19.1", "conc_net_le_4_tdr_short_all": "22.5", "conc_net_le_8_tdr_long_all": "29.2", "conc_net_le_8_tdr_short_all": "30.9", "contract_units": "(CONTRACTS OF $100,000 FACE VALUE)", "cftc_subgroup_code": "F30", "commodity": "T-BONDS", "commodity_subgroup_name": "Interest Rates - U.S. Treasury", "commodity_group_name": "FINANCIAL INSTRUMENTS", "futonly_or_combined": "FutOnly" }, { "id": "220913020604F", "market_and_exchange_names": "ULTRA UST BOND - CHICAGO BOARD OF TRADE", "report_date_as_yyyy_mm_dd": "2022-09-13T00:00:00.000", "yyyy_report_week_ww": "2022 Report Week 37", "contract_market_name": "ULTRA UST BOND", "cftc_contract_market_code": "020604", "cftc_market_code": "CBT ", "cftc_region_code": "CHI", "cftc_commodity_code": "020 ", "commodity_name": "T-BONDS", "open_interest_all": "1376937", "dealer_positions_long_all": "8384", "dealer_positions_short_all": "47242", "dealer_positions_spread_all": "6698", "asset_mgr_positions_long": "829753", "asset_mgr_positions_short": "218898", "asset_mgr_positions_spread": "230475", "lev_money_positions_long": "53169", "lev_money_positions_short": "708446", "lev_money_positions_spread": "37455", "other_rept_positions_long": "62216", "other_rept_positions_short": "14921", "other_rept_positions_spread": "0", "tot_rept_positions_long_all": "1228150", "tot_rept_positions_short": "1264135", "nonrept_positions_long_all": "148787", "nonrept_positions_short_all": "112802", "change_in_open_interest_all": "16537", "change_in_dealer_long_all": "17", "change_in_dealer_short_all": "2195", "change_in_dealer_spread_all": "1015", "change_in_asset_mgr_long": "20620", "change_in_asset_mgr_short": "7839", "change_in_asset_mgr_spread": "-7224", "change_in_lev_money_long": "3761", "change_in_lev_money_short": "19955", "change_in_lev_money_spread": "-1563", "change_in_other_rept_long": "72", "change_in_other_rept_short": "799", "change_in_other_rept_spread": "0", "change_in_tot_rept_long_all": "16698", "change_in_tot_rept_short": "23016", "change_in_nonrept_long_all": "-161", "change_in_nonrept_short_all": "-6479", "pct_of_open_interest_all": "100.0", "pct_of_oi_dealer_long_all": "0.6", "pct_of_oi_dealer_short_all": "3.4", "pct_of_oi_dealer_spread_all": "0.5", "pct_of_oi_asset_mgr_long": "60.3", "pct_of_oi_asset_mgr_short": "15.9", "pct_of_oi_asset_mgr_spread": "16.7", "pct_of_oi_lev_money_long": "3.9", "pct_of_oi_lev_money_short": "51.5", "pct_of_oi_lev_money_spread": "2.7", "pct_of_oi_other_rept_long": "4.5", "pct_of_oi_other_rept_short": "1.1", "pct_of_oi_other_rept_spread": "0.0", "pct_of_oi_tot_rept_long_all": "89.2", "pct_of_oi_tot_rept_short": "91.8", "pct_of_oi_nonrept_long_all": "10.8", "pct_of_oi_nonrept_short_all": "8.2", "traders_tot_all": "160", "traders_dealer_short_all": "10", "traders_dealer_spread_all": "4", "traders_asset_mgr_long_all": "79", "traders_asset_mgr_short_all": "25", "traders_asset_mgr_spread": "63", "traders_lev_money_long_all": "10", "traders_lev_money_short_all": "23", "traders_lev_money_spread": "17", "traders_other_rept_long_all": "7", "traders_other_rept_spread": "0", "traders_tot_rept_long_all": "131", "traders_tot_rept_short_all": "113", "conc_gross_le_4_tdr_long": "23.0", "conc_gross_le_4_tdr_short": "39.4", "conc_gross_le_8_tdr_long": "38.3", "conc_gross_le_8_tdr_short": "56.1", "conc_net_le_4_tdr_long_all": "20.1", "conc_net_le_4_tdr_short_all": "38.6", "conc_net_le_8_tdr_long_all": "33.5", "conc_net_le_8_tdr_short_all": "52.5", "contract_units": "(CONTRACTS OF $100,000 FACE VALUE)", "cftc_subgroup_code": "F30", "commodity": "T-BONDS", "commodity_subgroup_name": "Interest Rates - U.S. Treasury", "commodity_group_name": "FINANCIAL INSTRUMENTS", "futonly_or_combined": "FutOnly" }, { "id": "220913042601F", "market_and_exchange_names": "UST 2Y NOTE - CHICAGO BOARD OF TRADE", "report_date_as_yyyy_mm_dd": "2022-09-13T00:00:00.000", "yyyy_report_week_ww": "2022 Report Week 37", "contract_market_name": "UST 2Y NOTE", "cftc_contract_market_code": "042601", "cftc_market_code": "CBT ", "cftc_region_code": "CHI", "cftc_commodity_code": "042 ", "commodity_name": "T-NOTES, 1-2 YEAR", "open_interest_all": "2008780", "dealer_positions_long_all": "50855", "dealer_positions_short_all": "273099", "dealer_positions_spread_all": "11514", "asset_mgr_positions_long": "1094819", "asset_mgr_positions_short": "447511", "asset_mgr_positions_spread": "292382", "lev_money_positions_long": "171316", "lev_money_positions_short": "470250", "lev_money_positions_spread": "84629", "other_rept_positions_long": "159665", "other_rept_positions_short": "207795", "other_rept_positions_spread": "900", "tot_rept_positions_long_all": "1866080", "tot_rept_positions_short": "1788080", "nonrept_positions_long_all": "142700", "nonrept_positions_short_all": "220700", "change_in_open_interest_all": "54353", "change_in_dealer_long_all": "10292", "change_in_dealer_short_all": "25379", "change_in_dealer_spread_all": "-2076", "change_in_asset_mgr_long": "91911", "change_in_asset_mgr_short": "-45050", "change_in_asset_mgr_spread": "-10059", "change_in_lev_money_long": "4156", "change_in_lev_money_short": "122174", "change_in_lev_money_spread": "-38041", "change_in_other_rept_long": "-957", "change_in_other_rept_short": "11151", "change_in_other_rept_spread": "-13", "change_in_tot_rept_long_all": "55213", "change_in_tot_rept_short": "63465", "change_in_nonrept_long_all": "-860", "change_in_nonrept_short_all": "-9112", "pct_of_open_interest_all": "100.0", "pct_of_oi_dealer_long_all": "2.5", "pct_of_oi_dealer_short_all": "13.6", "pct_of_oi_dealer_spread_all": "0.6", "pct_of_oi_asset_mgr_long": "54.5", "pct_of_oi_asset_mgr_short": "22.3", "pct_of_oi_asset_mgr_spread": "14.6", "pct_of_oi_lev_money_long": "8.5", "pct_of_oi_lev_money_short": "23.4", "pct_of_oi_lev_money_spread": "4.2", "pct_of_oi_other_rept_long": "7.9", "pct_of_oi_other_rept_short": "10.3", "pct_of_oi_other_rept_spread": "0.0", "pct_of_oi_tot_rept_long_all": "92.9", "pct_of_oi_tot_rept_short": "89.0", "pct_of_oi_nonrept_long_all": "7.1", "pct_of_oi_nonrept_short_all": "11.0", "traders_tot_all": "346", "traders_dealer_long_all": "13", "traders_dealer_short_all": "38", "traders_dealer_spread_all": "10", "traders_asset_mgr_long_all": "102", "traders_asset_mgr_short_all": "53", "traders_asset_mgr_spread": "87", "traders_lev_money_long_all": "29", "traders_lev_money_short_all": "73", "traders_lev_money_spread": "30", "traders_other_rept_long_all": "13", "traders_other_rept_short": "25", "traders_other_rept_spread": "4", "traders_tot_rept_long_all": "210", "traders_tot_rept_short_all": "267", "conc_gross_le_4_tdr_long": "25.5", "conc_gross_le_4_tdr_short": "16.8", "conc_gross_le_8_tdr_long": "39.2", "conc_gross_le_8_tdr_short": "24.4", "conc_net_le_4_tdr_long_all": "23.4", "conc_net_le_4_tdr_short_all": "13.0", "conc_net_le_8_tdr_long_all": "34.4", "conc_net_le_8_tdr_short_all": "20.1", "contract_units": "(CONTRACTS OF $200,000 FACE VALUE)", "cftc_subgroup_code": "F30", "commodity": "T-NOTES, 1-2 YEAR", "commodity_subgroup_name": "Interest Rates - U.S. Treasury", "commodity_group_name": "FINANCIAL INSTRUMENTS", "futonly_or_combined": "FutOnly" } ], "normalized": [ { "report_date": "2022-09-13T00:00:00.000", "market_and_exchange_names": "UST BOND - CHICAGO BOARD OF TRADE", "contract_market_name": "UST BOND", "cftc_contract_market_code": "020601", "cftc_market_code": "CBT ", "cftc_region_code": "CHI", "cftc_commodity_code": "020 ", "commodity_name": "T-BONDS", "commodity_group_name": "FINANCIAL INSTRUMENTS", "open_interest": 1225024, "positions": { "dealer": { "long_all": 21636, "short_all": 149374, "spread": 1393 }, "asset_mgr": { "long": 591919, "short": 257837, "spread": 206578 }, "lev_money": { "long": 111379, "short": 329268, "spread": 39023 }, "other_rept": { "long": 81550, "short": 98448, "spread": 0 }, "tot_rept": { "long_all": 1053478, "short": 1081921 }, "nonrept": { "long_all": 171546, "short_all": 143103 } } }, { "report_date": "2022-09-13T00:00:00.000", "market_and_exchange_names": "ULTRA UST BOND - CHICAGO BOARD OF TRADE", "contract_market_name": "ULTRA UST BOND", "cftc_contract_market_code": "020604", "cftc_market_code": "CBT ", "cftc_region_code": "CHI", "cftc_commodity_code": "020 ", "commodity_name": "T-BONDS", "commodity_group_name": "FINANCIAL INSTRUMENTS", "open_interest": 1376937, "positions": { "dealer": { "long_all": 8384, "short_all": 47242, "spread": 6698 }, "asset_mgr": { "long": 829753, "short": 218898, "spread": 230475 }, "lev_money": { "long": 53169, "short": 708446, "spread": 37455 }, "other_rept": { "long": 62216, "short": 14921, "spread": 0 }, "tot_rept": { "long_all": 1228150, "short": 1264135 }, "nonrept": { "long_all": 148787, "short_all": 112802 } } }, { "report_date": "2022-09-13T00:00:00.000", "market_and_exchange_names": "UST 2Y NOTE - CHICAGO BOARD OF TRADE", "contract_market_name": "UST 2Y NOTE", "cftc_contract_market_code": "042601", "cftc_market_code": "CBT ", "cftc_region_code": "CHI", "cftc_commodity_code": "042 ", "commodity_name": "T-NOTES, 1-2 YEAR", "commodity_group_name": "FINANCIAL INSTRUMENTS", "open_interest": 2008780, "positions": { "dealer": { "long_all": 50855, "short_all": 273099, "spread": 11514 }, "asset_mgr": { "long": 1094819, "short": 447511, "spread": 292382 }, "lev_money": { "long": 171316, "short": 470250, "spread": 84629 }, "other_rept": { "long": 159665, "short": 207795, "spread": 900 }, "tot_rept": { "long_all": 1866080, "short": 1788080 }, "nonrept": { "long_all": 142700, "short_all": 220700 } } } ] } } } } } }, "description": "Successful response." }, "400": { "content": { "application/json": { "schema": { "properties": { "data": {}, "error": { "type": "object" }, "meta": { "type": "object" } }, "type": "object" } } }, "description": "JSON envelope" }, "401": { "description": "Unauthorized. API-key authenticated tiers use an Authorization bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "default": { "summary": "HTTP 401 error", "value": { "ok": false, "error": { "code": "unauthorized", "message": "A valid API key is required for this tier." } } } } } } }, "404": { "content": { "application/json": { "schema": { "properties": { "data": {}, "error": { "type": "object" }, "meta": { "type": "object" } }, "type": "object" } } }, "description": "JSON envelope" }, "405": { "description": "Method not allowed. Source API routes are documented as HTTP GET unless otherwise specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "default": { "summary": "HTTP 405 error", "value": { "ok": false, "error": { "code": "method_not_allowed", "message": "This route does not support the requested HTTP method." } } } } } } }, "429": { "description": "Rate limited. Retry after the limit reset or include the documented contact/API-key headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "default": { "summary": "HTTP 429 error", "value": { "ok": false, "error": { "code": "rate_limited", "message": "Too many requests. Retry after the rate-limit reset." } } } } } } }, "502": { "content": { "application/json": { "schema": { "properties": { "data": {}, "error": { "type": "object" }, "meta": { "type": "object" } }, "type": "object" } } }, "description": "JSON envelope" }, "503": { "description": "Service unavailable. The source API or an upstream dependency is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "default": { "summary": "HTTP 503 error", "value": { "ok": false, "error": { "code": "service_unavailable", "message": "The service is temporarily unavailable." } } } } } } }, "504": { "description": "Upstream timeout. The upstream source did not return within the source API timeout window.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "default": { "summary": "HTTP 504 error", "value": { "ok": false, "error": { "code": "upstream_timeout", "message": "The upstream source timed out." } } } } } } } }, "summary": "Rows", "security": [ {}, { "ContactEmail": [] }, { "BearerAuth": [] }, { "CotfinApiKey": [] } ], "operationId": "cotfin_get_reports_family", "description": "Returns rows with source-native report rows, filters, and metadata fields.", "tags": [ "Reports" ], "x-source-api": "cotfin", "x-source-name": "CFTC", "x-source-upstream": "cftc.gov", "x-docs-example-url": "https://api.cotfin.bluedoor.sh/v1/reports/tff-futures-only?limit=3", "x-docs-example-status": 200, "x-docs-captured-at": "2026-06-07T01:33:19.105Z" } } }, "components": { "securitySchemes": { "ContactEmail": { "type": "apiKey", "in": "header", "name": "X-Cotfin-Contact", "description": "Optional contact email for higher public limits." }, "BearerAuth": { "type": "http", "scheme": "bearer", "description": "API keys are available by emailing sam@bluedoor.sh." }, "CotfinApiKey": { "type": "apiKey", "in": "header", "name": "X-Cotfin-Key", "description": "API keys are available by emailing sam@bluedoor.sh." } }, "schemas": { "ErrorEnvelope": { "type": "object", "additionalProperties": true, "properties": { "ok": { "type": "boolean", "example": false }, "error": { "type": "object", "additionalProperties": true, "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "meta": { "type": "object", "additionalProperties": true } } }, "cotfin_get_product_hierarchyResponse": { "type": "object", "additionalProperties": true, "properties": { "meta": { "type": "object", "additionalProperties": true, "properties": { "product": { "type": "string" }, "source": { "type": "string" }, "endpoint_id": { "type": "string" }, "family": { "type": "string" }, "route": { "type": "string" }, "path_params": { "type": "object", "additionalProperties": true, "properties": {} }, "status": { "type": "string" }, "cache": { "type": "string" }, "identity_tier": { "type": "string" }, "generated_at": { "type": "string" }, "freshness": { "type": "object", "additionalProperties": true, "properties": { "max_age_seconds": { "type": "integer" }, "stale_while_revalidate_seconds": { "type": "integer" }, "stale": { "type": "boolean" } }, "required": [ "max_age_seconds", "stale", "stale_while_revalidate_seconds" ] }, "rate_plan": { "type": "object", "additionalProperties": true, "properties": { "public_request_budget_per_user_rpm": { "type": "integer" } }, "required": [ "public_request_budget_per_user_rpm" ] } }, "required": [ "cache", "endpoint_id", "family", "freshness", "generated_at", "identity_tier", "path_params", "product", "rate_plan", "route", "source", "status" ] }, "data": { "type": "object", "additionalProperties": true, "properties": { "rows": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "contract_market_code": { "type": "string" }, "commodity_name": { "type": "string" }, "commodity_subgroup_name": { "type": "string" }, "commodity_group_name": { "type": "string" } }, "required": [ "commodity_group_name", "commodity_name", "commodity_subgroup_name", "contract_market_code" ] } }, "normalized": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "contract_market_code": { "type": "string" }, "commodity_name": { "type": "string" }, "commodity_subgroup_name": { "type": "string" }, "commodity_group_name": { "type": "string" } }, "required": [ "commodity_group_name", "commodity_name", "commodity_subgroup_name", "contract_market_code" ] } } }, "required": [ "normalized", "rows" ] } }, "required": [ "data", "meta" ] }, "cotfin_get_report_familiesResponse": { "type": "object", "additionalProperties": true, "properties": { "meta": { "type": "object", "additionalProperties": true, "properties": { "product": { "type": "string" }, "source": { "type": "string" }, "route": { "type": "string" } }, "required": [ "product", "route", "source" ] }, "data": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "family": { "type": "string" }, "id": { "type": "string" }, "label": { "type": "string" }, "fields": { "type": "array", "items": { "type": "string" } } }, "required": [ "family", "fields", "id", "label" ] } } }, "required": [ "data", "meta" ] }, "cotfin_get_reports_familyResponse": { "type": "object", "additionalProperties": true, "properties": { "meta": { "type": "object", "additionalProperties": true, "properties": { "product": { "type": "string" }, "source": { "type": "string" }, "endpoint_id": { "type": "string" }, "family": { "type": "string" }, "route": { "type": "string" }, "path_params": { "type": "object", "additionalProperties": true, "properties": { "family": { "type": "string" } }, "required": [ "family" ] }, "status": { "type": "string" }, "cache": { "type": "string" }, "identity_tier": { "type": "string" }, "generated_at": { "type": "string" }, "freshness": { "type": "object", "additionalProperties": true, "properties": { "max_age_seconds": { "type": "integer" }, "stale_while_revalidate_seconds": { "type": "integer" }, "stale": { "type": "boolean" } }, "required": [ "max_age_seconds", "stale", "stale_while_revalidate_seconds" ] }, "rate_plan": { "type": "object", "additionalProperties": true, "properties": { "public_request_budget_per_user_rpm": { "type": "integer" } }, "required": [ "public_request_budget_per_user_rpm" ] } }, "required": [ "cache", "endpoint_id", "family", "freshness", "generated_at", "identity_tier", "path_params", "product", "rate_plan", "route", "source", "status" ] }, "data": { "type": "object", "additionalProperties": true, "properties": { "rows": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string" }, "market_and_exchange_names": { "type": "string" }, "report_date_as_yyyy_mm_dd": { "type": "string" }, "yyyy_report_week_ww": { "type": "string" }, "contract_market_name": { "type": "string" }, "cftc_contract_market_code": { "type": "string" }, "cftc_market_code": { "type": "string" }, "cftc_region_code": { "type": "string" }, "cftc_commodity_code": { "type": "string" }, "commodity_name": { "type": "string" }, "open_interest_all": { "type": "string" }, "dealer_positions_long_all": { "type": "string" }, "dealer_positions_short_all": { "type": "string" }, "dealer_positions_spread_all": { "type": "string" }, "asset_mgr_positions_long": { "type": "string" }, "asset_mgr_positions_short": { "type": "string" }, "asset_mgr_positions_spread": { "type": "string" }, "lev_money_positions_long": { "type": "string" }, "lev_money_positions_short": { "type": "string" }, "lev_money_positions_spread": { "type": "string" }, "other_rept_positions_long": { "type": "string" }, "other_rept_positions_short": { "type": "string" }, "other_rept_positions_spread": { "type": "string" }, "tot_rept_positions_long_all": { "type": "string" }, "tot_rept_positions_short": { "type": "string" }, "nonrept_positions_long_all": { "type": "string" }, "nonrept_positions_short_all": { "type": "string" }, "change_in_open_interest_all": { "type": "string" }, "change_in_dealer_long_all": { "type": "string" }, "change_in_dealer_short_all": { "type": "string" }, "change_in_dealer_spread_all": { "type": "string" }, "change_in_asset_mgr_long": { "type": "string" }, "change_in_asset_mgr_short": { "type": "string" }, "change_in_asset_mgr_spread": { "type": "string" }, "change_in_lev_money_long": { "type": "string" }, "change_in_lev_money_short": { "type": "string" }, "change_in_lev_money_spread": { "type": "string" }, "change_in_other_rept_long": { "type": "string" }, "change_in_other_rept_short": { "type": "string" }, "change_in_other_rept_spread": { "type": "string" }, "change_in_tot_rept_long_all": { "type": "string" }, "change_in_tot_rept_short": { "type": "string" }, "change_in_nonrept_long_all": { "type": "string" }, "change_in_nonrept_short_all": { "type": "string" }, "pct_of_open_interest_all": { "type": "string" }, "pct_of_oi_dealer_long_all": { "type": "string" }, "pct_of_oi_dealer_short_all": { "type": "string" }, "pct_of_oi_dealer_spread_all": { "type": "string" }, "pct_of_oi_asset_mgr_long": { "type": "string" }, "pct_of_oi_asset_mgr_short": { "type": "string" }, "pct_of_oi_asset_mgr_spread": { "type": "string" }, "pct_of_oi_lev_money_long": { "type": "string" }, "pct_of_oi_lev_money_short": { "type": "string" }, "pct_of_oi_lev_money_spread": { "type": "string" }, "pct_of_oi_other_rept_long": { "type": "string" }, "pct_of_oi_other_rept_short": { "type": "string" }, "pct_of_oi_other_rept_spread": { "type": "string" }, "pct_of_oi_tot_rept_long_all": { "type": "string" }, "pct_of_oi_tot_rept_short": { "type": "string" }, "pct_of_oi_nonrept_long_all": { "type": "string" }, "pct_of_oi_nonrept_short_all": { "type": "string" }, "traders_tot_all": { "type": "string" }, "traders_dealer_long_all": { "type": "string" }, "traders_dealer_short_all": { "type": "string" }, "traders_asset_mgr_long_all": { "type": "string" }, "traders_asset_mgr_short_all": { "type": "string" }, "traders_asset_mgr_spread": { "type": "string" }, "traders_lev_money_long_all": { "type": "string" }, "traders_lev_money_short_all": { "type": "string" }, "traders_lev_money_spread": { "type": "string" }, "traders_other_rept_long_all": { "type": "string" }, "traders_other_rept_short": { "type": "string" }, "traders_other_rept_spread": { "type": "string" }, "traders_tot_rept_long_all": { "type": "string" }, "traders_tot_rept_short_all": { "type": "string" }, "conc_gross_le_4_tdr_long": { "type": "string" }, "conc_gross_le_4_tdr_short": { "type": "string" }, "conc_gross_le_8_tdr_long": { "type": "string" }, "conc_gross_le_8_tdr_short": { "type": "string" }, "conc_net_le_4_tdr_long_all": { "type": "string" }, "conc_net_le_4_tdr_short_all": { "type": "string" }, "conc_net_le_8_tdr_long_all": { "type": "string" }, "conc_net_le_8_tdr_short_all": { "type": "string" }, "contract_units": { "type": "string" }, "cftc_subgroup_code": { "type": "string" }, "commodity": { "type": "string" }, "commodity_subgroup_name": { "type": "string" }, "commodity_group_name": { "type": "string" }, "futonly_or_combined": { "type": "string" }, "traders_dealer_spread_all": { "type": "string" } }, "required": [ "asset_mgr_positions_long", "asset_mgr_positions_short", "asset_mgr_positions_spread", "cftc_commodity_code", "cftc_contract_market_code", "cftc_market_code", "cftc_region_code", "cftc_subgroup_code", "change_in_asset_mgr_long", "change_in_asset_mgr_short", "change_in_asset_mgr_spread", "change_in_dealer_long_all", "change_in_dealer_short_all", "change_in_dealer_spread_all", "change_in_lev_money_long", "change_in_lev_money_short", "change_in_lev_money_spread", "change_in_nonrept_long_all", "change_in_nonrept_short_all", "change_in_open_interest_all", "change_in_other_rept_long", "change_in_other_rept_short", "change_in_other_rept_spread", "change_in_tot_rept_long_all", "change_in_tot_rept_short", "commodity", "commodity_group_name", "commodity_name", "commodity_subgroup_name", "conc_gross_le_4_tdr_long", "conc_gross_le_4_tdr_short", "conc_gross_le_8_tdr_long", "conc_gross_le_8_tdr_short", "conc_net_le_4_tdr_long_all", "conc_net_le_4_tdr_short_all", "conc_net_le_8_tdr_long_all", "conc_net_le_8_tdr_short_all", "contract_market_name", "contract_units", "dealer_positions_long_all", "dealer_positions_short_all", "dealer_positions_spread_all", "futonly_or_combined", "id", "lev_money_positions_long", "lev_money_positions_short", "lev_money_positions_spread", "market_and_exchange_names", "nonrept_positions_long_all", "nonrept_positions_short_all", "open_interest_all", "other_rept_positions_long", "other_rept_positions_short", "other_rept_positions_spread", "pct_of_oi_asset_mgr_long", "pct_of_oi_asset_mgr_short", "pct_of_oi_asset_mgr_spread", "pct_of_oi_dealer_long_all", "pct_of_oi_dealer_short_all", "pct_of_oi_dealer_spread_all", "pct_of_oi_lev_money_long", "pct_of_oi_lev_money_short", "pct_of_oi_lev_money_spread", "pct_of_oi_nonrept_long_all", "pct_of_oi_nonrept_short_all", "pct_of_oi_other_rept_long", "pct_of_oi_other_rept_short", "pct_of_oi_other_rept_spread", "pct_of_oi_tot_rept_long_all", "pct_of_oi_tot_rept_short", "pct_of_open_interest_all", "report_date_as_yyyy_mm_dd", "tot_rept_positions_long_all", "tot_rept_positions_short", "traders_asset_mgr_long_all", "traders_asset_mgr_short_all", "traders_asset_mgr_spread", "traders_dealer_long_all", "traders_dealer_short_all", "traders_dealer_spread_all", "traders_lev_money_long_all", "traders_lev_money_short_all", "traders_lev_money_spread", "traders_other_rept_long_all", "traders_other_rept_short", "traders_other_rept_spread", "traders_tot_all", "traders_tot_rept_long_all", "traders_tot_rept_short_all", "yyyy_report_week_ww" ] } }, "normalized": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "report_date": { "type": "string" }, "market_and_exchange_names": { "type": "string" }, "contract_market_name": { "type": "string" }, "cftc_contract_market_code": { "type": "string" }, "cftc_market_code": { "type": "string" }, "cftc_region_code": { "type": "string" }, "cftc_commodity_code": { "type": "string" }, "commodity_name": { "type": "string" }, "commodity_group_name": { "type": "string" }, "open_interest": { "type": "integer" }, "positions": { "type": "object", "additionalProperties": true, "properties": { "dealer": { "type": "object", "additionalProperties": true, "properties": { "long_all": { "type": "integer" }, "short_all": { "type": "integer" }, "spread": { "type": "integer" } }, "required": [ "long_all", "short_all", "spread" ] }, "asset_mgr": { "type": "object", "additionalProperties": true, "properties": { "long": { "type": "integer" }, "short": { "type": "integer" }, "spread": { "type": "integer" } }, "required": [ "long", "short", "spread" ] }, "lev_money": { "type": "object", "additionalProperties": true, "properties": { "long": { "type": "integer" }, "short": { "type": "integer" }, "spread": { "type": "integer" } }, "required": [ "long", "short", "spread" ] }, "other_rept": { "type": "object", "additionalProperties": true, "properties": { "long": { "type": "integer" }, "short": { "type": "integer" }, "spread": { "type": "integer" } }, "required": [ "long", "short", "spread" ] }, "tot_rept": { "type": "object", "additionalProperties": true, "properties": { "long_all": { "type": "integer" }, "short": { "type": "integer" } }, "required": [ "long_all", "short" ] }, "nonrept": { "type": "object", "additionalProperties": true, "properties": { "long_all": { "type": "integer" }, "short_all": { "type": "integer" } }, "required": [ "long_all", "short_all" ] } }, "required": [ "asset_mgr", "dealer", "lev_money", "nonrept", "other_rept", "tot_rept" ] } }, "required": [ "cftc_commodity_code", "cftc_contract_market_code", "cftc_market_code", "cftc_region_code", "commodity_group_name", "commodity_name", "contract_market_name", "market_and_exchange_names", "open_interest", "positions", "report_date" ] } } }, "required": [ "normalized", "rows" ] } }, "required": [ "data", "meta" ] } } }, "x-generated-at": "2026-06-07T01:30:59.456Z", "x-source-api": "cotfin", "x-source-base-url": "https://api.cotfin.bluedoor.sh" }