{"openapi":"3.1.0","info":{"title":"GUS BDL Poland (BYOK) API","version":"0.1.0","description":"GUS BDL Poland (BYOK) lets an AI assistant read your own GUS BDL Poland data through the GUS BDL Poland API with a key you supply (BDL client key (registered user key)). Read-only: 8 tools (list_subjects, search_subjects, list_variables, search_variables, list_territorial_units, search_territorial_units, get_data_by_variable, get_data_by_unit). The BYOK key travels with each request, is used for...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-gusbdl.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-gusbdl/docs"},"termsOfService":"https://connectorbay.com/byok-gusbdl/terms"},"servers":[{"url":"https://byok-gusbdl.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-gusbdl/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_subjects":{"post":{"operationId":"list_subjects","summary":"List statistical subjects (topics) of the Local Data Bank; leave parent_id empty for the top level, or give a subject id","description":"List statistical subjects (topics) of the Local Data Bank; leave parent_id empty for the top level, or give a subject id for its children. Use for \"What are the top-level statistical topics in the Polish Local Data Bank\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"parent_id":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Parent subject id such as 'K3' or 'G186'; leave out for the top level.","title":"Parent Id"},"page":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Page index, starting at 0.","title":"Page"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Rows per page (1 to 100).","title":"Page Size"},"lang":{"anyOf":[{"enum":["pl","en"],"type":"string"},{"type":"null"}],"default":"en","description":"Language of names and descriptions: pl or en.","title":"Lang"},"format":{"anyOf":[{"const":"json","type":"string"},{"type":"null"}],"default":"json","description":"Response format; json is the only one this connector accepts.","title":"Format"}},"title":"list_subjectsArguments","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/search_subjects":{"post":{"operationId":"search_subjects","summary":"Search statistical subjects by a fragment of the name. Use for \"Find BDL subjects about cars (samochody)\".","description":"Search statistical subjects by a fragment of the name. Use for \"Find BDL subjects about cars (samochody)\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"description":"Name fragment to search for, for example 'samochody' or 'population'.","maxLength":100,"title":"Name","type":"string"},"page":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Page index, starting at 0.","title":"Page"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Rows per page (1 to 100).","title":"Page Size"},"lang":{"anyOf":[{"enum":["pl","en"],"type":"string"},{"type":"null"}],"default":"en","description":"Language of names and descriptions: pl or en.","title":"Lang"},"format":{"anyOf":[{"const":"json","type":"string"},{"type":"null"}],"default":"json","description":"Response format; json is the only one this connector accepts.","title":"Format"}},"required":["name"],"title":"search_subjectsArguments","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_variables":{"post":{"operationId":"list_variables","summary":"List statistical variables of a subject, optionally limited to one level and one year; returns variable ids used by the ","description":"List statistical variables of a subject, optionally limited to one level and one year; returns variable ids used by the data tools. Use for \"Which variables exist under subject P2137\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"subject_id":{"description":"Subject id whose variables to list, for example 'P2137' (a subject with hasVariables true).","maxLength":20,"title":"Subject Id","type":"string"},"level":{"anyOf":[{"maximum":7,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Territorial unit level: 0 Poland, 1 macroregion, 2 voivodeship, 3 region, 4 subregion, 5 county, 6 commune.","title":"Level"},"year":{"anyOf":[{"maximum":2100,"minimum":1990,"type":"integer"},{"type":"null"}],"default":null,"description":"Only variables available in this year.","title":"Year"},"page":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Page index, starting at 0.","title":"Page"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Rows per page (1 to 100).","title":"Page Size"},"lang":{"anyOf":[{"enum":["pl","en"],"type":"string"},{"type":"null"}],"default":"en","description":"Language of names and descriptions: pl or en.","title":"Lang"},"format":{"anyOf":[{"const":"json","type":"string"},{"type":"null"}],"default":"json","description":"Response format; json is the only one this connector accepts.","title":"Format"}},"required":["subject_id"],"title":"list_variablesArguments","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/search_variables":{"post":{"operationId":"search_variables","summary":"Search statistical variables by text in their dimension names, for example 'samochody'. Use for \"Find BDL variables ment","description":"Search statistical variables by text in their dimension names, for example 'samochody'. Use for \"Find BDL variables mentioning cars\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"description":"Text to search in the variable dimension names.","maxLength":100,"title":"Name","type":"string"},"subject_id":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Optional parent subject id to search within.","title":"Subject Id"},"level":{"anyOf":[{"maximum":7,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Territorial unit level 0 to 7 (0 Poland, 2 voivodeship, 5 county, 6 commune).","title":"Level"},"page":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Page index, starting at 0.","title":"Page"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Rows per page (1 to 100).","title":"Page Size"},"lang":{"anyOf":[{"enum":["pl","en"],"type":"string"},{"type":"null"}],"default":"en","description":"Language of names and descriptions: pl or en.","title":"Lang"},"format":{"anyOf":[{"const":"json","type":"string"},{"type":"null"}],"default":"json","description":"Response format; json is the only one this connector accepts.","title":"Format"}},"required":["name"],"title":"search_variablesArguments","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_territorial_units":{"post":{"operationId":"list_territorial_units","summary":"List territorial units (Poland, regions, voivodeships, counties, communes), optionally for a parent unit and level. Use ","description":"List territorial units (Poland, regions, voivodeships, counties, communes), optionally for a parent unit and level. Use for \"List the voivodeships (level 2) of Poland\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"level":{"anyOf":[{"maximum":6,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Unit level: 0 Poland, 1 macroregion, 2 voivodeship, 3 region, 4 subregion, 5 county, 6 commune.","title":"Level"},"parent_id":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Parent unit id (12 digits), for example '011200000000'.","title":"Parent Id"},"page":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Page index, starting at 0.","title":"Page"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Rows per page (1 to 100).","title":"Page Size"},"lang":{"anyOf":[{"enum":["pl","en"],"type":"string"},{"type":"null"}],"default":"en","description":"Language of names and descriptions: pl or en.","title":"Lang"},"format":{"anyOf":[{"const":"json","type":"string"},{"type":"null"}],"default":"json","description":"Response format; json is the only one this connector accepts.","title":"Format"}},"title":"list_territorial_unitsArguments","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/search_territorial_units":{"post":{"operationId":"search_territorial_units","summary":"Search territorial units by name fragment, optionally for one level. Use for \"Find the unit named Krakow\".","description":"Search territorial units by name fragment, optionally for one level. Use for \"Find the unit named Krakow\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"description":"Unit name fragment, for example 'Krakow'.","maxLength":100,"title":"Name","type":"string"},"level":{"anyOf":[{"maximum":6,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Unit level 0 to 6.","title":"Level"},"page":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Page index, starting at 0.","title":"Page"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Rows per page (1 to 100).","title":"Page Size"},"lang":{"anyOf":[{"enum":["pl","en"],"type":"string"},{"type":"null"}],"default":"en","description":"Language of names and descriptions: pl or en.","title":"Lang"},"format":{"anyOf":[{"const":"json","type":"string"},{"type":"null"}],"default":"json","description":"Response format; json is the only one this connector accepts.","title":"Format"}},"required":["name"],"title":"search_territorial_unitsArguments","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_data_by_variable":{"post":{"operationId":"get_data_by_variable","summary":"Get the values of one statistical variable for many territorial units (filtered by level, parent unit and one year), pag","description":"Get the values of one statistical variable for many territorial units (filtered by level, parent unit and one year), paged. Use for \"What are the values of variable 3643 for all voivodeships in 2010\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"variable_id":{"description":"Variable id from list_variables or search_variables, for example 3643.","title":"Variable Id","type":"integer"},"year":{"anyOf":[{"maximum":2100,"minimum":1990,"type":"integer"},{"type":"null"}],"default":null,"description":"Single year to return; leave out for all available years.","title":"Year"},"unit_level":{"anyOf":[{"maximum":6,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Territorial unit level to include (2 voivodeship, 5 county, 6 commune, and so on).","title":"Unit Level"},"unit_parent_id":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Only units under this parent unit id.","title":"Unit Parent Id"},"page":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Page index, starting at 0.","title":"Page"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Rows per page (1 to 100).","title":"Page Size"},"lang":{"anyOf":[{"enum":["pl","en"],"type":"string"},{"type":"null"}],"default":"en","description":"Language of names and descriptions: pl or en.","title":"Lang"},"format":{"anyOf":[{"const":"json","type":"string"},{"type":"null"}],"default":"json","description":"Response format; json is the only one this connector accepts.","title":"Format"}},"required":["variable_id"],"title":"get_data_by_variableArguments","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_data_by_unit":{"post":{"operationId":"get_data_by_unit","summary":"Get the values of one statistical variable for one territorial unit, optionally for a single year. Use for \"What is vari","description":"Get the values of one statistical variable for one territorial unit, optionally for a single year. Use for \"What is variable 3643 for unit 023200000000 in 2005\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"unit_id":{"description":"Territorial unit id (12 digits), for example '023200000000'.","maxLength":200,"title":"Unit Id","type":"string"},"variable_id":{"description":"Variable id, for example 3643.","minimum":1,"title":"Variable Id","type":"integer"},"year":{"anyOf":[{"maximum":2100,"minimum":1990,"type":"integer"},{"type":"null"}],"default":null,"description":"Single year to return; leave out for all available years.","title":"Year"},"page":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Page index, starting at 0.","title":"Page"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Rows per page (1 to 100).","title":"Page Size"},"lang":{"anyOf":[{"enum":["pl","en"],"type":"string"},{"type":"null"}],"default":"en","description":"Language of names and descriptions: pl or en.","title":"Lang"},"format":{"anyOf":[{"const":"json","type":"string"},{"type":"null"}],"default":"json","description":"Response format; json is the only one this connector accepts.","title":"Format"}},"required":["unit_id","variable_id"],"title":"get_data_by_unitArguments","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}}}}