{"openapi":"3.1.0","info":{"title":"SukuuData (BYOK) API","version":"0.1.0","description":"SukuuData (BYOK) lets an AI assistant read your own SukuuData data through the SukuuData API with a key you supply (SukuuData API key). Read-only: 12 tools (list_schools, search_schools, find_schools_near, get_school, list_secondary_schools, get_secondary_school, list_programmes, get_placement_rules, list_regions, list_districts, get_school_statistics, get_data_quality). The BYOK key travels with...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-sukuudata.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-sukuudata/docs"},"termsOfService":"https://connectorbay.com/byok-sukuudata/terms"},"servers":[{"url":"https://byok-sukuudata.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-sukuudata/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_schools":{"post":{"operationId":"list_schools","summary":"List Ghana schools with filters (region, district, level, type, gender, boarding, status, town, name text) and paging. F","description":"List Ghana schools with filters (region, district, level, type, gender, boarding, status, town, name text) and paging. Filters combine with AND; comma-separated values inside one filter are alternatives. Use for \"Which public junior high schools are in the Ashanti region\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Region name or code to filter by, for example 'ashanti'; comma-separated values are alternatives.","title":"Region"},"district":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"District name or code to filter by; comma-separated values are alternatives.","title":"District"},"level":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"School level, for example PRIMARY, KG, JHS, SHS or TVET; comma-separated values are alternatives.","title":"Level"},"type":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Ownership type, for example Public or Private.","title":"Type"},"school_type":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"School type filter as defined by the provider.","title":"School Type"},"gender":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Student gender intake, for example MIXED, BOYS or GIRLS.","title":"Gender"},"residential":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Boarding arrangement, for example BOARDING, DAY or MIXED.","title":"Residential"},"status":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Record status, for example ACTIVE or NEEDS_REVIEW.","title":"Status"},"town":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Town name.","title":"Town"},"search":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Text to match against school names.","title":"Search"},"has_location":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to return only schools that have coordinates.","title":"Has Location"},"sort":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Sort order as defined by the provider, for example name.","title":"Sort"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Results per page (1 to 100).","title":"Limit"}},"title":"list_schoolsArguments","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_schools":{"post":{"operationId":"search_schools","summary":"Typo-tolerant school name search for pickers, best match first (prefix matches rank first). Use for \"Find the school nam","description":"Typo-tolerant school name search for pickers, best match first (prefix matches rank first). Use for \"Find the school named Achinakrom\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"description":"School name or part of it.","maxLength":100,"title":"Q","type":"string"},"region":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Region name or code to filter by, for example 'ashanti'; comma-separated values are alternatives.","title":"Region"},"level":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"School level, for example PRIMARY, KG, JHS, SHS or TVET; comma-separated values are alternatives.","title":"Level"},"limit":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Maximum results (1 to 50).","title":"Limit"}},"required":["q"],"title":"search_schoolsArguments","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/find_schools_near":{"post":{"operationId":"find_schools_near","summary":"List schools within a radius (kilometres) of a point, nearest first, with the distance. Accepts the same filters as list","description":"List schools within a radius (kilometres) of a point, nearest first, with the distance. Accepts the same filters as list_schools. Use for \"Which schools are within 5 km of latitude 6.66, longitude -1.46\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"lat":{"description":"Latitude in decimal degrees.","title":"Lat","type":"number"},"lng":{"description":"Longitude in decimal degrees.","title":"Lng","type":"number"},"radius":{"anyOf":[{"type":"number"},{"type":"null"}],"default":5,"description":"Search radius in kilometres.","title":"Radius"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Maximum results (1 to 100).","title":"Limit"},"region":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Region name or code to filter by, for example 'ashanti'; comma-separated values are alternatives.","title":"Region"},"district":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"District name or code to filter by; comma-separated values are alternatives.","title":"District"},"level":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"School level, for example PRIMARY, KG, JHS, SHS or TVET; comma-separated values are alternatives.","title":"Level"}},"required":["lat","lng"],"title":"find_schools_nearArguments","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_school":{"post":{"operationId":"get_school","summary":"Get one school by its id (as returned by the list and search tools), including its placement register details when it ha","description":"Get one school by its id (as returned by the list and search tools), including its placement register details when it has any. Use for \"Show the details of school gh-way-785317414\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"school_id":{"description":"School id, for example 'gh-way-785317414'.","maxLength":80,"title":"School Id","type":"string"}},"required":["school_id"],"title":"get_schoolArguments","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_secondary_schools":{"post":{"operationId":"list_secondary_schools","summary":"List senior high, technical and TVET schools of the GES placement register with CSSPS code, category, programmes and day","description":"List senior high, technical and TVET schools of the GES placement register with CSSPS code, category, programmes and day/boarding options. Give lat and lng to filter by distance. Use for \"Which boarding schools in Ashanti offer General Science (programme 502)\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Region name or code to filter by, for example 'ashanti'; comma-separated values are alternatives.","title":"Region"},"district":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"District name or code to filter by; comma-separated values are alternatives.","title":"District"},"search":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Text to match against school names.","title":"Search"},"category":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Placement category, for example A, B, C or PILOT_PRIVATE.","title":"Category"},"institution_type":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Institution type, for example SHS, SHTS or TVET.","title":"Institution Type"},"programme":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Programme code, for example '502' (see list_programmes).","title":"Programme"},"student_gender":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only schools this student can attend, for example FEMALE or MALE.","title":"Student Gender"},"gender":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"School gender intake, for example MIXED, BOYS or GIRLS.","title":"Gender"},"residential":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Boarding arrangement, for example BOARDING or DAY.","title":"Residential"},"lat":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"Latitude of a point to measure distance from (use with lng).","title":"Lat"},"lng":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"Longitude of a point (use with lat).","title":"Lng"},"radius":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"Radius in kilometres around lat/lng (default 25).","title":"Radius"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Results per page (1 to 100).","title":"Limit"}},"title":"list_secondary_schoolsArguments","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_secondary_school":{"post":{"operationId":"get_secondary_school","summary":"Get one placement-register school by its seven-digit CSSPS code. Use for \"Show the placement details of CSSPS school 005","description":"Get one placement-register school by its seven-digit CSSPS code. Use for \"Show the placement details of CSSPS school 0051606\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"cssps_code":{"description":"Seven-digit CSSPS school code, for example '0051606'.","maxLength":10,"title":"Cssps Code","type":"string"}},"required":["cssps_code"],"title":"get_secondary_schoolArguments","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_programmes":{"post":{"operationId":"list_programmes","summary":"List the general programmes and TVET trades offered in senior secondary schools, with their codes and how many schools o","description":"List the general programmes and TVET trades offered in senior secondary schools, with their codes and how many schools offer each. Use for \"Which SHS programmes exist and how many schools offer each\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"kind":{"anyOf":[{"enum":["GENERAL","TVET"],"type":"string"},{"type":"null"}],"default":null,"description":"Programme kind: GENERAL or TVET.","title":"Kind"}},"title":"list_programmesArguments","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_placement_rules":{"post":{"operationId":"get_placement_rules","summary":"Get the 2026 CSSPS school-selection rules as data: number of choices, boarding and day limits, category limits and notes","description":"Get the 2026 CSSPS school-selection rules as data: number of choices, boarding and day limits, category limits and notes. Use for \"What are the rules for choosing schools in the Ghana placement system\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_placement_rulesArguments","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_regions":{"post":{"operationId":"list_regions","summary":"List Ghana's 16 regions with codes and the number of active schools in each. Use for \"How many schools are in each regio","description":"List Ghana's 16 regions with codes and the number of active schools in each. Use for \"How many schools are in each region of Ghana\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_regionsArguments","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_districts":{"post":{"operationId":"list_districts","summary":"List districts with codes and school counts, optionally for one region. Use for \"List the districts in the Ashanti regio","description":"List districts with codes and school counts, optionally for one region. Use for \"List the districts in the Ashanti region\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Region name or code to filter by, for example 'ashanti'; comma-separated values are alternatives.","title":"Region"}},"title":"list_districtsArguments","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_school_statistics":{"post":{"operationId":"get_school_statistics","summary":"Get school totals (public, private, with coordinates, by level, placement schools by category), nationally or for one re","description":"Get school totals (public, private, with coordinates, by level, placement schools by category), nationally or for one region. Use for \"How many schools does Ghana have by level\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Region name or code to filter by, for example 'ashanti'; comma-separated values are alternatives.","title":"Region"}},"title":"get_school_statisticsArguments","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_quality":{"post":{"operationId":"get_data_quality","summary":"Show where the data comes from (sources, licences, last sync) and how complete each field is, so you can judge what to t","description":"Show where the data comes from (sources, licences, last sync) and how complete each field is, so you can judge what to trust. Use for \"How complete and current is the SukuuData school data\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_data_qualityArguments","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}}}}