{"openapi":"3.1.0","info":{"title":"SchoolDigger (BYOK) API","version":"0.1.0","description":"SchoolDigger (BYOK) lets an AI assistant read your own SchoolDigger data through the SchoolDigger API with a key you supply (SchoolDigger appID). Read-only: 8 tools (autocomplete_schools, autocomplete_districts, search_schools, get_school, get_school_rankings, search_districts, get_district, get_district_rankings). The BYOK key travels with each request, is used for that one call only and is...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-schooldigger.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-schooldigger/docs"},"termsOfService":"https://connectorbay.com/byok-schooldigger/terms"},"servers":[{"url":"https://byok-schooldigger.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-schooldigger/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/autocomplete_schools":{"post":{"operationId":"autocomplete_schools","summary":"Quickly find schools whose name starts with typed text, for picking a school id. Some fields need a paid plan. The free ","description":"Quickly find schools whose name starts with typed text, for picking a school id. Some fields need a paid plan. The free test plan allows few calls per day. Use for \"Find schools named Lincoln in Washington state\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"description":"Text typed so far, for example 'Lincol'.","maxLength":100,"title":"Q","type":"string"},"st":{"anyOf":[{"maxLength":2,"type":"string"},{"type":"null"}],"default":null,"description":"Two-letter US state code, for example 'CA'.","title":"St"},"level":{"anyOf":[{"enum":["Elementary","Middle","High","Alt","Private"],"type":"string"},{"type":"null"}],"default":null,"description":"Only schools of this level.","title":"Level"},"return_count":{"anyOf":[{"maximum":20,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Number of matches (1 to 20).","title":"Return Count"}},"required":["q"],"title":"autocomplete_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/autocomplete_districts":{"post":{"operationId":"autocomplete_districts","summary":"Quickly find school districts whose name starts with typed text, for picking a district id. Use for \"Find districts that","description":"Quickly find school districts whose name starts with typed text, for picking a district id. Use for \"Find districts that start with 'Spring'\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"description":"Text typed so far, for example 'Lincol'.","maxLength":100,"title":"Q","type":"string"},"st":{"anyOf":[{"maxLength":2,"type":"string"},{"type":"null"}],"default":null,"description":"Two-letter US state code, for example 'CA'.","title":"St"},"return_count":{"anyOf":[{"maximum":20,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Number of matches (1 to 20).","title":"Return Count"}},"required":["q"],"title":"autocomplete_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/search_schools":{"post":{"operationId":"search_schools","summary":"Search US public and private schools by state, name or city, district, level, city, ZIP or school type (magnet, charter,","description":"Search US public and private schools by state, name or city, district, level, city, ZIP or school type (magnet, charter, virtual, Title I). Location filters need a paid plan. Use for \"List charter high schools in Austin, Texas\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"st":{"anyOf":[{"maxLength":2,"type":"string"},{"type":"null"}],"default":null,"description":"Two-letter US state code, for example 'CA'.","title":"St"},"q":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Words matched against school name or city.","title":"Q"},"district_id":{"anyOf":[{"maxLength":7,"type":"string"},{"type":"null"}],"default":null,"description":"7-digit district id to list that district's schools.","title":"District Id"},"level":{"anyOf":[{"enum":["Elementary","Middle","High","Alt","Public","Private"],"type":"string"},{"type":"null"}],"default":null,"description":"School level.","title":"Level"},"city":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"City name.","title":"City"},"zip":{"anyOf":[{"maxLength":5,"type":"string"},{"type":"null"}],"default":null,"description":"5-digit ZIP code.","title":"Zip"},"is_charter":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for charter schools only, false to exclude them (paid plans).","title":"Is Charter"},"is_magnet":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for magnet schools only, false to exclude them (paid plans).","title":"Is Magnet"},"sort_by":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":"schoolname","description":"Order: schoolname, distance or rank; prefix '-' for descending, for example '-rank'.","title":"Sort By"},"page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"per_page":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Results per page (1 to 50).","title":"Per Page"}},"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/get_school":{"post":{"operationId":"get_school","summary":"Get one school's profile by its 12-digit SchoolDigger id: contact details, grades, type, district, rank history and year","description":"Get one school's profile by its 12-digit SchoolDigger id: contact details, grades, type, district, rank history and yearly enrollment details. Use for \"Show details for school 530966001632\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"12-digit SchoolDigger school id from search_schools, for example '530966001632'.","maxLength":200,"title":"Id","type":"string"}},"required":["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/get_school_rankings":{"post":{"operationId":"get_school_rankings","summary":"List the SchoolDigger rankings of a state's schools for a year, best first, with stars and rank history. Use for \"Which ","description":"List the SchoolDigger rankings of a state's schools for a year, best first, with stars and rank history. Use for \"Which are the top-ranked elementary schools in Massachusetts\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"st":{"description":"Two-letter US state code, for example 'MA'.","maxLength":200,"title":"St","type":"string"},"level":{"anyOf":[{"enum":["Elementary","Middle","High"],"type":"string"},{"type":"null"}],"default":null,"description":"Ranking level.","title":"Level"},"year":{"anyOf":[{"maximum":2100,"minimum":2000,"type":"integer"},{"type":"null"}],"default":null,"description":"Ranking year, for example 2025 for 2024-25; latest if omitted.","title":"Year"},"page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"per_page":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Results per page (1 to 50).","title":"Per Page"}},"required":["st"],"title":"get_school_rankingsArguments","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_districts":{"post":{"operationId":"search_districts","summary":"Search US school districts by state, name or city, or ZIP. Location filters need a paid plan. Use for \"Which school dist","description":"Search US school districts by state, name or city, or ZIP. Location filters need a paid plan. Use for \"Which school districts are in ZIP 02139\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"st":{"anyOf":[{"maxLength":2,"type":"string"},{"type":"null"}],"default":null,"description":"Two-letter US state code, for example 'CA'.","title":"St"},"q":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Words matched against district name or city.","title":"Q"},"city":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"City name.","title":"City"},"zip":{"anyOf":[{"maxLength":5,"type":"string"},{"type":"null"}],"default":null,"description":"5-digit ZIP code.","title":"Zip"},"sort_by":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":"districtname","description":"Order: districtname, distance or rank; prefix '-' for descending.","title":"Sort By"},"page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"per_page":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Results per page (1 to 50).","title":"Per Page"}},"title":"search_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_district":{"post":{"operationId":"get_district","summary":"Get one district's profile by its 7-digit SchoolDigger id: contact details, grade span, school counts, rank history and ","description":"Get one district's profile by its 7-digit SchoolDigger id: contact details, grade span, school counts, rank history and yearly details. Use for \"Give me details of district 5309660\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"7-digit SchoolDigger district id from search_districts, for example '5309660'.","maxLength":200,"title":"Id","type":"string"}},"required":["id"],"title":"get_districtArguments","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_district_rankings":{"post":{"operationId":"get_district_rankings","summary":"List the SchoolDigger rankings of a state's districts for a year, best first. Use for \"Which school districts rank best ","description":"List the SchoolDigger rankings of a state's districts for a year, best first. Use for \"Which school districts rank best in New Jersey\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"st":{"description":"Two-letter US state code, for example 'NJ'.","maxLength":200,"title":"St","type":"string"},"year":{"anyOf":[{"maximum":2100,"minimum":2000,"type":"integer"},{"type":"null"}],"default":null,"description":"Ranking year, for example 2025 for 2024-25; latest if omitted.","title":"Year"},"page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"per_page":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Results per page (1 to 50).","title":"Per Page"}},"required":["st"],"title":"get_district_rankingsArguments","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}}}}