{"openapi":"3.1.0","info":{"title":"College Scorecard (BYOK) API","version":"0.1.0","description":"College Scorecard (BYOK) lets an AI assistant read your own College Scorecard data through the College Scorecard API with a key you supply (api.data.gov API key). Read-only: 7 tools (search_schools_by_name, list_schools_in_state, get_school, find_schools_near_zip, list_schools_by_degree_level, list_schools_by_ownership, list_schools_by_region). 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-collegescorecard.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-collegescorecard/docs"},"termsOfService":"https://connectorbay.com/byok-collegescorecard/terms"},"servers":[{"url":"https://byok-collegescorecard.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-collegescorecard/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/search_schools_by_name":{"post":{"operationId":"search_schools_by_name","summary":"Search US institutions by words in their name (each word at least 3 letters). Institution-level statistics only, no stud","description":"Search US institutions by words in their name (each word at least 3 letters). Institution-level statistics only, no student records. Use for \"Find colleges with 'Boston' and 'University' in the name\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"description":"Words to find in the institution name, for example 'Boston University'.","maxLength":100,"title":"Name","type":"string"},"fields":{"anyOf":[{"maxLength":600,"type":"string"},{"type":"null"}],"default":"id,school.name,school.city,school.state,school.ownership,school.school_url,latest.student.size,latest.admissions.admission_rate.overall,latest.cost.tuition.in_state,latest.cost.tuition.out_of_state","description":"Comma-separated field names to return, from the College Scorecard data dictionary, for example 'id,school.name,latest.student.size' ('latest' is the most recent year; 'latest' alone returns every latest value and is large). A short list keeps answers small.","title":"Fields"},"sort":{"anyOf":[{"maxLength":120,"type":"string"},{"type":"null"}],"default":null,"description":"Optional sort, a numeric or name field with optional ':asc' or ':desc', for example 'latest.student.size:desc'.","title":"Sort"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Schools per page (1 to 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Page number, starting at 0.","title":"Page"}},"required":["name"],"title":"search_schools_by_nameArguments","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_schools_in_state":{"post":{"operationId":"list_schools_in_state","summary":"List institutions in one US state or territory (two-letter postcode), for example the largest ones by adding sort=latest","description":"List institutions in one US state or territory (two-letter postcode), for example the largest ones by adding sort=latest.student.size:desc. Use for \"What are the biggest colleges in Ohio\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"description":"Two-letter state postcode, for example 'OH'.","maxLength":2,"title":"State","type":"string"},"fields":{"anyOf":[{"maxLength":600,"type":"string"},{"type":"null"}],"default":"id,school.name,school.city,school.state,school.ownership,school.school_url,latest.student.size,latest.admissions.admission_rate.overall,latest.cost.tuition.in_state,latest.cost.tuition.out_of_state","description":"Comma-separated field names to return, from the College Scorecard data dictionary, for example 'id,school.name,latest.student.size' ('latest' is the most recent year; 'latest' alone returns every latest value and is large). A short list keeps answers small.","title":"Fields"},"sort":{"anyOf":[{"maxLength":120,"type":"string"},{"type":"null"}],"default":null,"description":"Optional sort, a numeric or name field with optional ':asc' or ':desc', for example 'latest.student.size:desc'.","title":"Sort"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Schools per page (1 to 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Page number, starting at 0.","title":"Page"}},"required":["state"],"title":"list_schools_in_stateArguments","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 institution by its IPEDS unit id (the 'id' field), with the fields requested. Use for \"Show tuition and size for","description":"Get one institution by its IPEDS unit id (the 'id' field), with the fields requested. Use for \"Show tuition and size for the school with id 190752\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"IPEDS unit id of the institution, for example 190752.","minimum":1,"title":"Id","type":"integer"},"fields":{"anyOf":[{"maxLength":600,"type":"string"},{"type":"null"}],"default":"id,school.name,school.city,school.state,school.ownership,school.school_url,latest.student.size,latest.admissions.admission_rate.overall,latest.cost.tuition.in_state,latest.cost.tuition.out_of_state","description":"Comma-separated field names to return, from the College Scorecard data dictionary, for example 'id,school.name,latest.student.size' ('latest' is the most recent year; 'latest' alone returns every latest value and is large). A short list keeps answers small.","title":"Fields"},"sort":{"anyOf":[{"maxLength":120,"type":"string"},{"type":"null"}],"default":null,"description":"Optional sort, a numeric or name field with optional ':asc' or ':desc', for example 'latest.student.size:desc'.","title":"Sort"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Schools per page (1 to 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Page number, starting at 0.","title":"Page"}},"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/find_schools_near_zip":{"post":{"operationId":"find_schools_near_zip","summary":"Find institutions within a distance of a US ZIP code. Use for \"Which colleges are within 10 miles of ZIP 02139\".","description":"Find institutions within a distance of a US ZIP code. Use for \"Which colleges are within 10 miles of ZIP 02139\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"zip":{"description":"5-digit US ZIP code, for example '02139'.","maxLength":10,"title":"Zip","type":"string"},"distance":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":"10mi","description":"Radius with unit, for example '10mi' or '25km'; a bare number means miles.","title":"Distance"},"fields":{"anyOf":[{"maxLength":600,"type":"string"},{"type":"null"}],"default":"id,school.name,school.city,school.state,school.ownership,school.school_url,latest.student.size,latest.admissions.admission_rate.overall,latest.cost.tuition.in_state,latest.cost.tuition.out_of_state","description":"Comma-separated field names to return, from the College Scorecard data dictionary, for example 'id,school.name,latest.student.size' ('latest' is the most recent year; 'latest' alone returns every latest value and is large). A short list keeps answers small.","title":"Fields"},"sort":{"anyOf":[{"maxLength":120,"type":"string"},{"type":"null"}],"default":null,"description":"Optional sort, a numeric or name field with optional ':asc' or ':desc', for example 'latest.student.size:desc'.","title":"Sort"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Schools per page (1 to 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Page number, starting at 0.","title":"Page"}},"required":["zip"],"title":"find_schools_near_zipArguments","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_schools_by_degree_level":{"post":{"operationId":"list_schools_by_degree_level","summary":"List institutions by predominant undergraduate degree: 1 certificate, 2 associate, 3 bachelor's, 4 graduate only. Use fo","description":"List institutions by predominant undergraduate degree: 1 certificate, 2 associate, 3 bachelor's, 4 graduate only. Use for \"Which colleges mainly award associate degrees in California\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"predominant_degree":{"description":"Predominant degree code: 1 certificate, 2 associate, 3 bachelor's, 4 entirely graduate.","maximum":4,"minimum":0,"title":"Predominant Degree","type":"integer"},"state":{"anyOf":[{"maxLength":2,"type":"string"},{"type":"null"}],"default":null,"description":"Optional two-letter state postcode to narrow the list.","title":"State"},"fields":{"anyOf":[{"maxLength":600,"type":"string"},{"type":"null"}],"default":"id,school.name,school.city,school.state,school.ownership,school.school_url,latest.student.size,latest.admissions.admission_rate.overall,latest.cost.tuition.in_state,latest.cost.tuition.out_of_state","description":"Comma-separated field names to return, from the College Scorecard data dictionary, for example 'id,school.name,latest.student.size' ('latest' is the most recent year; 'latest' alone returns every latest value and is large). A short list keeps answers small.","title":"Fields"},"sort":{"anyOf":[{"maxLength":120,"type":"string"},{"type":"null"}],"default":null,"description":"Optional sort, a numeric or name field with optional ':asc' or ':desc', for example 'latest.student.size:desc'.","title":"Sort"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Schools per page (1 to 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Page number, starting at 0.","title":"Page"}},"required":["predominant_degree"],"title":"list_schools_by_degree_levelArguments","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_schools_by_ownership":{"post":{"operationId":"list_schools_by_ownership","summary":"List institutions by control type: 1 public, 2 private nonprofit, 3 private for-profit, optionally in one state. Use for","description":"List institutions by control type: 1 public, 2 private nonprofit, 3 private for-profit, optionally in one state. Use for \"List private nonprofit colleges in Massachusetts\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"ownership":{"description":"Control code: 1 public, 2 private nonprofit, 3 private for-profit.","maximum":3,"minimum":1,"title":"Ownership","type":"integer"},"state":{"anyOf":[{"maxLength":2,"type":"string"},{"type":"null"}],"default":null,"description":"Optional two-letter state postcode to narrow the list.","title":"State"},"fields":{"anyOf":[{"maxLength":600,"type":"string"},{"type":"null"}],"default":"id,school.name,school.city,school.state,school.ownership,school.school_url,latest.student.size,latest.admissions.admission_rate.overall,latest.cost.tuition.in_state,latest.cost.tuition.out_of_state","description":"Comma-separated field names to return, from the College Scorecard data dictionary, for example 'id,school.name,latest.student.size' ('latest' is the most recent year; 'latest' alone returns every latest value and is large). A short list keeps answers small.","title":"Fields"},"sort":{"anyOf":[{"maxLength":120,"type":"string"},{"type":"null"}],"default":null,"description":"Optional sort, a numeric or name field with optional ':asc' or ':desc', for example 'latest.student.size:desc'.","title":"Sort"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Schools per page (1 to 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Page number, starting at 0.","title":"Page"}},"required":["ownership"],"title":"list_schools_by_ownershipArguments","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_schools_by_region":{"post":{"operationId":"list_schools_by_region","summary":"List institutions in one IPEDS region (0 service schools, 1 New England, 2 Mid East, 3 Great Lakes, 4 Plains, 5 Southeas","description":"List institutions in one IPEDS region (0 service schools, 1 New England, 2 Mid East, 3 Great Lakes, 4 Plains, 5 Southeast, 6 Southwest, 7 Rocky Mountains, 8 Far West, 9 outlying areas). Use for \"Show colleges in the Rocky Mountains region\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region_id":{"description":"IPEDS region code 0 to 9.","maximum":9,"minimum":0,"title":"Region Id","type":"integer"},"fields":{"anyOf":[{"maxLength":600,"type":"string"},{"type":"null"}],"default":"id,school.name,school.city,school.state,school.ownership,school.school_url,latest.student.size,latest.admissions.admission_rate.overall,latest.cost.tuition.in_state,latest.cost.tuition.out_of_state","description":"Comma-separated field names to return, from the College Scorecard data dictionary, for example 'id,school.name,latest.student.size' ('latest' is the most recent year; 'latest' alone returns every latest value and is large). A short list keeps answers small.","title":"Fields"},"sort":{"anyOf":[{"maxLength":120,"type":"string"},{"type":"null"}],"default":null,"description":"Optional sort, a numeric or name field with optional ':asc' or ':desc', for example 'latest.student.size:desc'.","title":"Sort"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Schools per page (1 to 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Page number, starting at 0.","title":"Page"}},"required":["region_id"],"title":"list_schools_by_regionArguments","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}}}}