{"openapi":"3.1.0","info":{"title":"Open States (BYOK) API","version":"0.1.0","description":"Open States (BYOK) lets an AI assistant read your own Open States data through the Open States API with a key you supply (Open States API key). Read-only: 7 tools (list_jurisdictions, get_jurisdiction, search_legislators, find_legislators_by_location, search_bills, get_bill, list_committees). The BYOK key travels with each request, is used for that one call only and is never stored, logged or...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-openstates.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-openstates/docs"},"termsOfService":"https://connectorbay.com/byok-openstates/terms"},"servers":[{"url":"https://byok-openstates.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-openstates/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_jurisdictions":{"post":{"operationId":"list_jurisdictions","summary":"List the jurisdictions Open States covers (states, DC, Puerto Rico, some municipalities) with id, name, classification a","description":"List the jurisdictions Open States covers (states, DC, Puerto Rico, some municipalities) with id, name, classification and the dates of the latest bill and people updates. Use for \"Which state legislatures does Open States cover\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"classification":{"anyOf":[{"enum":["state","municipality","country"],"type":"string"},{"type":"null"}],"default":null,"description":"Only this kind of jurisdiction: state, municipality or country.","title":"Classification"},"per_page":{"anyOf":[{"maximum":20,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Results per page, 1 to 20.","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_jurisdictionsArguments","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_jurisdiction":{"post":{"operationId":"get_jurisdiction","summary":"Get one jurisdiction with its legislative sessions (identifiers, names and dates; the session identifier is needed to lo","description":"Get one jurisdiction with its legislative sessions (identifiers, names and dates; the session identifier is needed to look up a bill) and its organizations. Use for \"What legislative sessions does Texas have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"jurisdiction_id":{"description":"Jurisdiction name or id, for example 'Texas' or 'ocd-jurisdiction/country:us/state:tx/government'.","maxLength":100,"title":"Jurisdiction Id","type":"string"},"include":{"anyOf":[{"enum":["legislative_sessions","organizations","latest_runs"],"type":"string"},{"type":"null"}],"default":"legislative_sessions","description":"Extra data to include: legislative_sessions, organizations or latest_runs.","title":"Include"}},"required":["jurisdiction_id"],"title":"get_jurisdictionArguments","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_legislators":{"post":{"operationId":"search_legislators","summary":"Search current legislators and other officials by name, jurisdiction, district or role (upper chamber, lower chamber, ex","description":"Search current legislators and other officials by name, jurisdiction, district or role (upper chamber, lower chamber, executive ...): name, party, current role, email and Open States link. Use for \"Who are the senators of Colorado\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"jurisdiction":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Jurisdiction name or id, for example 'Texas' or 'ocd-jurisdiction/country:us/state:tx/government'.","title":"Jurisdiction"},"name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Part of the person's name, case-insensitive.","title":"Name"},"district":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"District name or number.","title":"District"},"org_classification":{"anyOf":[{"enum":["upper","lower","legislature","executive","government"],"type":"string"},{"type":"null"}],"default":null,"description":"Current role: upper (senate), lower (house), legislature, executive or government.","title":"Org Classification"},"per_page":{"anyOf":[{"maximum":20,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Results per page, 1 to 20.","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"search_legislatorsArguments","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_legislators_by_location":{"post":{"operationId":"find_legislators_by_location","summary":"Find the state legislators who represent a latitude/longitude point. Use for \"Who are the state legislators for latitude","description":"Find the state legislators who represent a latitude/longitude point. Use for \"Who are the state legislators for latitude 30.2672, longitude -97.7431\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"lat":{"description":"Latitude in decimal degrees.","maximum":90,"minimum":-90,"title":"Lat","type":"number"},"lng":{"description":"Longitude in decimal degrees.","maximum":180,"minimum":-180,"title":"Lng","type":"number"}},"required":["lat","lng"],"title":"find_legislators_by_locationArguments","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_bills":{"post":{"operationId":"search_bills","summary":"Search state bills by jurisdiction, session, chamber, subject, sponsor, text or dates; returns identifier, title, sessio","description":"Search state bills by jurisdiction, session, chamber, subject, sponsor, text or dates; returns identifier, title, session, jurisdiction, classification, subjects and latest action. Use get_bill for actions and sponsors. Use for \"What Texas bills about water were acted on recently\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"jurisdiction":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Jurisdiction name or id, for example 'Texas' or 'ocd-jurisdiction/country:us/state:tx/government'.","title":"Jurisdiction"},"session":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Legislative session identifier, for example 2025.","title":"Session"},"chamber":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Chamber of origin, for example upper or lower.","title":"Chamber"},"identifier":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Bill identifier such as 'HB 1', to match one bill.","title":"Identifier"},"classification":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Bill classification, for example bill or resolution.","title":"Classification"},"subject":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"A subject term to match.","title":"Subject"},"sponsor":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Sponsor name or Open States person id.","title":"Sponsor"},"q":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Full-text search terms.","title":"Q"},"updated_since":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only bills updated since this date (YYYY-MM-DD).","title":"Updated Since"},"action_since":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only bills with an action since this date (YYYY-MM-DD).","title":"Action Since"},"sort":{"anyOf":[{"enum":["updated_asc","updated_desc","first_action_asc","first_action_desc","latest_action_asc","latest_action_desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Order: updated_asc, updated_desc (default), first_action_asc, first_action_desc, latest_action_asc or latest_action_desc.","title":"Sort"},"per_page":{"anyOf":[{"maximum":20,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Results per page, 1 to 20.","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"search_billsArguments","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_bill":{"post":{"operationId":"get_bill","summary":"Get one state bill by jurisdiction, session and identifier: title, subjects, latest action and, with include, sponsorshi","description":"Get one state bill by jurisdiction, session and identifier: title, subjects, latest action and, with include, sponsorships, actions, versions, documents or votes. Use for \"Show HB 1 of the 2025 Texas session with its actions\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"jurisdiction":{"description":"Jurisdiction name or id, for example 'Texas' or 'ocd-jurisdiction/country:us/state:tx/government'.","maxLength":100,"title":"Jurisdiction","type":"string"},"session":{"description":"Session identifier from get_jurisdiction, for example 89R.","maxLength":40,"title":"Session","type":"string"},"bill_id":{"description":"Bill identifier, for example 'HB 1'.","maxLength":30,"title":"Bill Id","type":"string"},"include":{"anyOf":[{"enum":["sponsorships","abstracts","other_titles","other_identifiers","actions","sources","documents","versions","votes","related_bills"],"type":"string"},{"type":"null"}],"default":"actions","description":"Extra data to include: sponsorships, abstracts, other_titles, other_identifiers, actions, sources, documents, versions, votes or related_bills.","title":"Include"}},"required":["jurisdiction","session","bill_id"],"title":"get_billArguments","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_committees":{"post":{"operationId":"list_committees","summary":"List legislative committees of a jurisdiction and chamber (the service marks committee data as experimental and incomple","description":"List legislative committees of a jurisdiction and chamber (the service marks committee data as experimental and incomplete for some states). Use for \"What committees does the Texas Senate have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"jurisdiction":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Jurisdiction name or id, for example 'Texas' or 'ocd-jurisdiction/country:us/state:tx/government'.","title":"Jurisdiction"},"chamber":{"anyOf":[{"enum":["upper","lower","legislature","executive","government"],"type":"string"},{"type":"null"}],"default":null,"description":"Chamber: upper, lower, legislature, executive or government.","title":"Chamber"},"classification":{"anyOf":[{"enum":["committee","subcommittee"],"type":"string"},{"type":"null"}],"default":null,"description":"committee or subcommittee.","title":"Classification"},"include":{"anyOf":[{"enum":["memberships","links","sources"],"type":"string"},{"type":"null"}],"default":null,"description":"Extra data: memberships, links or sources.","title":"Include"},"per_page":{"anyOf":[{"maximum":20,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Results per page, 1 to 20.","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_committeesArguments","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}}}}