Mapflow

https://docs.mapflow.ai
Admin
Mapflow is an AI-powered Earth observation platform that automates semantic imagery analysis and...
Tokens:31,469
Snippets:335
Trust Score:6.9
Update:5 months ago
Show doc for...
Tokens:
Raw
### Scene Product Response Example

Source: https://docs.mapflow.ai/api/mapflow_api.html

Example JSON response structure for a 'Scene' product type returned from the imagery search API.

```json
[
  {
    "id": "JL1GF03A_PMS_20220607132729_200087596_103_0002_001_L1",
    "productType": "Scene",
    "acquisitionDate": "2022-06-07T13:27:33Z",
    "sensor": "JL1GF03A",
    "pixelResolution": 1.06,
    "cloudCover": 0.09,
    "offNadirAngle": -3.91,
    "colorBandOrder": "B,G,R,NIR,PAN",
    "providerName": "CG",
    "previewType": "png",
    "previewUrl": "https://example.com/preview.jpg",
    "footprint": {
      "type": "Polygon",
     "coordinates": [[[76.5009, 43.3412]]]
    }
  }
]
```

--------------------------------

### Create Project Request

Source: https://docs.mapflow.ai/api/mapflow_api.html

Example JSON payload for creating a new project. Provide a name and an optional description.

```json
{
  "name": "Urban Analysis 2026",
  "description": "Building footprints for city planning"
}
```

--------------------------------

### Mosaic Product Response Example

Source: https://docs.mapflow.ai/api/mapflow_api.html

Example JSON response structure for a 'Mosaic' product type returned from the imagery search API.

```json
[
  {
    "id": "JL1KF01A_PMS04_20220717131252_200093089_101_0005_001_L1",
    "productType": "Mosaic",
    "acquisitionDate": "2022-07-17T00:00:00Z",
    "sensor": "JL1KF01A",
    "pixelResolution": 0.0,
    "cloudCover": 0.0,
    "offNadirAngle": 3.0,
    "colorBandOrder": "RGB",
    "providerName": "CG_mosaic_2022",
    "previewType": "xyz",
    "previewUrl": "https://app.mapflow.ai/tiles/provider/{z}/{x}/{-y}.png",
    "footprint": {
      "type": "MultiPolygon",
     "coordinates": [[[[76.9037, 43.2529]]]]
    }
  }
]
```

--------------------------------

### Quick Start: Upload Images to Mosaic

Source: https://docs.mapflow.ai/api/mapflow_api.html

Upload imagery files to a previously created mosaic. Ensure the file path is correct.

```bash
curl -X POST https://api.mapflow.ai/rest/rasters/mosaic/{mosaic-uuid}/image \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/multipart/form-data" \
  -F "file=@/path/to/orthophoto.tif"
```

--------------------------------

### Create Processing (v2) - Mapbox Example

Source: https://docs.mapflow.ai/api/mapflow_api.html

Example request body for creating a processing using Mapbox imagery. Specify the providerName and zoom level.

```json
{
  "name": "Downtown Buildings",
  "projectId": "546d148f-19a1-40d8-8f16-d1e6dabfd204",
  "wdName": "🏠 Buildings",
  "geometry": {
    "type": "Polygon",
    "coordinates": [[[37.615, 55.755], [37.625, 55.755],
                     [37.625, 55.760], [37.615, 55.760],
                     [37.615, 55.755]]]
  },
  "params": {
    "sourceParams": {
      "dataProvider": {
        "providerName": "Mapbox",
        "zoom": 18
      }
    }
  }
}
```

--------------------------------

### Quick Start: Create a Mosaic

Source: https://docs.mapflow.ai/api/mapflow_api.html

Use this command to create a new mosaic container for your imagery. Replace YOUR_TOKEN with your actual API token.

```bash
curl -X POST https://api.mapflow.ai/rest/rasters/mosaic \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Aerial Survey", "tags": ["survey-2024"]}'
```

--------------------------------

### Create Processing (v2) - Custom Imagery Example

Source: https://docs.mapflow.ai/api/mapflow_api.html

Example request body for creating a processing using custom uploaded imagery. Reference image IDs within sourceParams.

```json
{
  "name": "Aerial Survey 2026",
  "projectId": "546d148f-19a1-40d8-8f16-d1e6dabfd204",
  "wdName": "🏠 Buildings",
  "geometry": {"type": "Polygon", "coordinates": [...]},
  "params": {
    "sourceParams": {
      "myImagery": {
        "imageIds": ["0c26a0d3-96d8-4ed5-aa62-3843d1d7905c"]
      }
    }
  }
}
```

--------------------------------

### Authorization - Get API Token

Source: https://docs.mapflow.ai/api/mapflow_api.html

This example shows how to obtain an API token for accessing the Mapflow API. The token is required for all API requests and can be obtained from the Mapflow.ai user profile settings.

```APIDOC
## Authorization to Mapflow API

To access from external applications such as plugin for QGIS you need to get **API token**. Users can register and obtain token at https://app.mapflow.ai/app/account/api. Token must be passed in the **Basic Auth** parameters like in the example:

```curl
curl --location --request GET 'https://api.mapflow.ai/rest/projects/default' \
--header 'Authorization: Basic <YOUR TOKEN>'
```

Note
> Your token is generated by request and composed of <Email: API Token>
You can decode it with base64 decoder to use in Basic Auth form
Make sure you save the token, otherwise you will need to reissue it.

### Obtaining an API token
  1. Open the web application Mapflow. Register a new account or sign in using your Google account.
  2. Go to user profile settings to generate a new API token.
```

--------------------------------

### Quick Start: Run Processing with Uploaded Imagery

Source: https://docs.mapflow.ai/api/mapflow_api.html

Initiate an imagery analysis processing using imagery uploaded to a mosaic. Specify the mosaicId in sourceParams.

```bash
curl -X POST https://api.mapflow.ai/rest/processings/v2 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Building Detection",
    "projectId": "project-uuid",
    "wdName": "🏠 Buildings",
    "geometry": {...},
    "params": {
      "sourceParams": {
        "myImagery": {"mosaicId": "mosaic-uuid"}
      }
    }
  }'
```

--------------------------------

### Mapflow Processing API - Create and Run Processing

Source: https://docs.mapflow.ai/api/mapflow_api.html

This example demonstrates how to create and run a new processing job using the Mapflow Processing API. You can specify the project, analysis type, geometry, and parameters for the job.

```APIDOC
### Create and run processing

```curl
curl -X POST https://api.mapflow.ai/rest/processings/v2 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Downtown Buildings",
    "projectId": "project-uuid",
    "wdName": "🏠 Buildings",
    "geometry": {
      "type": "Polygon",
      "coordinates": [[
        [37.6156, 55.7558],
        [37.6256, 55.7558],
        [37.6256, 55.7608],
        [37.6156, 55.7608],
        [37.6156, 55.7558]
      ]]
    },
    "params": {
      "sourceParams": {
        "dataProvider": {
          "providerName": "Mapbox",
          "zoom": 18
        }
      }
    }
  }'
```

Response: `{"id": "processing-uuid", "status": "IN_PROGRESS", ...}`
```

--------------------------------

### Update Project Request

Source: https://docs.mapflow.ai/api/mapflow_api.html

Example JSON payload for updating an existing project. You can modify the name and/or description.

```json
{
  "name": "Urban Analysis 2026 - Updated",
  "description": "Building and road detection"
}
```

--------------------------------

### Get User Status

Source: https://docs.mapflow.ai/api/mapflow_api.html

Retrieves account details, including user information, available models, and workflow definitions.

```json
{
  "user": {
    "id": "user-uuid",
    "email": "user@example.com",
    "credits": 5000
  },
  "models": [
    {
      "id": "model-uuid",
      "name": "🏠 Buildings",
      "pricePerSqKm": 15.0,
      "blocks": [...]
    }
  ]
}

```

--------------------------------

### Mapflow Processing API - Create Project

Source: https://docs.mapflow.ai/api/mapflow_api.html

This example shows how to create a new project using the Mapflow Processing API. Projects are used to organize your geospatial analysis tasks.

```APIDOC
### Create a project

```curl
curl -X POST https://api.mapflow.ai/rest/projects \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My First Project",
    "description": "Buildings detection"
  }'
```

Response: `{"id": "project-uuid", ...}`
```

--------------------------------

### Mapflow Processing API - Check Status and Download Results

Source: https://docs.mapflow.ai/api/mapflow_api.html

These examples show how to check the status of a processing job and download the results once the processing is complete.

```APIDOC
### Check status and download results

```curl
# Check status
curl https://api.mapflow.ai/rest/processings/{processing-uuid}/v2 \
  -H "Authorization: Bearer YOUR_TOKEN"

# Download results (when status = "OK")
curl https://api.mapflow.ai/rest/processings/{processing-uuid}/result \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o results.geojson
```
```

--------------------------------

### Get user status

Source: https://docs.mapflow.ai/api/mapflow_api.html

Retrieves account details, including user information, available models, and workflow definitions.

```APIDOC
## GET /user/status

### Description
Returns account details, available models, and workflow definitions.

### Method
GET

### Endpoint
/user/status

### Response
#### Success Response (200)
- **user** (object) - User account information
  - **id** (string) - User ID
  - **email** (string) - User email address
  - **credits** (integer) - Available credits
- **models** (array) - List of available models
  - **id** (string) - Model ID
  - **name** (string) - Name of the model
  - **pricePerSqKm** (number) - Cost per square kilometer
  - **blocks** (array) - List of workflow blocks associated with the model

### Response Example
```json
{
  "user": {
    "id": "user-uuid",
    "email": "user@example.com",
    "credits": 5000
  },
  "models": [
    {
      "id": "model-uuid",
      "name": "🏠 Buildings",
      "pricePerSqKm": 15.0,
      "blocks": [...] 
    }
  ]
}
```
```

--------------------------------

### Get Image Preview

Source: https://docs.mapflow.ai/api/mapflow_api.html

Retrieves a preview thumbnail of an image in JPEG format. Specify the image ID and the desired size ('s' for small, 'l' for large).

```bash
curl https://api.mapflow.ai/rest/rasters/image/{image_id}/preview/s \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o preview.jpg


```

--------------------------------

### Get Storage Usage

Source: https://docs.mapflow.ai/api/mapflow_api.html

Returns current storage usage and limits for your account, including used and limit in bytes and GB, and usage percentage.

```json
{
  "used_bytes": 5368709120,
  "limit_bytes": 10737418240,
  "used_gb": 5.0,
  "limit_gb": 10.0,
  "usage_percent": 50.0
}


```

--------------------------------

### Get Storage Usage

Source: https://docs.mapflow.ai/api/mapflow_api.html

Returns the current storage usage and limits for your account. This endpoint helps you monitor your data consumption against your allocated storage.

```APIDOC
## GET /rasters/memory

### Description
Returns current storage usage and limits for your account.

### Method
GET

### Endpoint
/rasters/memory

### Example Request
```bash
curl https://api.mapflow.ai/rest/rasters/memory \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Response
#### Success Response (200)
- **used_bytes** (integer) - The amount of storage currently used in bytes.
- **limit_bytes** (integer) - The total storage limit in bytes.
- **used_gb** (number) - The amount of storage currently used in gigabytes.
- **limit_gb** (number) - The total storage limit in gigabytes.
- **usage_percent** (number) - The percentage of storage used.

#### Response Example
```json
{
  "used_bytes": 5368709120,
  "limit_bytes": 10737418240,
  "used_gb": 5.0,
  "limit_gb": 10.0,
  "usage_percent": 50.0
}
```
```

--------------------------------

### Get API Token Status

Source: https://docs.mapflow.ai/api/processing_api.html

Verify your API authentication by checking the status of your API token. Replace YOUR_API_TOKEN with your actual token.

```APIDOC
## GET /user/status

### Description
Checks the status of the provided API token.

### Method
GET

### Endpoint
https://api.mapflow.ai/rest/user/status

### Request Headers
- Authorization: Bearer YOUR_API_TOKEN
```

--------------------------------

### Get Processing IDs and Names with Python

Source: https://docs.mapflow.ai/userguides/use_API.html

This Python script fetches a list of all processings for a given project, extracting their IDs and names. It requires the 'requests' library and your username and password for authentication. The output is a list of ID-name pairs.

```python
import requests
import json

url = "https://api.mapflow.ai/rest/projects/fb49b97e-51ec-4b31-872f-d1411284de85/processings"

response = requests.request("GET", url, auth=(username,password))

json_data = response.json()

values = []
for item in json_data:
    if "id" in item and "name" in item:
        values.append((item["id"], item["name"]))

if  response.status_code == 200:
    for id, name in values:
        print(f"{id}, {name}")
else:
    print(response.text)

```

--------------------------------

### Get List of Processings

Source: https://docs.mapflow.ai/userguides/use_API.html

Retrieve a list of all processings for a given project, including their IDs and names. This is useful for iterating and downloading results for multiple processings.

```APIDOC
## Get List of Processings

### Description
Retrieve a list of all processings for a given project, including their IDs and names. This is useful for iterating and downloading results for multiple processings.

### Method
GET

### Endpoint
`https://api.mapflow.ai/rest/projects/<PROJECT_ID>/processings`

### Parameters
#### Path Parameters
- **PROJECT_ID** (string) - Required - The unique identifier of the project.

#### Authentication
Requires username and password for authentication.

### Request Example
```python
import requests

url = "https://api.mapflow.ai/rest/projects/<PROJECT_ID>/processings"
username = "<YOUR_USERNAME>"
password = "<YOUR_PASSWORD>"

response = requests.request("GET", url, auth=(username, password))
json_data = response.json()

values = []
for item in json_data:
    if "id" in item and "name" in item:
        values.append((item["id"], item["name"]))

if response.status_code == 200:
    for id, name in values:
        print(f"{id}, {name}")
else:
    print(response.text)
```

### Response Example
```
5f748822-c94a-4233-ae1e-7622973bf9b5, Бой
87f258e6-c1ce-4deb-8155-ccd6b21ac237, Авазли
1e24c0e5-9b6f-4a26-9970-82dfb1f67807, Avazali
...
```
```

--------------------------------

### Get Image Preview

Source: https://docs.mapflow.ai/api/mapflow_api.html

Retrieves a preview thumbnail of an image in either small or large size. This is useful for quickly visualizing image content without downloading the full file.

```APIDOC
## GET /rasters/image/{image_id}/preview/{size}

### Description
Retrieves a preview thumbnail of the image.

### Method
GET

### Endpoint
/rasters/image/{image_id}/preview/{size}

### Parameters
#### Path Parameters
- **size** (string) - Required - Specifies the size of the preview.
  - `s`: Small preview (256×256 pixels)
  - `l`: Large preview (1024×1024 pixels)

### Example Request
```bash
curl https://api.mapflow.ai/rest/rasters/image/{image_id}/preview/s \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o preview.jpg
```

### Response
Returns JPEG image data.
```

--------------------------------

### Create a Project

Source: https://docs.mapflow.ai/api/processing_api.html

Create a new project to organize your geospatial analysis tasks. The project name and description are required.

```APIDOC
## POST /projects

### Description
Creates a new project for organizing geospatial analysis.

### Method
POST

### Endpoint
https://api.mapflow.ai/rest/projects

### Request Headers
- Authorization: Bearer YOUR_TOKEN
- Content-Type: application/json

### Request Body
- **name** (string) - Required - The name of the project.
- **description** (string) - Optional - A description for the project.

### Request Example
```json
{
  "name": "My First Project",
  "description": "Buildings detection"
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the created project.
```

--------------------------------

### Get Mosaic

Source: https://docs.mapflow.ai/api/mapflow_api.html

Retrieves mosaic metadata by its unique ID.

```APIDOC
## GET /rasters/mosaic/{mosaic_id}

Retrieves mosaic metadata by ID.

### Method

GET

### Endpoint

`/rasters/mosaic/{mosaic_id}`

### Parameters

#### Path Parameters

- **`mosaic_id`** (string) - Required - The ID of the mosaic to retrieve.

### Response

#### Success Response (200)

- **`id`** (string) - Unique identifier for the mosaic.
- **`name`** (string) - The name of the mosaic.
- **`tags`** (array) - List of tags associated with the mosaic.
- **`created_at`** (string) - Timestamp when the mosaic was created.
- **`image_count`** (integer) - The number of images currently in the mosaic.

#### Response Example

```json
{
  "id": "6ee95ae6-f26e-41bd-8cb1-39bea545119f",
  "name": "Aerial Survey 2024",
  "tags": ["agriculture", "spring"],
  "created_at": "2024-03-15T10:30:00Z",
  "image_count": 15
}
```
```

--------------------------------

### Get processing (v2)

Source: https://docs.mapflow.ai/api/mapflow_api.html

Retrieves the status and details of a specific processing job using its unique ID.

```APIDOC
## GET /processings/{processingId}/v2

### Description
Retrieves processing status and details.

### Method
GET

### Endpoint
/processings/{processingId}/v2

#### Path Parameters
- **processingId** (string) - Required - Processing UUID

### Response
#### Success Response (200)
- **id** (string) - Processing ID
- **name** (string) - Name of the processing job
- **status** (string) - Current status of the processing (e.g., UNPROCESSED, IN_PROGRESS, OK, FAILED)
- **percentCompleted** (number) - Percentage of completion
- **area** (number) - Processed area in square meters
- **cost** (number) - Estimated or actual cost of the processing
- **vectorLayer** (object) - Information about the vector layer output
  - **id** (string) - ID of the vector layer
  - **tileUrl** (string) - URL for accessing the vector tiles
- **created** (string) - Timestamp when the processing was created
- **updated** (string) - Timestamp when the processing was last updated

### Response Example
```json
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Downtown Buildings",
  "status": "OK",
  "percentCompleted": 100,
  "area": 1200000,
  "cost": 150,
  "vectorLayer": {
    "id": "layer-uuid",
    "tileUrl": "https://app.mapflow.ai/api/layers/{z}/{x}/{y}.pbf"
  },
  "created": "2026-02-10T10:30:00Z",
  "updated": "2026-02-10T10:45:00Z"
}
```
```

--------------------------------

### Get Processing Status (v2)

Source: https://docs.mapflow.ai/api/mapflow_api.html

Retrieves the status and details of a specific processing job using its ID.

```json
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Downtown Buildings",
  "status": "OK",
  "percentCompleted": 100,
  "area": 1200000,
  "cost": 150,
  "vectorLayer": {
    "id": "layer-uuid",
    "tileUrl": "https://app.mapflow.ai/api/layers/{z}/{x}/{y}.pbf"
  },
  "created": "2026-02-10T10:30:00Z",
  "updated": "2026-02-10T10:45:00Z"
}

```

--------------------------------

### Configure Custom XYZ Tile Service

Source: https://docs.mapflow.ai/api/mapflow_api.html

Use your own XYZ, TMS, or WMS tile service by defining source parameters. Authentication credentials can be provided if required.

```json
{
  "sourceParams": {
    "userDefined": {
      "sourceType": "XYZ",
      "url": "https://tiles.example.com/{z}/{x}/{y}.png",
      "zoom": 18,
      "crs": "EPSG:3857",
      "rasterLogin": "username",
      "rasterPassword": "password"
    }
  }
}
```

--------------------------------

### Create Project

Source: https://docs.mapflow.ai/userguides/use_API.html

This snippet shows how to create a new project using the Mapflow API, which can help organize processing tasks.

```APIDOC
## Create the project (it’s optional)

### Description
This API method allows you to create a new project to organize your processing tasks. Projects help in managing related processing jobs.

### Method
POST

### Endpoint
https://api.mapflow.ai/rest/projects

### Parameters
#### Request Body
- **name** (string) - Required - The name of the new project.

### Request Example
```json
{
    "name": "My new project"
}
```

### Response
#### Success Response (200)
Returns the details of the created project, including its ID.

#### Response Example
```json
{
    "id": "fb49b97e-51ec-4b31-872f-d1411284de85",
    "name": "My new project",
    ...
}
```
```

--------------------------------

### Create Project

Source: https://docs.mapflow.ai/api/mapflow_api.html

Creates a new project container for organizing processings. Projects help in managing and categorizing your analysis tasks.

```APIDOC
## POST /projects

### Description
Creates a new project container for organizing processings.

### Method
POST

### Endpoint
/projects

### Parameters
#### Request Body
- **name** (string) - Required - Project name
- **description** (string) - Optional - Project description

### Request Example
```json
{
  "name": "Urban Analysis 2026",
  "description": "Building footprints for city planning"
}
```

### Response
#### Success Response (200)
- **id** (string) - Description
- **name** (string) - Description
- **description** (string) - Description

#### Response Example
```json
{
  "id": "546d148f-19a1-40d8-8f16-d1e6dabfd204",
  "name": "Urban Analysis 2026",
  "description": "Building footprints for city planning"
}
```
```

--------------------------------

### Get Processing History

Source: https://docs.mapflow.ai/api/mapflow_api.html

Retrieves processing history with support for pagination and filtering. The response format can be JSON or CSV.

```json
{
  "page": 1,
  "perPage": 50,
  "sort": "created:desc",
  "filter": "status=OK"
}

```

--------------------------------

### Create a New Project with Mapflow API

Source: https://docs.mapflow.ai/userguides/use_API.html

Create a new project to organize your processing tasks. This is optional but recommended for better management. The response will contain the project ID.

```python
import requests
import json

url = "https://api.mapflow.ai/rest/projects"
headers = {
    'Content-Type': 'application/json'
    }

payload = json.dumps({
        "name": "My new project"  # Your project name
    })

response = requests.request("POST", url, headers=headers, auth=(username,password), data=payload)

if  response.status_code == 200:
    print(response.text)
else:
    print(f"Request failed")
    print(response.text)
```

--------------------------------

### Get Processing Status

Source: https://docs.mapflow.ai/api/processing_api.html

Retrieve the current status of a specific geospatial processing task using its unique processing ID.

```APIDOC
## GET /processings/{processing-uuid}/v2

### Description
Retrieves the status of a specific processing task.

### Method
GET

### Endpoint
https://api.mapflow.ai/rest/processings/{processing-uuid}/v2

### Parameters
#### Path Parameters
- **processing-uuid** (string) - Required - The unique identifier of the processing task.

### Request Headers
- Authorization: Bearer YOUR_TOKEN
```

--------------------------------

### Get Images in Mosaic

Source: https://docs.mapflow.ai/api/mapflow_api.html

Retrieves a list of all images within a specified mosaic, including their metadata. Requires the mosaic ID.

```json
[
  {
    "id": "6ae7f9e9-da2d-41e0-b16f-83396003af57",
    "filename": "area-1101712.tif",
    "file_size": 68417439,
    "uploaded_at": "2024-03-15T10:35:00Z",
    "footprint": "POLYGON((1.9915 48.7643, ...))",
    "preview_url_s": "https://api.mapflow.ai/rest/rasters/image/{id}/preview/s",
    "preview_url_l": "https://api.mapflow.ai/rest/rasters/image/{id}/preview/l",
    "meta_data": {
      "crs": "EPSG:32631",
      "width": 5589,
      "height": 4079,
      "count": 3,
      "pixel_size": [0.3, 0.3]
    }
  }
]


```

--------------------------------

### Custom URL Tile Service Configuration

Source: https://docs.mapflow.ai/api/mapflow_api.html

Configure a custom tile service using XYZ, TMS, or WMS protocols by providing the URL and other parameters.

```APIDOC
## Custom URL Tile Service

Use your own XYZ/TMS/WMS tile service.

### Parameters

#### `sourceParams.userDefined`

- **`sourceType`** (string) - Required - Specifies the tile service type (`XYZ`, `TMS`, `QUADKEY`, `SENTINEL_L2A`, `LOCAL`).
- **`url`** (string) - Required - Tile URL template.
- **`zoom`** (integer) - Optional - Zoom level.
- **`crs`** (string) - Optional - Coordinate reference system (e.g., `EPSG:3857`).
- **`rasterLogin`** (string) - Optional - Authentication username.
- **`rasterPassword`** (string) - Optional - Authentication password.

### Example Request Body

```json
{
  "sourceParams": {
    "userDefined": {
      "sourceType": "XYZ",
      "url": "https://tiles.example.com/{z}/{x}/{y}.png",
      "zoom": 18,
      "crs": "EPSG:3857",
      "rasterLogin": "username",
      "rasterPassword": "password"
    }
  }
}
```
```

--------------------------------

### Create and Run a Processing Job

Source: https://docs.mapflow.ai/api/processing_api.html

Initiate a new geospatial analysis job. Specify project details, geometry, and processing parameters. The 'wdName' parameter selects the AI model to use (e.g., '🏠 Buildings').

```curl
curl -X POST https://api.mapflow.ai/rest/processings/v2 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Downtown Buildings",
    "projectId": "project-uuid",
    "wdName": "🏠 Buildings",
    "geometry": {
      "type": "Polygon",
      "coordinates": [[
        [37.6156, 55.7558],
        [37.6256, 55.7558],
        [37.6256, 55.7608],
        [37.6156, 55.7608],
        [37.6156, 55.7558]
      ]]
    },
    "params": {
      "sourceParams": {
        "dataProvider": {
          "providerName": "Mapbox",
          "zoom": 18
        }
      }
    }
  }'
```

--------------------------------

### Create Processing (v2)

Source: https://docs.mapflow.ai/api/mapflow_api.html

Creates and runs an imagery analysis processing using the v2 API, which is recommended for its structured parameters.

```APIDOC
## POST /processings/v2

### Description
Creates and runs an imagery analysis processing.

### Method
POST

### Endpoint
/processings/v2

### Parameters
#### Request Body
- **name** (string) - Required - Processing name
- **projectId** (string) - Required - Project UUID
- **wdId** or **wdName** (string) - Required - Workflow definition ID or name (e.g., “🏠 Buildings”)
- **geometry** (GeoJSON) - Required - Area of interest (Polygon or MultiPolygon)
- **params.sourceParams** (object) - Required - Imagery source configuration (see Data Sources)
- **params.inferenceParams** (object) - Optional - Model-specific parameters
- **blocks** (array) - Optional - Enable/disable workflow steps (see Workflow Blocks)
- **description** (string) - Optional - Processing description
- **meta** (object) - Optional - Custom metadata

### Request Example: Using Mapbox
```json
{
  "name": "Downtown Buildings",
  "projectId": "546d148f-19a1-40d8-8f16-d1e6dabfd204",
  "wdName": "🏠 Buildings",
  "geometry": {
    "type": "Polygon",
    "coordinates": [[[37.615, 55.755], [37.625, 55.755],
                     [37.625, 55.760], [37.615, 55.760],
                     [37.615, 55.755]]]
  },
  "params": {
    "sourceParams": {
      "dataProvider": {
        "providerName": "Mapbox",
        "zoom": 18
      }
    }
  }
}
```

### Request Example: Using Custom Imagery
```json
{
  "name": "Aerial Survey 2026",
  "projectId": "546d148f-19a1-40d8-8f16-d1e6dabfd204",
  "wdName": "🏠 Buildings",
  "geometry": {"type": "Polygon", "coordinates": [...]},
  "params": {
    "sourceParams": {
      "myImagery": {
        "imageIds": ["0c26a0d3-96d8-4ed5-aa62-3843d1d7905c"]
      }
    }
  }
}
```

### Response
#### Success Response (200)
- **id** (string) - Description
- **name** (string) - Description
- **status** (string) - Description
- **percentCompleted** (number) - Description
- **cost** (number) - Description
- **created** (string) - Description

#### Response Example
```json
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Downtown Buildings",
  "status": "IN_PROGRESS",
  "percentCompleted": 0,
  "cost": 150,
  "created": "2026-02-10T10:30:00Z"
}
```
```

--------------------------------

### Get Images in Mosaic

Source: https://docs.mapflow.ai/api/mapflow_api.html

Lists all images within a specified mosaic, including their metadata. This is useful for retrieving a collection of related image files.

```APIDOC
## GET /rasters/mosaic/{mosaic_id}/image

### Description
Lists all images in a mosaic with metadata.

### Method
GET

### Endpoint
/rasters/mosaic/{mosaic_id}/image

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the image.
- **filename** (string) - The name of the image file.
- **file_size** (integer) - The size of the image file in bytes.
- **uploaded_at** (string) - Timestamp when the image was uploaded.
- **footprint** (string) - The geographic boundary of the image.
- **preview_url_s** (string) - URL for a small preview of the image.
- **preview_url_l** (string) - URL for a large preview of the image.
- **meta_data** (object) - Contains detailed metadata about the image.
  - **crs** (string) - Coordinate reference system.
  - **width** (integer) - Image width in pixels.
  - **height** (integer) - Image height in pixels.
  - **count** (integer) - Number of bands in the image.
  - **pixel_size** (array) - Array containing pixel size in x and y dimensions.

#### Response Example
```json
[
  {
    "id": "6ae7f9e9-da2d-41e0-b16f-83396003af57",
    "filename": "area-1101712.tif",
    "file_size": 68417439,
    "uploaded_at": "2024-03-15T10:35:00Z",
    "footprint": "POLYGON((1.9915 48.7643, ...))",
    "preview_url_s": "https://api.mapflow.ai/rest/rasters/image/{id}/preview/s",
    "preview_url_l": "https://api.mapflow.ai/rest/rasters/image/{id}/preview/l",
    "meta_data": {
      "crs": "EPSG:32631",
      "width": 5589,
      "height": 4079,
      "count": 3,
      "pixel_size": [0.3, 0.3]
    }
  }
]
```
```

--------------------------------

### My Imagery - Mosaic Configuration

Source: https://docs.mapflow.ai/api/mapflow_api.html

Configures the data source to use a mosaic of multiple uploaded images. Requires `imageIds` and optionally `mosaicId`.

```json
{
  "sourceParams": {
    "myImagery": {
      "imageIds": ["img1-uuid", "img2-uuid"],
      "mosaicId": "mosaic-uuid"
    }
  }
}

```

--------------------------------

### My Imagery - Single Image Configuration

Source: https://docs.mapflow.ai/api/mapflow_api.html

Configures the data source to use a single uploaded image. Requires the `imageIds` parameter.

```json
{
  "sourceParams": {
    "myImagery": {
      "imageIds": ["image-uuid"]
    }
  }
}

```

--------------------------------

### Create and Run Processing (v2)

Source: https://docs.mapflow.ai/api/processing_api.html

Initiates a new geospatial processing task within a specified project. This includes defining the analysis area, model, and data source parameters.

```APIDOC
## POST /processings/v2

### Description
Creates and runs a new geospatial processing task.

### Method
POST

### Endpoint
https://api.mapflow.ai/rest/processings/v2

### Request Headers
- Authorization: Bearer YOUR_TOKEN
- Content-Type: application/json

### Request Body
- **name** (string) - Required - The name of the processing task.
- **projectId** (string) - Required - The ID of the project to associate with.
- **wdName** (string) - Required - The name of the workflow or model to use (e.g., "🏠 Buildings").
- **geometry** (object) - Required - The geographic area for the analysis.
  - **type** (string) - Required - Geometry type (e.g., "Polygon").
  - **coordinates** (array) - Required - Array of coordinates defining the geometry.
- **params** (object) - Optional - Parameters for the processing.
  - **sourceParams** (object) - Optional - Parameters related to the data source.
    - **dataProvider** (object) - Optional - Specifies the data provider.
      - **providerName** (string) - Required - Name of the data provider (e.g., "Mapbox").
      - **zoom** (integer) - Optional - Zoom level for imagery.

### Request Example
```json
{
  "name": "Downtown Buildings",
  "projectId": "project-uuid",
  "wdName": "🏠 Buildings",
  "geometry": {
    "type": "Polygon",
    "coordinates": [[[
      37.6156, 55.7558
    ], [
      37.6256, 55.7558
    ], [
      37.6256, 55.7608
    ], [
      37.6156, 55.7608
    ], [
      37.6156, 55.7558
    ]]]
  },
  "params": {
    "sourceParams": {
      "dataProvider": {
        "providerName": "Mapbox",
        "zoom": 18
      }
    }
  }
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the processing task.
- **status** (string) - The initial status of the processing (e.g., "IN_PROGRESS").
```

--------------------------------

### Create a Project

Source: https://docs.mapflow.ai/api/processing_api.html

Use this endpoint to create a new project for organizing your geospatial analyses. Projects created via the API are synchronized with Mapflow.ai.

```curl
curl -X POST https://api.mapflow.ai/rest/projects \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My First Project",
    "description": "Buildings detection"
  }'
```

--------------------------------

### Get Image Metadata

Source: https://docs.mapflow.ai/api/mapflow_api.html

Retrieves detailed metadata for a specific image using its ID. Includes information like filename, size, footprint, and processing details.

```json
{
  "id": "6ae7f9e9-da2d-41e0-b16f-83396003af57",
  "filename": "orthophoto.tif",
  "file_size": 68417439,
  "uploaded_at": "2024-03-15T10:35:00Z",
  "footprint": "POLYGON((...))",
  "meta_data": {
    "crs": "EPSG:32631",
    "width": 5589,
    "height": 4079,
    "count": 3,
    "dtypes": ["uint8", "uint8", "uint8"],
    "pixel_size": [0.3, 0.3]
  },
  "cog_link": "s3://bucket/path/cog/image.tif"
}


```

--------------------------------

### Mapflow Processing API - Authentication

Source: https://docs.mapflow.ai/api/mapflow_api.html

All Mapflow Processing API requests require an API token for authentication. This example demonstrates how to include the token in the request header.

```APIDOC
### Authentication

All API requests require an API token. Generate yours in profile settings.

```curl
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://api.mapflow.ai/rest/user/status
```

See authorization guide for details.
```

--------------------------------

### Mapflow Data API - Authentication

Source: https://docs.mapflow.ai/api/mapflow_api.html

All Mapflow Data API requests require an API token for authentication. This example shows how to authenticate a request to the /rasters/memory endpoint.

```APIDOC
### Authentication

All API requests require an API token. Generate yours in profile settings.

```curl
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://api.mapflow.ai/rest/rasters/memory
```

See authorization guide for details.
```

--------------------------------

### Imagery Search Configuration

Source: https://docs.mapflow.ai/api/mapflow_api.html

Configures the data source to search and use imagery from commercial providers. Requires `dataProvider`, `imageIds`, and `zoom`.

```json
{
  "sourceParams": {
    "imagerySearch": {
      "dataProvider": "maxar",
      "imageIds": ["image-uuid"],
      "zoom": 18
    }
  }
}

```

--------------------------------

### Get Image Metadata

Source: https://docs.mapflow.ai/api/mapflow_api.html

Retrieves detailed metadata for a specific image using its unique identifier. This endpoint provides comprehensive information about an individual image file.

```APIDOC
## GET /rasters/image/{image_id}

### Description
Retrieves detailed metadata for a specific image.

### Method
GET

### Endpoint
/rasters/image/{image_id}

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the image.
- **filename** (string) - The name of the image file.
- **file_size** (integer) - The size of the image file in bytes.
- **uploaded_at** (string) - Timestamp when the image was uploaded.
- **footprint** (string) - The geographic boundary of the image.
- **meta_data** (object) - Contains detailed metadata about the image.
  - **crs** (string) - Coordinate reference system.
  - **width** (integer) - Image width in pixels.
  - **height** (integer) - Image height in pixels.
  - **count** (integer) - Number of bands in the image.
  - **dtypes** (array) - Array of data types for each band.
  - **pixel_size** (array) - Array containing pixel size in x and y dimensions.
- **cog_link** (string) - Link to the Cloud Optimized GeoTIFF (COG) version of the image.

#### Response Example
```json
{
  "id": "6ae7f9e9-da2d-41e0-b16f-83396003af57",
  "filename": "orthophoto.tif",
  "file_size": 68417439,
  "uploaded_at": "2024-03-15T10:35:00Z",
  "footprint": "POLYGON((...))",
  "meta_data": {
    "crs": "EPSG:32631",
    "width": 5589,
    "height": 4079,
    "count": 3,
    "dtypes": ["uint8", "uint8", "uint8"],
    "pixel_size": [0.3, 0.3]
  },
  "cog_link": "s3://bucket/path/cog/image.tif"
}
```
```
Tokens:
Raw