--- title: "MapTiler Service API Reference" description: "Reference documentation for the core MapTiler Service Admin API services." --- > For AI agents: a documentation index is available at [/llms.txt](https://docs.maptiler.com/llms.txt). Markdown versions of all pages are available by appending .md to any URL. Scalar API Reference - Introduction - tileset Close Group - List tilesets belonging to your account HTTP Method:  GET - Get tileset details HTTP Method:  GET - Delete tileset HTTP Method:  DEL - Change tileset metadata HTTP Method:  POST - dataset\_ingest Close Group - Ingest dataset container into a new dataset HTTP Method:  POST - Ingest dataset container into existing tileset HTTP Method:  POST - Get dataset ingest details HTTP Method:  GET - Cancel dataset ingest HTTP Method:  POST - Start dataset ingest processing HTTP Method:  POST - API keys Close Group - List API keys belonging to account HTTP Method:  GET - Create new key HTTP Method:  POST - Get key HTTP Method:  GET - Delete given key HTTP Method:  DEL - Update given key HTTP Method:  POST - analytics Close Group - Get usage analytics timeline HTTP Method:  GET - Get top usage analytics HTTP Method:  GET [Powered by Scalar](https://www.scalar.com) v1.0 OpenAPI 3.0.2 # MapTiler Service API [Support](mailto:support@maptiler.com) [](https://docs.maptiler.com/support/requests/) [Terms of Service](https://www.maptiler.com/terms/) Download OpenAPI Document json Download OpenAPI Document yaml MapTiler Service API gives you full access to your account including write operations. You can use it for example to upload or delete data from your MapTiler account. 🔑 You need to authorize every request to the Service API with a [service token](https://docs.maptiler.com/cloud/api/authentication-token/). Get your service token in your MapTiler account, page [Credentials](https://cloud.maptiler.com/account/credentials/). All of the listed endpoints might return these error responses: | Code | Description | Note | | --- | --- | --- | | 400 | Bad Request | | | 401 | Not Authorized | | | 403 | Forbidden | Might be returned if storage limit was exceeded | | 404 | Not Found | | | 410 | Gone | The requested resource is no longer available | Server Server:https://service.maptiler.com/v1 MapTiler Service API ## AuthenticationRequired Selected Auth Type: token Client Libraries Shell Ruby Node.js PHP Python MoreSelect from all clients Shell Curl ## tileset ​Copy link tileset Operations - get/tiles - get/tiles/{document\_id} - delete/tiles/{document\_id} - post/tiles/{document\_id}/change\_metadata ### List tilesets belonging to your account ​Copy link Auth Required Query Parameters - cursorCopy link to cursor Type: string • base64 Page cursor - limitCopy link to limit Type: integer min:   10 max:   100 Default 50 Page limit Responses - 200 Page of tilesets application/json Request Example for get/tiles Shell Curl ```curl curl https://service.maptiler.com/v1/tiles ``` Copy Copy Test Request(get /tiles) Status: 200 Show Schema ```json { "cursor": "aWQ9ImRlNzY0ZjE0LTRhMzktNGRhMS1iM2QxLTlhYmM5NzQyMzEzYSI=", "items": [ { "id": "de764f14-4a39-4da1-b3d1-9abc9742313a", "title": "North America", "description": "Processed on 04.05.2021", "attribution": null }, { "id": "b9d06d13-23e6-46ef-a54f-9279965d5761", "title": "South America", "description": "", "attribution": null } ] } ``` JSONCopy JSONCopy Page of tilesets ### Get tileset details ​Copy link Auth Required Path Parameters - document\_idCopy link to document\_id Type: string Format: uuid required Responses - 200 Tileset application/json Request Example for get/tiles/_{document\_id}_ Shell Curl ```curl curl https://service.maptiler.com/v1/tiles/123e4567-e89b-12d3-a456-426614174000 ``` Copy Copy Test Request(get /tiles/{document\_id}) Status: 200 Show Schema ```json { "id": "de764f14-4a39-4da1-b3d1-9abc9742313a", "title": "North America", "description": "Processed on 04.05.2021", "attribution": null } ``` JSONCopy JSONCopy Tileset ### Delete tileset ​Copy link Auth Required Path Parameters - document\_idCopy link to document\_id Type: string Format: uuid required Responses - 200 Resource marked for deletion. Request Example for delete/tiles/_{document\_id}_ Shell Curl ```curl curl https://service.maptiler.com/v1/tiles/123e4567-e89b-12d3-a456-426614174000 \ --request DELETE ``` cURLCopy cURLCopy Test Request(delete /tiles/{document\_id}) Status: 200 No Body Resource marked for deletion. ### Change tileset metadata ​Copy link Auth Required Path Parameters - document\_idCopy link to document\_id Type: string Format: uuid required Body·TilesetMetadataChange application/json - attributionCopy link to attribution Type: string required - descriptionCopy link to description Type: string required - titleCopy link to title Type: string required Responses - 200 Tileset application/json Request Example for post/tiles/_{document\_id}_/change\_metadata Shell Curl ```curl curl https://service.maptiler.com/v1/tiles/123e4567-e89b-12d3-a456-426614174000/change_metadata \ --request POST \ --header 'Content-Type: application/json' \ --data '{ "title": "North America", "description": "Processed on 04.05.2021", "attribution": null }' ``` cURLCopy cURLCopy Test Request(post /tiles/{document\_id}/change\_metadata) Status: 200 Show Schema ```json { "id": "de764f14-4a39-4da1-b3d1-9abc9742313a", "title": "North America", "description": "Processed on 04.05.2021", "attribution": null } ``` JSONCopy JSONCopy Tileset ## dataset\_ingest ​Copy link dataset\_ingest Operations - post/datasets/ingest - post/datasets/{document\_id}/ingest - get/datasets/ingest/{ingest\_id} - post/datasets/ingest/{ingest\_id}/cancel - post/datasets/ingest/{ingest\_id}/process ### Ingest dataset container into a new dataset ​Copy link Auth Required Body·DatasetIngestCreate application/json - filenameCopy link to filename Type: string required name of the file limited to 255 bytes - sizeCopy link to size Type: integer required size in bytes - outputCopy link to output Type: object | null · DatasetIngestOutput Default null Specify output properties Show DatasetIngestOutputfor output - supported\_upload\_typesCopy link to supported\_upload\_types Type: array string\[\] · UploadType\[\]enum Default \["google\_drive\_resumable"\] Show UploadTypefor supported\_upload\_types Responses - 200 Dataset ingest application/json Request Example for post/datasets/ingest Shell Curl ```curl curl https://service.maptiler.com/v1/datasets/ingest \ --request POST \ --header 'Content-Type: application/json' \ --data '{ "filename": "north-america.mbtiles", "size": 723000000, "supported_upload_types": [ "s3_multipart" ], "output": { "type": "raster_tileset" } }' ``` cURLCopy cURLCopy Test Request(post /datasets/ingest) Status: 200 Show Schema ```json { "id": "e3a507c3-f9dd-4786-8af3-b21f4ca2d9c8", "document_id": null, "state": "upload", "filename": "north-america.mbtiles", "size": 723000000, "errors": null, "progress": 0, "upload_url": "https://www.googleapis.com/upload/drive/v3/files/?uploadType=resumable&supportsTeamDrives=true&upload_id=ABg5-UzOoBea-789qB46gXPK7gGIOoTt5rvcGfzdJSxf_iCJ98ysr0WT9asddb-CpBPWFiR_u0DnCWj3oiD9UErtTdVj3w" } ``` JSONCopy JSONCopy upload (Google Drive) Dataset ingest ### Ingest dataset container into existing tileset ​Copy link Auth Required Path Parameters - document\_idCopy link to document\_id Type: string Format: uuid required Body·DatasetIngestCreate application/json - filenameCopy link to filename Type: string required name of the file limited to 255 bytes - sizeCopy link to size Type: integer required size in bytes - outputCopy link to output Type: object | null · DatasetIngestOutput Default null Specify output properties Show DatasetIngestOutputfor output - supported\_upload\_typesCopy link to supported\_upload\_types Type: array string\[\] · UploadType\[\]enum Default \["google\_drive\_resumable"\] Show UploadTypefor supported\_upload\_types Responses - 200 Dataset ingest application/json Request Example for post/datasets/_{document\_id}_/ingest Shell Curl ```curl curl https://service.maptiler.com/v1/datasets/123e4567-e89b-12d3-a456-426614174000/ingest \ --request POST \ --header 'Content-Type: application/json' \ --data '{ "filename": "north-america.mbtiles", "size": 723000000, "supported_upload_types": [ "s3_multipart" ], "output": { "type": "raster_tileset" } }' ``` cURLCopy cURLCopy Test Request(post /datasets/{document\_id}/ingest) Status: 200 Show Schema ```json { "id": "e3a507c3-f9dd-4786-8af3-b21f4ca2d9c8", "document_id": null, "state": "upload", "filename": "north-america.mbtiles", "size": 723000000, "errors": null, "progress": 0, "upload_url": "https://www.googleapis.com/upload/drive/v3/files/?uploadType=resumable&supportsTeamDrives=true&upload_id=ABg5-UzOoBea-789qB46gXPK7gGIOoTt5rvcGfzdJSxf_iCJ98ysr0WT9asddb-CpBPWFiR_u0DnCWj3oiD9UErtTdVj3w" } ``` JSONCopy JSONCopy upload (Google Drive) Dataset ingest ### Get dataset ingest details ​Copy link Auth Required Path Parameters - ingest\_idCopy link to ingest\_id Type: string Format: uuid required Responses - 200 Dataset ingest application/json Request Example for get/datasets/ingest/_{ingest\_id}_ Shell Curl ```curl curl https://service.maptiler.com/v1/datasets/ingest/123e4567-e89b-12d3-a456-426614174000 ``` Copy Copy Test Request(get /datasets/ingest/{ingest\_id}) Status: 200 Show Schema ```json { "id": "e3a507c3-f9dd-4786-8af3-b21f4ca2d9c8", "document_id": null, "state": "upload", "filename": "north-america.mbtiles", "size": 723000000, "errors": null, "progress": 0, "upload_url": "https://www.googleapis.com/upload/drive/v3/files/?uploadType=resumable&supportsTeamDrives=true&upload_id=ABg5-UzOoBea-789qB46gXPK7gGIOoTt5rvcGfzdJSxf_iCJ98ysr0WT9asddb-CpBPWFiR_u0DnCWj3oiD9UErtTdVj3w" } ``` JSONCopy JSONCopy upload (Google Drive) Dataset ingest ### Cancel dataset ingest ​Copy link Auth Required Path Parameters - ingest\_idCopy link to ingest\_id Type: string Format: uuid required Responses - 200 Dataset ingest application/json Request Example for post/datasets/ingest/_{ingest\_id}_/cancel Shell Curl ```curl curl https://service.maptiler.com/v1/datasets/ingest/123e4567-e89b-12d3-a456-426614174000/cancel \ --request POST ``` cURLCopy cURLCopy Test Request(post /datasets/ingest/{ingest\_id}/cancel) Status: 200 Show Schema ```json { "id": "e3a507c3-f9dd-4786-8af3-b21f4ca2d9c8", "document_id": null, "state": "upload", "filename": "north-america.mbtiles", "size": 723000000, "errors": null, "progress": 0, "upload_url": "https://www.googleapis.com/upload/drive/v3/files/?uploadType=resumable&supportsTeamDrives=true&upload_id=ABg5-UzOoBea-789qB46gXPK7gGIOoTt5rvcGfzdJSxf_iCJ98ysr0WT9asddb-CpBPWFiR_u0DnCWj3oiD9UErtTdVj3w" } ``` JSONCopy JSONCopy upload (Google Drive) Dataset ingest ### Start dataset ingest processing ​Copy link Auth Required Path Parameters - ingest\_idCopy link to ingest\_id Type: string Format: uuid required Body·DatasetIngestProcess application/json - upload\_resultCopy link to upload\_result Type: object · UploadResult Show UploadResultfor upload\_result One ofS3UploadResult - type Discriminator Type: string · UploadTypeenum values - s3\_multipart - google\_drive\_resumable - parts Type: array object\[\] · S3UploadResultItem\[\] Show S3UploadResultItemfor parts Responses - 200 Dataset ingest application/json Request Example for post/datasets/ingest/_{ingest\_id}_/process Shell Curl ```curl curl https://service.maptiler.com/v1/datasets/ingest/123e4567-e89b-12d3-a456-426614174000/process \ --request POST \ --header 'Content-Type: application/json' \ --data '{ "upload_result": { "type": "s3_multipart", "parts": [ { "part_id": 1, "etag": "fad1c8150539" }, { "part_id": 2, "etag": "94a6e2002464" } ] } }' ``` cURLCopy cURLCopy Test Request(post /datasets/ingest/{ingest\_id}/process) Status: 200 Show Schema ```json { "id": "e3a507c3-f9dd-4786-8af3-b21f4ca2d9c8", "document_id": null, "state": "upload", "filename": "north-america.mbtiles", "size": 723000000, "errors": null, "progress": 0, "upload_url": "https://www.googleapis.com/upload/drive/v3/files/?uploadType=resumable&supportsTeamDrives=true&upload_id=ABg5-UzOoBea-789qB46gXPK7gGIOoTt5rvcGfzdJSxf_iCJ98ysr0WT9asddb-CpBPWFiR_u0DnCWj3oiD9UErtTdVj3w" } ``` JSONCopy JSONCopy upload (Google Drive) Dataset ingest ## API keys ​Copy link API keys Operations - get/api\_keys - post/api\_keys - get/api\_keys/{key\_id} - delete/api\_keys/{key\_id} - post/api\_keys/{key\_id}/change\_settings ### List API keys belonging to account ​Copy link Auth Required Query Parameters - cursorCopy link to cursor Type: string • base64 Page cursor - limitCopy link to limit Type: integer min:   10 max:   100 Default 50 Page limit Responses - 200 application/json Request Example for get/api\_keys Shell Curl ```curl curl https://service.maptiler.com/v1/api_keys ``` Copy Copy Test Request(get /api\_keys) Status: 200 Show Schema ```json { "cursor": null, "total_count": 1, "items": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "token": "string", "name": "string", "description": null, "user_agent": null, "origins": [ "string" ], "created": "2026-08-24T07:53:22.225Z", "changed": "2026-08-24T07:53:22.225Z" } ] } ``` JSONCopy JSONCopy ### Create new key ​Copy link Auth Required Body·APIKeySettings application/json - descriptionCopy link to description Type: string | null - nameCopy link to name Type: string | null Will be generated automatically unless provided explicitly. - originsCopy link to origins Type: array string\[\] Specifies which HTTP origins are allowed to access the API. For example \[`mydomain.com`\] will ensure, that only requests coming from `mydomain.com` will be processed. Use `*.mydomain.com` to allow all subdomains. Ensure your application sends the `Origin` or `Referer` header; otherwise, requests are treated as unknown and will be rejected if any origin is specified. Use `?` placeholder to explicitly allow unknown origins. - user\_agentCopy link to user\_agent Type: string | null Processes only requests where the `User-Agent` HTTP header contains this exact, case-sensitive substring. Wildcards are not supported; only a single string is allowed. Useful for increasing security of your key used in custom mobile or desktop applications. Leave empty to allow requests from any user-agent. Responses - 200 application/json Request Example for post/api\_keys Shell Curl ```curl curl https://service.maptiler.com/v1/api_keys \ --request POST \ --header 'Content-Type: application/json' \ --data '{ "name": null, "description": null, "user_agent": null, "origins": [ "" ] }' ``` cURLCopy cURLCopy Test Request(post /api\_keys) Status: 200 Show Schema ```json { "id": "123e4567-e89b-12d3-a456-426614174000", "token": "string", "name": "string", "description": null, "user_agent": null, "origins": [ "string" ], "created": "2026-08-24T07:53:22.225Z", "changed": "2026-08-24T07:53:22.225Z" } ``` JSONCopy JSONCopy ### Get key ​Copy link Auth Required Path Parameters - key\_idCopy link to key\_id Responses - 200 application/json Request Example for get/api\_keys/_{key\_id}_ Shell Curl ```curl curl 'https://service.maptiler.com/v1/api_keys/{key_id}' ``` Copy Copy Test Request(get /api\_keys/{key\_id}) Status: 200 Show Schema ```json { "id": "123e4567-e89b-12d3-a456-426614174000", "token": "string", "name": "string", "description": null, "user_agent": null, "origins": [ "string" ], "created": "2026-08-24T07:53:22.225Z", "changed": "2026-08-24T07:53:22.225Z" } ``` JSONCopy JSONCopy ### Delete given key ​Copy link Auth Required Path Parameters - key\_idCopy link to key\_id Responses - 200 Successfully deleted Request Example for delete/api\_keys/_{key\_id}_ Shell Curl ```curl curl 'https://service.maptiler.com/v1/api_keys/{key_id}' \ --request DELETE ``` cURLCopy cURLCopy Test Request(delete /api\_keys/{key\_id}) Status: 200 No Body Successfully deleted ### Update given key ​Copy link Auth Required Path Parameters - key\_idCopy link to key\_id Body·APIKeySettings application/json - descriptionCopy link to description Type: string | null - nameCopy link to name Type: string | null Will be generated automatically unless provided explicitly. - originsCopy link to origins Type: array string\[\] Specifies which HTTP origins are allowed to access the API. For example \[`mydomain.com`\] will ensure, that only requests coming from `mydomain.com` will be processed. Use `*.mydomain.com` to allow all subdomains. Ensure your application sends the `Origin` or `Referer` header; otherwise, requests are treated as unknown and will be rejected if any origin is specified. Use `?` placeholder to explicitly allow unknown origins. - user\_agentCopy link to user\_agent Type: string | null Processes only requests where the `User-Agent` HTTP header contains this exact, case-sensitive substring. Wildcards are not supported; only a single string is allowed. Useful for increasing security of your key used in custom mobile or desktop applications. Leave empty to allow requests from any user-agent. Responses - 200 application/json Request Example for post/api\_keys/_{key\_id}_/change\_settings Shell Curl ```curl curl 'https://service.maptiler.com/v1/api_keys/{key_id}/change_settings' \ --request POST \ --header 'Content-Type: application/json' \ --data '{ "name": null, "description": null, "user_agent": null, "origins": [ "" ] }' ``` cURLCopy cURLCopy Test Request(post /api\_keys/{key\_id}/change\_settings) Status: 200 Show Schema ```json { "id": "123e4567-e89b-12d3-a456-426614174000", "token": "string", "name": "string", "description": null, "user_agent": null, "origins": [ "string" ], "created": "2026-08-24T07:53:22.225Z", "changed": "2026-08-24T07:53:22.225Z" } ``` JSONCopy JSONCopy ## analytics ​Copy link analytics Operations - get/analytics/api\_usage/timeline - get/analytics/api\_usage/top ### Get usage analytics timeline ​Copy link Auth Required Query Parameters - periodCopy link to period Type: string enum required - billing periods are based on account subscription - for classifiers api\_keys and service\_credentials are **supported only daily periods**: current\_billing\_period, last\_billing\_period, past\_30\_days, past\_90\_days values - current\_billing\_period - last\_billing\_period - past\_30\_days - past\_90\_days - past\_12\_billing\_periods - past\_12\_months - all - classifierCopy link to classifier Type: string enum required classifies datasets values - services - api\_keys - service\_credentials - groupCopy link to group Type: string enum group ID filter, **mandatory for CSV format** values - request - session - export - formatCopy link to format Type: string enum Default json response media type values - json - csv Responses - 200 Usage analytics timeline response, further description is within each media type schema. Selected Content Type: application/json - 400 - `period_not_found`: Selected time period does not exist (for example last\_billing\_period of new account) - `account_over_limit`: Account currently has too many entities (api\_keys or service\_credentials) to be queried. - `response_too_large`: There were too much data in the result (could be historical). Request Example for get/analytics/api\_usage/timeline Shell Curl ```curl curl 'https://service.maptiler.com/v1/analytics/api_usage/timeline?period=current_billing_period&classifier=services' ``` Copy Copy Test Request(get /analytics/api\_usage/timeline) Status: 200Status: 400 Show Schema ```json { "since": "2026-08-24", "until": "2026-08-24", "datasets": [ { "group_id": "request", "item_id": "string", "data": [ { "date": "2026-08-24", "value": 1 } ], "estimated_data": { "date": "2026-08-24", "value": 1 } } ], "legend": [ { "item_id": "string", "label": "string", "description": null } ] } ``` JSONCopy JSONCopy Usage analytics timeline response, further description is within each media type schema. ### Get top usage analytics ​Copy link Auth Required Query Parameters - periodCopy link to period Type: string enum required - billing periods are based on account subscription - for classifiers api\_keys and service\_credentials are **supported only daily periods**: current\_billing\_period, last\_billing\_period, past\_30\_days, past\_90\_days values - current\_billing\_period - last\_billing\_period - past\_30\_days - past\_90\_days - past\_12\_billing\_periods - past\_12\_months - all - classifierCopy link to classifier Type: string enum required classifies datasets values - services - api\_keys - service\_credentials - groupCopy link to group Type: string enum group ID filter, **mandatory for CSV format** values - request - session - export - formatCopy link to format Type: string enum Default json response media type values - json - csv - limitCopy link to limit Type: integer Default 10 number of top items within response group Responses - 200 Usage analytics top response, further description is within each media type schema. Selected Content Type: application/json - 400 - `period_not_found`: Selected time period does not exist (for example last\_billing\_period of new account) Request Example for get/analytics/api\_usage/top Shell Curl ```curl curl 'https://service.maptiler.com/v1/analytics/api_usage/top?period=current_billing_period&classifier=services' ``` Copy Copy Test Request(get /analytics/api\_usage/top) Status: 200Status: 400 Show Schema ```json { "since": "2026-08-24", "until": "2026-08-24", "datasets": [ { "group_id": "request", "data": [ { "item_id": "string", "value": 1 } ] } ], "legend": [ { "item_id": "string", "label": "string", "description": null } ] } ``` JSONCopy JSONCopy Usage analytics top response, further description is within each media type schema.