> For the complete documentation index, see [llms.txt](https://docs.lumidb.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.lumidb.com/import-data/import-data-with-the-api.md).

# Import data with the API

Upload point clouds and rasters and import them as datasets from your own code.

Use the API to import point clouds, rasters and photos from scripts and pipelines. For a one-off upload, use the import dialog in the app. See [Importing data](https://docs.lumidb.com/import-data/importing-data.md). Vector files, such as GeoJSON, are imported in the app.

An import has three steps: upload the file, start the import, and wait until it is ready. All requests go to `https://api.lumidb.com/api` and need an [API key](https://docs.lumidb.com/archive-management/api-keys.md). The [API quickstart](https://docs.lumidb.com/api-reference/quickstart-your-first-api-request.md) shows how to send one.

### Before you start

* Check that LumiDB accepts your file. See [Supported formats and file requirements](https://docs.lumidb.com/import-data/supported-formats-and-file-requirements.md).
* Find out the coordinate reference system of the file, and decide which one the dataset is stored in. See [Coordinate systems and projections](https://docs.lumidb.com/import-data/coordinate-systems-and-projections.md).

### 1. Upload the file

Create an asset. LumiDB returns a URL to upload the file to.

```sh
curl -X POST https://api.lumidb.com/api/assets/upload \
  -H "Authorization: apikey lumi_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"filename": "scan.laz", "client_modified_at": "2026-10-25T08:00:00Z"}'
```

```json
{
  "asset_id": "01a17233-2dcf-7f32-b498-5f53e1d6c844",
  "expiration_seconds": 86400,
  "upload_type": "single",
  "upload_url": "https://storage.example/presigned-upload-url"
}
```

Send the file to `upload_url` with a `PUT` request. Don't send your API key to this URL. It is already signed.

```sh
curl -X PUT "https://storage.example/presigned-upload-url" --data-binary @scan.laz
```

Then tell LumiDB that the upload is finished. This records the size of the file.

```sh
curl -X POST https://api.lumidb.com/api/assets/01a17233-2dcf-7f32-b498-5f53e1d6c844/complete \
  -H "Authorization: apikey lumi_your_key_here"
```

The upload URL works for 24 hours (`expiration_seconds`). To get a new upload URL for an asset, send `GET /assets/{asset_id}/upload-url`. LumiDB answers `409` once the file has been uploaded, or after the 24 hours have passed.

### 2. Start the import

Post a manifest that names the dataset and says which assets to import.

```sh
curl -X POST https://api.lumidb.com/api/tables/import \
  -H "Authorization: apikey lumi_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "table_name": "my_scan",
    "table_proj": "EPSG:3067",
    "inputs": [{ "id": "01a17233-2dcf-7f32-b498-5f53e1d6c844", "proj": "EPSG:3067" }]
  }'
```

The response comes back at once. The import runs in the background.

```json
{
  "table_version": "01a17233-3210-7000-854b-e8c8fb4e0023",
  "status": { "status": "queued", "updated_at": "2026-10-25T08:35:20.210445499Z" },
  "status_url": "https://api.lumidb.com/api/tables/import_status/01a17233-3210-7000-854b-e8c8fb4e0023"
}
```

| Field           | What it means                                                                                                                                         |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `table_name`    | The name of the dataset. If a dataset with this name exists, the import replaces it and doesn't create a second dataset. Use a new name to keep both. |
| `table_proj`    | The coordinate reference system the dataset is stored in. LumiDB converts every input into it.                                                        |
| `inputs[].id`   | The `asset_id` of an uploaded file.                                                                                                                   |
| `inputs[].proj` | The coordinate reference system of the file. If you leave it out, LumiDB uses the one the file declares, then `input_proj`, then `table_proj`.        |
| `input_proj`    | Optional. The system to assume for files that don't declare one.                                                                                      |
| `strict_mode`   | Optional. When `true`, a file without a coordinate reference system fails the import, and LumiDB doesn't assume `table_proj`.                         |

You can import several files into one dataset by listing more than one input. Write a coordinate reference system as an EPSG code, such as `EPSG:3067`.

{% hint style="warning" %}
A file that declares no coordinate reference system, such as an ASCII file, imports into the wrong place if you leave out `proj` and its coordinates are not in `table_proj`. Set `strict_mode` to `true` to make LumiDB reject such files.
{% endhint %}

### 3. Wait until the import is ready

Request the `status_url` until `status` is `ready`, `failed` or `cancelled`. Every few seconds is enough.

```sh
curl https://api.lumidb.com/api/tables/import_status/01a17233-3210-7000-854b-e8c8fb4e0023 \
  -H "Authorization: apikey lumi_your_key_here"
```

| `status`     | What it means                                                                                                                 |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| `queued`     | The import is waiting to start.                                                                                               |
| `processing` | LumiDB is importing the file. `progress` is a percentage and `phase` says what it is doing, for example `Finalizing dataset`. |
| `ready`      | The dataset is available.                                                                                                     |
| `failed`     | The import failed. `error_msg` says why.                                                                                      |
| `cancelled`  | Someone cancelled the import.                                                                                                 |

```json
{ "status": "failed", "updated_at": "2026-10-25T08:38:39.270761Z", "error_msg": "Invalid input: No points found in input files" }
```

When the status is `ready`, the dataset appears in the response of `GET /datasets`. See the [API quickstart](https://docs.lumidb.com/api-reference/quickstart-your-first-api-request.md).

### Import a raster

Rasters use the same upload and the same manifest. Start the import with `POST /rasters/import`.

```sh
curl -X POST https://api.lumidb.com/api/rasters/import \
  -H "Authorization: apikey lumi_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "table_name": "my_orthophoto",
    "table_proj": "EPSG:3067",
    "inputs": [{ "id": "01a17233-ff09-7440-893b-31ac97652063" }]
  }'
```

The response names the raster and gives a `status_url`. Request it the same way as for a point cloud.

```json
{
  "raster_name": "my_orthophoto",
  "raster_version_id": "01a17234-030d-7b30-be4e-408fbb437981",
  "status": { "status": "queued", "updated_at": "2026-10-25T08:36:13.710653777Z" },
  "status_url": "https://api.lumidb.com/api/rasters/import_status/01a17234-030d-7b30-be4e-408fbb437981"
}
```

### Import photos as an imageset

Photos use the same upload as point clouds: create an asset for each JPEG or TIFF file and upload the file to its URL. Then start the import with `POST /imagesets/import`. The manifest names the imageset and the project it goes into. The project ID is the last part of the project's address in the app.

```sh
curl -X POST https://api.lumidb.com/api/imagesets/import \
  -H "Authorization: apikey lumi_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Drone flight",
    "project_id": "01a17233-0000-7000-8000-000000000000",
    "inputs": [
      { "id": "01a17233-2dcf-7f32-b498-5f53e1d6c844" },
      { "id": "01a17233-2dd0-7a11-9c35-0d6f1ee0a1b2" }
    ]
  }'
```

The response comes back at once, and the import runs in the background. Request the `status_url` as for a point cloud, until `status` is `ready`, `failed` or `cancelled`.

```json
{
  "imageset_id": "01a17234-5a10-7c20-8d11-2b5e9f0c3a44",
  "status": { "status": "queued", "updated_at": "2026-11-17T12:24:34.788Z" },
  "status_url": "https://api.lumidb.com/api/imagesets/import_status/01a17234-5a10-7c20-8d11-2b5e9f0c3a44"
}
```

| Field           | What it means                                                                                                                                                                                       |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`          | The name of the imageset.                                                                                                                                                                           |
| `project_id`    | The project to import into.                                                                                                                                                                         |
| `inputs[].id`   | The `asset_id` of an uploaded photo.                                                                                                                                                                |
| `inputs[].proj` | Optional. The coordinate reference system of the photo's position, if the file declares none.                                                                                                       |
| `input_proj`    | Optional. The coordinate reference system to assume for photos that declare no height reference. EXIF positions are longitude and latitude, so it must be a geographic system such as `EPSG:4979`.  |
| `strict_mode`   | Optional. When `true`, the import fails if a file can't be read, or if a photo has no height reference from `proj`, its metadata or `input_proj`. Otherwise LumiDB assumes heights above sea level. |
| `user_metadata` | Optional. An object with your own metadata for the imageset.                                                                                                                                        |

LumiDB skips files that aren't JPEG or TIFF photos. `GET /imagesets/{imageset_id}` returns the skipped files in `rejected_assets`, each with a `reason`, for example `not a JPEG or TIFF file`. It also returns `image_count`, `located_count`, `captured_from`, `captured_to` and `bounds_wgs84`.

#### List the photos

`GET /imagesets/{imageset_id}/images` returns the photos in the order they were taken.

```sh
curl https://api.lumidb.com/api/imagesets/01a17234-5a10-7c20-8d11-2b5e9f0c3a44/images \
  -H "Authorization: apikey lumi_your_key_here"
```

```json
[
  {
    "image_id": "01a17234-5b02-7d4e-a1c3-6e7f8091a2b3",
    "asset_id": "01a17233-2dcf-7f32-b498-5f53e1d6c844",
    "filename": "IMG_0001.jpg",
    "captured_at": "2026-11-10T10:00:00",
    "position": [24.94, 60.17, 112.88],
    "yaw_deg": 90.0,
    "pitch_deg": -90.0,
    "roll_deg": 0.0,
    "projection": "perspective",
    "metadata": { "make": "DocsCam", "model": "Test" },
    "has_preview": true
  }
]
```

`position` is longitude, latitude and height in `EPSG:4979` by default, or `null` for a photo without a position. Add `?proj=EPSG:3067` to get the positions in another coordinate reference system. For a system without a vertical datum, such as `EPSG:3857`, the heights are above sea level.

#### Preview and original

* `GET /imagesets/{imageset_id}/images/{image_id}/preview` returns the preview JPEG that the camera embedded in the photo, about 960 pixels wide. It returns `404` when `has_preview` is `false`.
* `GET /imagesets/{imageset_id}/images/{image_id}/download` returns a `url` for downloading the original file, and its `filename`.

#### Rename or delete an imageset

Send `PATCH /imagesets/{imageset_id}` with a new `name`, or with `user_metadata` as a JSON merge patch. Send `DELETE /imagesets/{imageset_id}` to delete the imageset and its images. The assets that hold the uploaded files stay. Delete them with `DELETE /assets/{asset_id}` if you don't need them.

### Import a dataset again

To run an import again with the manifest of the dataset's newest version, post to `/tables/{table_name}/reimport` for a point cloud or `/rasters/{raster_name}/reimport` for a raster. This is what **Re-process** does in the app. LumiDB makes a new version of the dataset, and the response has the same shape as an import response, with a `status_url` to request.

```sh
curl -X POST https://api.lumidb.com/api/tables/my_scan/reimport \
  -H "Authorization: apikey lumi_your_key_here"
```

### Names of datasets you import in the app

The app doesn't replace a dataset when you import a second one with the same name. It adds a date and time to the name that LumiDB stores, for example `my-scan-20261113-103151`, and shows the name you typed as `display_name`. `GET /datasets` returns both. Use `name`, not `display_name`, in requests such as `DELETE`.

### Download an original file

Organization admins can download an uploaded file again. Send `GET /assets/{asset_id}/download`. The response has a `url` that works for one hour and keeps the original file name.

### Large files

A single upload takes files up to 5 GiB. For larger files, create the asset with `"mode": "multipart"` and the exact `content_length`. LumiDB then returns one upload URL for each part. See `POST /assets/upload` in the API reference.

### Delete a dataset

Delete a point cloud by its `name`, and a raster the same way. Take the `name` from `GET /datasets`.

```sh
curl -X DELETE https://api.lumidb.com/api/tables/my_scan \
  -H "Authorization: apikey lumi_your_key_here"

curl -X DELETE https://api.lumidb.com/api/rasters/my_orthophoto \
  -H "Authorization: apikey lumi_your_key_here"
```

{% hint style="danger" %}
Deleting removes the dataset. Check the name before you send the request.
{% endhint %}

### A complete example

This Python script uploads a file, starts the import and waits for the result. It reads the key from the environment variable `LUMIDB_API_KEY`.

```python
import datetime
import os
import time

import requests

BASE = "https://api.lumidb.com/api"
headers = {"Authorization": f"apikey {os.environ['LUMIDB_API_KEY']}"}

path = "scan.laz"
now = datetime.datetime.now(datetime.timezone.utc).isoformat()

# 1. Create the asset and upload the file
asset = requests.post(
    f"{BASE}/assets/upload",
    headers=headers,
    json={"filename": os.path.basename(path), "client_modified_at": now},
).json()
with open(path, "rb") as f:
    requests.put(asset["upload_url"], data=f).raise_for_status()
requests.post(f"{BASE}/assets/{asset['asset_id']}/complete", headers=headers).raise_for_status()

# 2. Start the import
manifest = {
    "table_name": "my_scan",
    "table_proj": "EPSG:3067",
    "inputs": [{"id": asset["asset_id"], "proj": "EPSG:3067"}],
}
job = requests.post(f"{BASE}/tables/import", headers=headers, json=manifest).json()

# 3. Wait until the import is ready or failed
while True:
    status = requests.get(job["status_url"], headers=headers).json()
    print(status["status"], status.get("progress"))
    if status["status"] in ("ready", "failed"):
        break
    time.sleep(3)
if status["status"] == "failed":
    raise SystemExit(status["error_msg"])
print("Imported", manifest["table_name"])
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.lumidb.com/import-data/import-data-with-the-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
