{"openapi":"3.1.0","info":{"title":"IPUMS (BYOK) API","version":"0.1.0","description":"IPUMS (BYOK) lets an AI assistant read your own IPUMS data through the IPUMS API with a key you supply (IPUMS API key). Read-only: 9 tools (list_nhgis_datasets, get_nhgis_dataset, list_nhgis_data_tables, get_nhgis_data_table, list_nhgis_time_series_tables, get_nhgis_time_series_table, list_nhgis_shapefiles, list_extracts, get_extract). The BYOK key travels with each request, is used for that one...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-ipums.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-ipums/docs"},"termsOfService":"https://connectorbay.com/byok-ipums/terms"},"servers":[{"url":"https://byok-ipums.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-ipums/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/list_nhgis_datasets":{"post":{"operationId":"list_nhgis_datasets","summary":"List NHGIS datasets (census and survey table collections) with name, description, group and sequence. Use for \"Which NHG","description":"List NHGIS datasets (census and survey table collections) with name, description, group and sequence. Use for \"Which NHGIS datasets exist for the 2010 census\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"collection":{"anyOf":[{"const":"nhgis","type":"string"},{"type":"null"}],"default":"nhgis","description":"IPUMS data collection; this connector reads NHGIS metadata.","title":"Collection"},"version":{"anyOf":[{"const":"2","type":"string"},{"type":"null"}],"default":"2","description":"IPUMS API version; use 2.","title":"Version"},"page_number":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page Number"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Records per page (1 to 100).","title":"Page Size"}},"title":"list_nhgis_datasetsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_nhgis_dataset":{"post":{"operationId":"get_nhgis_dataset","summary":"Get one NHGIS dataset with its data tables and geographic levels. Use for \"What tables and geographic levels does NHGIS ","description":"Get one NHGIS dataset with its data tables and geographic levels. Use for \"What tables and geographic levels does NHGIS dataset 2010_SF1a have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"dataset":{"description":"NHGIS dataset name, for example '2010_SF1a' or '1790_cPop'.","maxLength":80,"title":"Dataset","type":"string"},"collection":{"anyOf":[{"const":"nhgis","type":"string"},{"type":"null"}],"default":"nhgis","description":"IPUMS data collection; this connector reads NHGIS metadata.","title":"Collection"},"version":{"anyOf":[{"const":"2","type":"string"},{"type":"null"}],"default":"2","description":"IPUMS API version; use 2.","title":"Version"}},"required":["dataset"],"title":"get_nhgis_datasetArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_nhgis_data_tables":{"post":{"operationId":"list_nhgis_data_tables","summary":"List NHGIS data tables across datasets with name, NHGIS code, description, universe and dataset. Use for \"Which NHGIS da","description":"List NHGIS data tables across datasets with name, NHGIS code, description, universe and dataset. Use for \"Which NHGIS data tables cover total population\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"collection":{"anyOf":[{"const":"nhgis","type":"string"},{"type":"null"}],"default":"nhgis","description":"IPUMS data collection; this connector reads NHGIS metadata.","title":"Collection"},"version":{"anyOf":[{"const":"2","type":"string"},{"type":"null"}],"default":"2","description":"IPUMS API version; use 2.","title":"Version"},"page_number":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page Number"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Records per page (1 to 100).","title":"Page Size"}},"title":"list_nhgis_data_tablesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_nhgis_data_table":{"post":{"operationId":"get_nhgis_data_table","summary":"Get one NHGIS data table with its universe and variables. Use for \"Which variables are in NHGIS table NT1 of dataset 179","description":"Get one NHGIS data table with its universe and variables. Use for \"Which variables are in NHGIS table NT1 of dataset 1790_cPop\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"dataset":{"description":"NHGIS dataset name, for example '1790_cPop'.","maxLength":80,"title":"Dataset","type":"string"},"data_table":{"description":"Data table name within the dataset, for example 'NT1'.","maxLength":40,"title":"Data Table","type":"string"},"collection":{"anyOf":[{"const":"nhgis","type":"string"},{"type":"null"}],"default":"nhgis","description":"IPUMS data collection; this connector reads NHGIS metadata.","title":"Collection"},"version":{"anyOf":[{"const":"2","type":"string"},{"type":"null"}],"default":"2","description":"IPUMS API version; use 2.","title":"Version"}},"required":["dataset","data_table"],"title":"get_nhgis_data_tableArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_nhgis_time_series_tables":{"post":{"operationId":"list_nhgis_time_series_tables","summary":"List NHGIS time series tables with name, description, geographic integration and geographic levels. Use for \"Which NHGIS","description":"List NHGIS time series tables with name, description, geographic integration and geographic levels. Use for \"Which NHGIS time series tables cover total population over many censuses\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"collection":{"anyOf":[{"const":"nhgis","type":"string"},{"type":"null"}],"default":"nhgis","description":"IPUMS data collection; this connector reads NHGIS metadata.","title":"Collection"},"version":{"anyOf":[{"const":"2","type":"string"},{"type":"null"}],"default":"2","description":"IPUMS API version; use 2.","title":"Version"},"page_number":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page Number"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Records per page (1 to 100).","title":"Page Size"}},"title":"list_nhgis_time_series_tablesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_nhgis_time_series_table":{"post":{"operationId":"get_nhgis_time_series_table","summary":"Get one NHGIS time series table with its series and geographic levels. Use for \"Describe NHGIS time series table A00\".","description":"Get one NHGIS time series table with its series and geographic levels. Use for \"Describe NHGIS time series table A00\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"time_series_table":{"description":"Time series table name, for example 'A00'.","maxLength":40,"title":"Time Series Table","type":"string"},"collection":{"anyOf":[{"const":"nhgis","type":"string"},{"type":"null"}],"default":"nhgis","description":"IPUMS data collection; this connector reads NHGIS metadata.","title":"Collection"},"version":{"anyOf":[{"const":"2","type":"string"},{"type":"null"}],"default":"2","description":"IPUMS API version; use 2.","title":"Version"}},"required":["time_series_table"],"title":"get_nhgis_time_series_tableArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_nhgis_shapefiles":{"post":{"operationId":"list_nhgis_shapefiles","summary":"List NHGIS boundary shapefiles with name, year, geographic level and extent. Use for \"Which NHGIS shapefiles exist for U","description":"List NHGIS boundary shapefiles with name, year, geographic level and extent. Use for \"Which NHGIS shapefiles exist for US states\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"collection":{"anyOf":[{"const":"nhgis","type":"string"},{"type":"null"}],"default":"nhgis","description":"IPUMS data collection; this connector reads NHGIS metadata.","title":"Collection"},"version":{"anyOf":[{"const":"2","type":"string"},{"type":"null"}],"default":"2","description":"IPUMS API version; use 2.","title":"Version"},"page_number":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page Number"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Records per page (1 to 100).","title":"Page Size"}},"title":"list_nhgis_shapefilesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_extracts":{"post":{"operationId":"list_extracts","summary":"List your recent IPUMS data extracts for one collection with status, definition and download links. Use for \"What are my","description":"List your recent IPUMS data extracts for one collection with status, definition and download links. Use for \"What are my recent IPUMS NHGIS extracts and have they finished\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"collection":{"description":"IPUMS collection code: nhgis, usa, cps, ipumsi, dhs, atus, ahtus, mtus, meps, nhis or ihgis.","maxLength":20,"title":"Collection","type":"string"},"version":{"anyOf":[{"const":"2","type":"string"},{"type":"null"}],"default":"2","description":"IPUMS API version; use 2.","title":"Version"},"page_number":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page Number"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Records per page (1 to 100).","title":"Page Size"}},"required":["collection"],"title":"list_extractsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_extract":{"post":{"operationId":"get_extract","summary":"Get one of your IPUMS data extracts by number: status, what it contains and where to download it. Use for \"Is IPUMS NHGI","description":"Get one of your IPUMS data extracts by number: status, what it contains and where to download it. Use for \"Is IPUMS NHGIS extract number 2 ready to download\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"extract_number":{"description":"Extract number, for example 2.","title":"Extract Number","type":"integer"},"collection":{"description":"IPUMS collection code: nhgis, usa, cps, ipumsi, dhs, atus, ahtus, mtus, meps, nhis or ihgis.","maxLength":20,"title":"Collection","type":"string"},"version":{"anyOf":[{"const":"2","type":"string"},{"type":"null"}],"default":"2","description":"IPUMS API version; use 2.","title":"Version"}},"required":["extract_number","collection"],"title":"get_extractArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}