---
title: "Upload API"
description: "API for adding and updating datasets in your MapTiler account."
---

> 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.

# Upload API

MapTiler’s Upload API adds new datasets or updates existing ones in your MapTiler account. You can call it directly, but we recommend using one of these tools instead. They handle the upload process for you:

-   **[CLI](https://github.com/maptiler/maptiler-cloud-cli)** – works with any tech stack. It reads your service token from the `--token` option or the `MAPTILER_TOKEN` environment variable, so you don’t need to write any backend code.
-   **[Upload JS](https://docs.maptiler.com/upload-js/)** – a JavaScript and TypeScript library with extra features. It needs a backend of your own to keep the service token private.

See the complete guide: [How to upload your data using API & CLI](https://docs.maptiler.com/guides/map-tiling-hosting/data-hosting/how-to-upload-mbtiles-or-geopackage-into-maptiler-cloud-using-api/).

## Upload API reference

Configure your environment settings below to update code samples:

-   **Client Libraries** – select your preferred programming language of the code examples.

  Scalar API Reference

-   [
    
    Introduction
    
    ](#description/introduction)
-   [
    
    dataset\_ingest
    
    ](#tag/dataset-ingest)
    
    Close Group - dataset\_ingest
    
    -   [
        
        Ingest dataset container into a new dataset
        
        HTTP Method:  POST](#tag/dataset-ingest/POST/datasets/ingest)
    -   [
        
        Ingest dataset container into existing tileset
        
        HTTP Method:  POST](#tag/dataset-ingest/POST/datasets/{document_id}/ingest)
    -   [
        
        Get dataset ingest details
        
        HTTP Method:  GET](#tag/dataset-ingest/GET/datasets/ingest/{ingest_id})
    -   [
        
        Cancel dataset ingest
        
        HTTP Method:  POST](#tag/dataset-ingest/POST/datasets/ingest/{ingest_id}/cancel)
    -   [
        
        Start dataset ingest processing
        
        HTTP Method:  POST](#tag/dataset-ingest/POST/datasets/ingest/{ingest_id}/process)

[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/)

Server

Server:https://service.maptiler.com/v1

MapTiler Service API

Client Libraries

Shell

Ruby

Node.js

PHP

Python

MoreSelect from all clients

Shell Curl

## 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' \
  --header 'Authorization: Basic username:password' \
  --data '{
  "filename": "north-america.mbtiles",
  "size": 723000000,
  "supported_upload_types": [
    "s3_multipart"
  ],
  "output": {
    "type": "raster_tileset"
  }
}'
```

cURLCopy

cURLCopy

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' \
  --header 'Authorization: Basic username:password' \
  --data '{
  "filename": "north-america.mbtiles",
  "size": 723000000,
  "supported_upload_types": [
    "s3_multipart"
  ],
  "output": {
    "type": "raster_tileset"
  }
}'
```

cURLCopy

cURLCopy

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 \
  --header 'Authorization: Basic username:password'
```

cURLCopy

cURLCopy

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 \
  --header 'Authorization: Basic username:password'
```

cURLCopy

cURLCopy

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' \
  --header 'Authorization: Basic username:password' \
  --data '{
  "upload_result": {
    "type": "s3_multipart",
    "parts": [
      {
        "part_id": 1,
        "etag": "fad1c8150539"
      },
      {
        "part_id": 2,
        "etag": "94a6e2002464"
      }
    ]
  }
}'
```

cURLCopy

cURLCopy

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