A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Mapbox API is how an app or AI agent works with location data: turning an address into coordinates, calculating a driving route, rendering a static map image, or managing styles, datasets, and uploaded tilesets. Access is granted through an access token, and each token carries scopes that decide which services it can reach and can be locked to specific website addresses. Mapbox versions each service on its own path rather than pinning a single account-wide version.
How an app or AI agent connects to Mapbox determines what it can reach. There is the set of web service APIs called directly, and a hosted server that exposes Mapbox tools to agents, and each is governed by the access token behind it and the scopes that token carries.
Mapbox exposes a set of HTTPS web service APIs under the base host https://api.mapbox.com, each on its own versioned path (geocoding at /search/geocode/v6, directions at /directions/v5, and so on). Most return JSON or GeoJSON; the Static Images API returns a rendered picture. Every request supplies an access token in the access_token query parameter.
Mapbox publishes a first-party Model Context Protocol server that exposes its location tools to AI agents and LLM clients. A hosted endpoint at https://mcp.mapbox.com/mcp connects with no local install and prompts the user through an OAuth flow, so access tokens need not be handled manually; the same server can also be run locally with a token. It exposes geocoding and reverse geocoding, POI and category search, directions for driving, walking, and cycling, travel-time matrices, isochrones, and static map images.
A public token ships with every account and is safe to embed in client code. It carries default public scopes that let it read services like geocoding, directions, styles, fonts, and tiles, but it cannot create or change styles, datasets, uploads, or tokens. It can be given URL restrictions so it only works from named website addresses.
A secret token is created with specific scopes and is revealed only once, at creation, so it must be stored securely and used server-side. It is the token used for scoped writes such as datasets:write, uploads:write, and tokens:write. A leaked secret token should be deleted and replaced through the Tokens API.
A temporary token is created through the Tokens API and automatically expires at a set time, up to one hour in the future. It carries a subset of the creating token's scopes and is suited to short-lived sessions where a long-lived token should not be exposed.
The Mapbox APIs are split into areas an agent can act on, like turning text into coordinates, calculating routes, rendering map images, and managing styles, datasets, and uploads. Each area has its own methods, and most reads need only a default public token while writes to styles, datasets, uploads, or tokens need a scope that a public token does not carry.
Methods for converting between location text and coordinates, on the v6 Geocoding API.
Methods for routes, travel-time matrices, reachable areas, and snapping GPS traces to roads.
Methods for rendering static map images and querying features at a point.
Methods for working with map styles in an account.
Methods for working with editable datasets and their features.
Methods for staging files and turning them into tilesets.
Methods for managing the account's access tokens and their scopes.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
Geocoding (Search)Methods for converting between location text and coordinates, on the v6 Geocoding API.3 | ||||||
| GET | /search/geocode/v6/forward | Forward geocode: convert search text, like an address or place name, into coordinates. | read | — | Current | |
Read; the default public token is enough. Permanent geocoding (to cache results) is a separate, account-level entitlement. Acts ongeocode Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit600 requests per minute SourceOfficial documentation ↗ | ||||||
| GET | /search/geocode/v6/reverse | Reverse geocode: turn a longitude and latitude into the place names at that point. | read | — | Current | |
Read; the default public token is enough. Acts ongeocode Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit600 requests per minute SourceOfficial documentation ↗ | ||||||
| POST | /search/geocode/v6/batch | Batch geocode: send up to 1,000 forward or reverse queries in a single request. | read | — | Current | |
A POST is used to carry the query array, but it reads data and needs only a public token. Acts ongeocode Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Navigation & RoutingMethods for routes, travel-time matrices, reachable areas, and snapping GPS traces to roads.4 | ||||||
| GET | /directions/v5/{profile}/{coordinates} | Calculate a route between 2 to 25 waypoints, with turn-by-turn steps, for driving, driving-traffic, walking, or cycling. | read | — | Current | |
Read; large requests are sent as POST to stay under the URL length limit. Acts onroute Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /directions-matrix/v1/{profile}/{coordinates} | Return a matrix of travel times or distances between many origin and destination points. | read | — | Current | |
Read; capped at 25 coordinates (10 for driving-traffic). Acts onmatrix Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit60 requests per minute (30 for driving-traffic) SourceOfficial documentation ↗ | ||||||
| GET | /isochrone/v1/{profile}/{coordinates} | Compute the area reachable within a given travel time or distance from a point, returned as contour polygons or lines. | read | — | Current | |
Read; one coordinate, up to 4 contours, 60-minute or 100km maximum. Acts onisochrone Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit300 requests per minute SourceOfficial documentation ↗ | ||||||
| GET | /matching/v5/{profile}/{coordinates} | Map matching: snap a fuzzy GPS trace to the road and path network to produce a clean route. | read | — | Current | |
Read; up to 100 coordinates per request (50 for OpenLR), large traces sent as POST. Acts onmatch Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit300 requests per minute SourceOfficial documentation ↗ | ||||||
Maps & TilesMethods for rendering static map images and querying features at a point.2 | ||||||
| GET | /styles/v1/{username}/{style_id}/static/{overlay}/{position}/{dimensions} | Render a standalone static map image from a Studio style, with optional markers and overlays. | read | styles:tiles | Current | |
Read; needs the styles:tiles scope, which the default public token carries. Acts onstatic_image Permission (capability) styles:tilesVersionAvailable since the API’s base version Webhook eventNone Rate limit1,250 requests per minute SourceOfficial documentation ↗ | ||||||
| GET | /v4/{tileset_id}/tilequery/{lon},{lat}.json | Query features from a vector or rasterarray tileset at a longitude and latitude, without downloading tiles. | read | — | Current | |
Read; the default public token is enough. Acts ontilequery Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit600 requests per minute SourceOfficial documentation ↗ | ||||||
StylesMethods for working with map styles in an account.5 | ||||||
| GET | /styles/v1/{username} | List the styles that belong to an account, with pagination. | read | styles:list | Current | |
Needs the styles:list scope. Acts onstyle Permission (capability) styles:listVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /styles/v1/{username}/{style_id} | Retrieve a single style as a JSON document. | read | styles:read | Current | |
Needs the styles:read scope, which the default public token carries. Acts onstyle Permission (capability) styles:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /styles/v1/{username} | Create a new style in an account. | write | styles:write | Current | |
Needs the styles:write scope, which a public token does not carry. Acts onstyle Permission (capability) styles:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /styles/v1/{username}/{style_id} | Update an existing style with new content. | write | styles:write | Current | |
Needs the styles:write scope. Acts onstyle Permission (capability) styles:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /styles/v1/{username}/{style_id} | Delete a style, along with the sprites that belong to it. | write | styles:write | Current | |
Needs the styles:write scope; irreversible and also removes the style's sprites. Acts onstyle Permission (capability) styles:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
DatasetsMethods for working with editable datasets and their features.5 | ||||||
| GET | /datasets/v1/{username} | List the datasets that belong to an account, with pagination. | read | datasets:list | Current | |
Needs the datasets:list scope. Acts ondataset Permission (capability) datasets:listVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /datasets/v1/{username} | Create a new, empty dataset, with an optional name and description. | write | datasets:write | Current | |
Needs the datasets:write scope. Acts ondataset Permission (capability) datasets:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /datasets/v1/{username}/{dataset_id}/features | List the GeoJSON features in a dataset, with pagination. | read | datasets:read | Current | |
Needs the datasets:read scope. Acts onfeature Permission (capability) datasets:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /datasets/v1/{username}/{dataset_id}/features/{feature_id} | Insert or replace a GeoJSON feature in a dataset by its id. | write | datasets:write | Current | |
Needs the datasets:write scope. Acts onfeature Permission (capability) datasets:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /datasets/v1/{username}/{dataset_id}/features/{feature_id} | Delete a single feature from a dataset. | write | datasets:write | Current | |
Needs the datasets:write scope. Acts onfeature Permission (capability) datasets:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
UploadsMethods for staging files and turning them into tilesets.3 | ||||||
| POST | /uploads/v1/{username}/credentials | Retrieve temporary S3 credentials to stage a file before turning it into a tileset. | write | uploads:write | Current | |
Needs the uploads:write scope; returns short-lived staging credentials. Acts onupload Permission (capability) uploads:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /uploads/v1/{username} | Trigger generation of a tileset from a staged file or an existing dataset. | write | uploads:write | Current | |
Needs the uploads:write scope; processing runs asynchronously and is tracked by polling. Acts onupload Permission (capability) uploads:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /uploads/v1/{username}/{upload_id} | Retrieve the status of an upload, with progress from 0 to 1 and any error. | read | uploads:read | Current | |
Needs the uploads:read scope; this is how completion is detected, since there are no webhooks. Acts onupload Permission (capability) uploads:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TokensMethods for managing the account's access tokens and their scopes.5 | ||||||
| GET | /tokens/v2/{username} | List all the access tokens that belong to an account, with pagination. | read | tokens:read | Current | |
Needs the tokens:read scope. Acts ontoken Permission (capability) tokens:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /tokens/v2/{username} | Create a new access token with chosen scopes and optional URL restrictions, or a temporary token that expires. | write | tokens:write | Current | |
Needs the tokens:write scope; a token can only grant scopes the creating token holds. Acts ontoken Permission (capability) tokens:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /tokens/v2/{username}/{token_id} | Update a token's description, scopes, or allowed website addresses. | write | tokens:write | Current | |
Needs the tokens:write scope. Acts ontoken Permission (capability) tokens:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /tokens/v2/{username}/{token_id} | Delete an access token, revoking its access to Mapbox APIs. | write | tokens:write | Current | |
Needs the tokens:write scope; this is how a leaked token is revoked. Acts ontoken Permission (capability) tokens:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /scopes/v1/{username} | List every scope an account is allowed to grant to a token. | read | scopes:list | Current | |
Needs the scopes:list scope. Acts onscope Permission (capability) scopes:listVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Mapbox does not push events. An app learns about long-running work, like an upload being processed into a tileset, by polling its status rather than receiving a callback.
| Event | What it signals | Triggered by |
|---|
Mapbox sets a separate rate limit on each API, counted per access token, and reports the current state in response headers so an app can pace itself.
Mapbox sets a separate rate limit on each API, counted per access token, not per account. The Geocoding and Tilequery APIs default to 600 requests per minute, batch Geocoding and the Static Images API to higher ceilings, the Matrix API to 60 requests per minute for driving, walking, and cycling and 30 for driving-traffic, and the Isochrone and Map Matching APIs to 300 requests per minute. Each response carries X-Rate-Limit-Interval (the window in seconds), X-Rate-Limit-Limit (the ceiling for that window), and X-Rate-Limit-Reset (when the window resets). Going over returns HTTP 429 Too Many Requests, and higher limits are available by contacting Mapbox sales.
List endpoints, like listing styles, datasets, tokens, or uploads, page through results using a Link response header that carries the URL of the next page, combined with a limit query parameter and a start parameter that takes the id of the last item seen. An empty Link next relation signals the last page.
Batch Geocoding accepts up to 1,000 queries in a single request. The Directions and Map Matching APIs accept up to 25 and 100 coordinates respectively, the Matrix API up to 25 coordinates (10 for driving-traffic), and the Isochrone API a single coordinate with up to 4 contours. A request URL may be up to 8,192 bytes before returning HTTP 414 URI too long, which is why large Directions, Matrix, and Map Matching requests are sent as POST.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 401 | Not Authorized - Invalid Token | No access token was supplied, or the token is not valid. | Send a valid access token in the access_token query parameter, and confirm the token has not been deleted. |
| 403 | Forbidden | The token is valid but lacks the scope for this call, or the request came from an origin not in the token's URL restrictions. | Grant the missing scope on the token, or call from an allowed origin. Use a secret token for scoped writes. |
| 404 | Not Found | The requested resource, like a style, dataset, or upload, does not exist or is not visible to this token. | Check the id and the username in the path, and confirm the resource belongs to the account. |
| 422 | Invalid | A parameter is missing or malformed, like a coordinate out of range or a body that fails validation. | Read the message field in the response body, fix the parameters, and resend. |
| 429 | Too Many Requests | The per-token rate limit for that API was exceeded. | Back off using the X-Rate-Limit-Reset header, smooth the request rate, or contact Mapbox sales for a higher limit. |
| 414 | URI Too Long | The request URL exceeded the 8,192-byte limit, common on large Directions, Matrix, or Map Matching requests. | Send the request as POST with the coordinates in the body instead of the URL. |
Mapbox versions each service on its own path rather than pinning one account-wide version, so Geocoding sits at v6 while Directions and Map Matching sit at v5 and several services sit at v1.
Mapbox does not pin one dated version per account. Each web service carries its own version in its path, so they move independently: Geocoding at v6, Directions and Map Matching at v5, the Tokens API at v2, and Matrix, Isochrone, Datasets, and Uploads at v1. An integration can adopt a new version of one service without changing the others.
The Geocoding v6 API was updated to remove points of interest from results; POI search moved to the Search Box API.
Minor schema additions to Geocoding v6, including a name_preferred field, secondary address match codes, and updated address accuracy types.
The Geocoding v6 API reached general availability, with secondary (unit-level) address support, batch geocoding of up to 1,000 queries per request, structured input, a geographical context object, and self-service permanent geocoding.
Each service carries its own version in its path, so an integration upgrades one service at a time.
Mapbox Search changelog ↗Bollard AI sits between a team's AI agents and Mapbox. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.