{"openapi":"3.1.0","info":{"title":"Mapbox Search Box API (your token) API","version":"0.1.0","description":"Mapbox Search Box API (your token) lets an AI assistant read your own Mapbox Search Box data through the Mapbox Search Box API with a key you supply (Mapbox access token (public or secret)). Read-only: 6 tools (suggest_places, retrieve_place, search_places, search_by_category, reverse_lookup, list_categories). The BYOK key travels with each request, is used for that one call only and is never...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-mapbox-search-box.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-mapbox-search-box/docs"},"termsOfService":"https://connectorbay.com/byok-mapbox-search-box/terms"},"servers":[{"url":"https://byok-mapbox-search-box.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-mapbox-search-box/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/suggest_places":{"post":{"operationId":"suggest_places","summary":"Autocomplete: suggest places, addresses, categories and points of interest for partial text, without coordinates (use re","description":"Autocomplete: suggest places, addresses, categories and points of interest for partial text, without coordinates (use retrieve_place with the mapbox_id for those); up to 10 suggestions. Use for \"Suggest places matching 'Michigan Stad' near Ann Arbor\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"description":"The user's query text, at most 256 characters.","maxLength":256,"title":"Q","type":"string"},"session_token":{"description":"A UUID v4 you generate; use the same value for suggest_places and the following retrieve_place (one billing session).","maxLength":64,"title":"Session Token","type":"string"},"language":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"ISO language code for results (default English).","title":"Language"},"limit":{"anyOf":[{"maximum":10,"minimum":1,"type":"integer"},{"type":"null"}],"default":5,"description":"How many suggestions (1 to 10).","title":"Limit"},"proximity":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Bias results toward 'longitude,latitude' (for example '-83.7487,42.2658') or 'ip' for the caller's IP location.","title":"Proximity"},"country":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated ISO 3166 alpha-2 country codes to limit results to, for example 'US,CA'.","title":"Country"},"bbox":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Bounding box 'min_lon,min_lat,max_lon,max_lat' to limit results to (cannot cross the 180th meridian).","title":"Bbox"},"types":{"anyOf":[{"maxLength":150,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated feature types: country, region, postcode, district, place, city, locality, neighborhood, block, street, address, poi, category.","title":"Types"},"poi_category":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated POI category ids to limit results to, for example 'airport,train_station' (see list_categories).","title":"Poi Category"}},"required":["q","session_token"],"title":"suggest_placesArguments","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/retrieve_place":{"post":{"operationId":"retrieve_place","summary":"Get the full feature (coordinates, address, category) of a suggestion by its mapbox_id, ending an autocomplete session. ","description":"Get the full feature (coordinates, address, category) of a suggestion by its mapbox_id, ending an autocomplete session. Use for \"Get the coordinates of the suggestion with mapbox_id dXJuOm1ieHBvaTpleGFtcGxl\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"mapbox_id":{"description":"The mapbox_id of a suggestion from suggest_places.","maxLength":300,"title":"Mapbox Id","type":"string"},"session_token":{"description":"A UUID v4 you generate; use the same value for suggest_places and the following retrieve_place (one billing session).","maxLength":64,"title":"Session Token","type":"string"},"language":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"ISO language code for results (default English).","title":"Language"}},"required":["mapbox_id","session_token"],"title":"retrieve_placeArguments","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_places":{"post":{"operationId":"search_places","summary":"One-off text search for places, addresses and points of interest with coordinates and metadata; up to 10 results, option","description":"One-off text search for places, addresses and points of interest with coordinates and metadata; up to 10 results, optionally biased or limited by location, country, type or category. Use for \"Find Heathrow Airport terminal 5\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"description":"Search text, at most 256 characters.","maxLength":256,"title":"Q","type":"string"},"language":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"ISO language code for results (default English).","title":"Language"},"limit":{"anyOf":[{"maximum":10,"minimum":1,"type":"integer"},{"type":"null"}],"default":5,"description":"How many results (1 to 10).","title":"Limit"},"proximity":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Bias results toward 'longitude,latitude' (for example '-83.7487,42.2658') or 'ip' for the caller's IP location.","title":"Proximity"},"country":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated ISO 3166 alpha-2 country codes to limit results to, for example 'US,CA'.","title":"Country"},"bbox":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Bounding box 'min_lon,min_lat,max_lon,max_lat' to limit results to (cannot cross the 180th meridian).","title":"Bbox"},"types":{"anyOf":[{"maxLength":150,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated feature types: country, region, postcode, district, place, city, locality, neighborhood, block, street, address, poi, category.","title":"Types"},"poi_category":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated POI category ids to limit results to, for example 'airport,train_station' (see list_categories).","title":"Poi Category"},"open_now":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to keep only points of interest that are open now.","title":"Open Now"}},"required":["q"],"title":"search_placesArguments","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_by_category":{"post":{"operationId":"search_by_category","summary":"List points of interest of one category (for example gas_station, airport, hotel) around a point or inside a box; up to ","description":"List points of interest of one category (for example gas_station, airport, hotel) around a point or inside a box; up to 25 results. Use for \"Find gas stations near longitude -122.41, latitude 39\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"category_id":{"description":"Canonical category id such as 'coffee', 'gas_station' or 'airport' (see list_categories).","maxLength":100,"title":"Category Id","type":"string"},"language":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"ISO language code for results (default English).","title":"Language"},"limit":{"anyOf":[{"maximum":25,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results (1 to 25).","title":"Limit"},"proximity":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Bias results toward 'longitude,latitude' (for example '-83.7487,42.2658') or 'ip' for the caller's IP location.","title":"Proximity"},"bbox":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Bounding box 'min_lon,min_lat,max_lon,max_lat' to limit results to (cannot cross the 180th meridian).","title":"Bbox"},"country":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated ISO 3166 alpha-2 country codes to limit results to, for example 'US,CA'.","title":"Country"}},"required":["category_id"],"title":"search_by_categoryArguments","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/reverse_lookup":{"post":{"operationId":"reverse_lookup","summary":"Find the address or place at a longitude and latitude; up to 10 results. Use for \"What address is at longitude -118.4714","description":"Find the address or place at a longitude and latitude; up to 10 results. Use for \"What address is at longitude -118.4714, latitude 34.0237\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"longitude":{"description":"Longitude of the point.","maximum":180,"minimum":-180,"title":"Longitude","type":"number"},"latitude":{"description":"Latitude of the point.","maximum":90,"minimum":-90,"title":"Latitude","type":"number"},"language":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"ISO language code for results (default English).","title":"Language"},"limit":{"anyOf":[{"maximum":10,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"How many results (1 to 10).","title":"Limit"},"country":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated ISO 3166 alpha-2 country codes to limit results to, for example 'US,CA'.","title":"Country"},"types":{"anyOf":[{"maxLength":150,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated feature types: country, region, postcode, district, place, city, locality, neighborhood, block, street, address, poi, category.","title":"Types"}},"required":["longitude","latitude"],"title":"reverse_lookupArguments","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_categories":{"post":{"operationId":"list_categories","summary":"List all point-of-interest categories with their canonical id, name and icon, in the chosen language. Use for \"Which pla","description":"List all point-of-interest categories with their canonical id, name and icon, in the chosen language. Use for \"Which place categories can I search by\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"language":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"ISO language code for results (default English).","title":"Language"}},"title":"list_categoriesArguments","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}}}}