BSA_SLAM_API Manual

WEB HTTP API User Guide

About This Document

This document describes the APIs, parameters, responses, and invocation flows exposed by the WEB service.

Scope of Exposed Capabilities

The WEB service exposes the following capabilities:

Addresses and Common Conventions

Example Addresses

All examples in this document use the following addresses:

WEB_BASE="http://192.168.1.88:18080"
UPLOAD_BASE="http://192.168.1.88:1080"
TOKEN="<登录成功后得到的token>"

Notes:

WEB_BASE is the address of the WEB HTTP service.

UPLOAD_BASE is used only when large file upload is enabled.

The examples use ports 18080 and 1080; the ports used in an actual deployment depend on the on-site configuration.

Path Prefixes

Authentication

Account Rules

The account rules are as follows:

Additional notes:

Only one valid root session is retained at any given time.

Logging in as root again immediately invalidates the previous root token.

Time Formats

Response Types

Business Error Codes

The following table lists the main business codes returned by the APIs:

WEB API Summary

Authentication

Monitoring and Control

Startup Parameters, Calibration Parameters, and Maps

Logs and OTA

API Details

Login

Request example:

curl -sS -X POST "${WEB_BASE}/api/v1/auth/login" \
-H "Content-Type: application/json" \
-d '{"username":"root","password":"root"}'

Success response example:

{
"code": 0,
"data": {
"token": "0123456789abcdef0123456789abcdef",
"role": "root"
}
}

Failure details:

Sequence diagram

sequenceDiagram
    autonumber
    actor User
    participant Caller
    participant WEBAPI

    User->>Caller: Enter username and password
    Caller->>WEBAPI: POST /api/v1/auth/login
    WEBAPI-->>Caller: code=0 + token/role
    Caller-->>User: Login successful

Logout

Path

/api/v1/auth/logout

Authentication

Bearer Token

Request body

May be empty

Success response

200 + code=0

Request example:

curl -sS -X POST "${WEB_BASE}/api/v1/auth/logout" \
-H "Authorization: Bearer ${TOKEN}"

Sequence diagram

sequenceDiagram
actor User
participant Caller
participant WEBAPI
User->>Caller: Initiate logout
Caller->>WEBAPI: POST /api/v1/auth/logout
WEBAPI-->>Caller: code=0
Caller-->>User: Return token invalidation status

Query Real-Time Localization and Status

Permissions

Any logged-in user

Success response

200 + code=0

Request example:

curl -sS "${WEB_BASE}/api/v1/monitor/localization" \
-H "Authorization: Bearer ${TOKEN}"

Success response example:

{
"code": 0,
"data": {
"timestamp": "2026-03-28T09:50:00Z",
"system_status": "normal",
"position": {
"x": 12.345,
"y": -3.21,
"z": 1.56
},
"orientation": {
"q1": 0.0,
"q2": 0.0,
"q3": 1.0,
"q4": 0.0
},
"velocity": {
"vx": 0.12,
"vy": 0.01,
"vz": 0.0
},
"obstacles": {
"sector": [
1.10, 1.20, 1.35, 1.50, 1.65, 1.80,
1.95, 2.10, 2.25, 2.40, 2.55, 2.70,
2.85, 3.00, 3.15, 3.30, 3.45, 3.60,
3.75, 3.90, 4.05, 4.20, 4.35, 4.50,
4.65, 4.80, 4.95, 5.10, 5.25, 5.40,
5.55, 5.70, 5.85, 6.00, 6.15, 6.30
]
},
"confidence": 0.98,
"sensors": [
{
"name": "mid_360",
"type": "lidar",
"status": "active"
},
{
"name": "camera_front",
"type": "camera",
"status": "inactive"
}
],
"system_resources": {
"cpu": {
"usage_percent": 18.4,
"temperature_celsius": 52.3
},
"memory": {
"available_bytes": 5120000000,
"used_bytes": 3268608000
},
"disk": {
"available_bytes": 41000000000,
"used_bytes": 23000000000
}
}
}
}

Field descriptions:

The obstacles.sector indices are interpreted as follows:

sector[9]

Near the left side, covering 90° to 100°

sector[18]

Near directly behind, covering 180° to 190°

sector[27]

Near the right side, covering 270° to 280°

sector[35]

The last sector before returning to directly ahead, covering 350° to 360°

Sequence diagram

sequenceDiagram
actor User
participant Caller
participant WEBAPI
User->>Caller: Initiate real-time status query
Caller->>WEBAPI: GET /api/v1/monitor/localization
WEBAPI-->>Caller: code=0 + data
Caller-->>User: Display localization and status information

Control Plugin Status

Request example:

curl -sS -X POST "${WEB_BASE}/api/v1/plugins/control" \
-H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" \
-d '{"plugin_name":"SLAM","action":"restart"}'

Success response example:

{
"code": 0,
"data": {
"plugin_name": "SLAM",
"action": "restart"
}
}

Failure details:

Sequence diagram

sequenceDiagram
actor Administrator
participant Caller
participant WEBAPI
Administrator->>Caller: Select the target plugin and action
Caller->>WEBAPI: POST /api/v1/plugins/control
WEBAPI-->>Caller: code=0 + plugin_name/action
Caller-->>Administrator: Display the control result

Query startup / calibration / map Lists

Request example:

curl -sS "${WEB_BASE}/api/v1/config/startup/files/list" \
-H "Authorization: Bearer ${TOKEN}"

startup list example:

{
"code": 0,
"data": {
"items": [
{
"file_name": "startup_default.yaml",
"is_active": true
},
{
"file_name": "startup_mapping.yaml",
"is_active": false
}
]
}
}

map list example:

{
"code": 0,
"data": {
"items": [
{
"description": "active map",
"dir": "map_example_1",
"bin": "map.bin",
"pcd": "map.pcd",
"is_active": true
}
]
}
}

Sequence diagram

sequenceDiagram
actor User
participant Caller
participant WEBAPI
User->>Caller: Initiate a resource list query
Caller->>WEBAPI: GET list API
WEBAPI-->>Caller: code=0 + items
Caller-->>User: Display the list and the currently active item

Switch the Currently Active Resource

startup

/api/v1/config/startup/files/active

{"file_name":"startup_mapping.yaml"}

calibration

/api/v1/calibration/files/active

{"file_name":"calib_next.yaml"}

map

/api/v1/maps/packages/active

{"dir":"map_example_2"}

Notes:

All three APIs require root.

On success, the name of the target that was just activated is echoed in the response.

If the target does not exist or cannot be activated, the response is 200 + code=1401.

Sequence diagram

sequenceDiagram
actor Administrator
participant Caller
participant WEBAPI
Administrator->>Caller: Select the target resource and activate it
Caller->>WEBAPI: POST active-resource switch API
WEBAPI-->>Caller: code=0 + target name
Caller-->>Administrator: Indicate that the switch succeeded

Upload Small startup / calibration Files

Request example:

FILE="startup_mapping.yaml"
SHA256="$(sha256sum "${FILE}" | awk '{print $1}')"
curl -sS -X POST "${WEB_BASE}/api/v1/config/startup/files/upload" \
-H "Authorization: Bearer ${TOKEN}" \
-F "sha256=${SHA256}" \
-F "file=@${FILE}"

Success response example:

{
"code": 0,
"data": {
"file_name": "startup_mapping.yaml",
"file_size": 128,
"sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
}
}

Failure details:

400

1001

Missing form field, invalid file name, or empty sha256

200

1201

SHA256 mismatch, or YAML validation/import failure

Sequence diagram

sequenceDiagram
actor Administrator
participant Caller
participant WEBAPI
Administrator->>Caller: Select a startup or calibration file
Caller->>Caller: Calculate SHA-256
Caller->>WEBAPI: POST file upload API<br/>multipart(file, sha256)
WEBAPI-->>Caller: code=0 + upload result
Caller-->>Administrator: Indicate upload success or failure

Download startup / calibration / map Resources

Notes:

The map download API returns a ZIP file stream, and the downloaded file name is fixed as {dir}.zip.

The map HEAD preflight returns only the download headers and no response body.

startup/calibration downloads return X-File-Sha256; map downloads do not return this header.

Download example:

curl -sS -OJ -D startup_headers.txt \
"${WEB_BASE}/api/v1/config/startup/files/download/startup_default.yaml" \
-H "Authorization: Bearer ${TOKEN}"

Sequence diagram

sequenceDiagram
actor User
participant Caller
participant WEBAPI
User->>Caller: Initiate download
Caller->>WEBAPI: GET download API
WEBAPI-->>Caller: File stream + response headers
Caller-->>User: Save the file

Delete startup / calibration / map Resources

Response rules:

Sequence diagram

sequenceDiagram
actor Administrator
participant Caller
participant WEBAPI
Administrator->>Caller: Initiate deletion
Caller->>WEBAPI: DELETE API
WEBAPI-->>Caller: code=0 or error code
Caller-->>Administrator: Display the deletion result

Set Mapping Mode

Request example:

curl -sS -X POST "${WEB_BASE}/api/v1/config/startup/mode" \
-H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" \
-d '{"mapping":true}'

Success response example:

{
"code": 0,
"data": {
"mapping": true
}
}

Sequence diagram

sequenceDiagram
actor Administrator
participant Caller
participant WEBAPI
Administrator->>Caller: Switch mapping mode
Caller->>WEBAPI: POST /api/v1/config/startup/mode
WEBAPI-->>Caller: code=0 + mapping
Caller-->>Administrator: Display the setting result

Export Logs

Additional notes:

The units parameter in the request has no effect and can be ignored.

Request example:

curl -sS -OJ -D log_headers.txt \
"${WEB_BASE}/api/v1/logs/exports?start_time=2026-03-28T00:00:00Z&end_time=2026-03-28T12:30:00Z" \
-H "Authorization: Bearer ${TOKEN}"

Downloaded file naming rules:

Failure details:

Sequence diagram

sequenceDiagram
actor User
participant Caller
participant WEBAPI
User->>Caller: Select the log start and end times
Caller->>WEBAPI: GET /api/v1/logs/exports?start_time=...&end_time=...
WEBAPI-->>Caller: Log file stream
Caller-->>User: Download the log file

List, Delete, and Install OTA Packages

All OTA-related APIs are restricted to root.

Query the OTA Package List

curl -sS "${WEB_BASE}/api/v1/ota/packages/list" \
-H "Authorization: Bearer ${TOKEN}"

Response example:

{
"code": 0,
"data": {
"items": [
{
"file_name": "ota_update.deb"
}
]
}
}

Sequence diagram

sequenceDiagram
actor Administrator
participant Caller
participant WEBAPI
Administrator->>Caller: Open the OTA package list
Caller->>WEBAPI: GET /api/v1/ota/packages/list
WEBAPI-->>Caller: code=0 + items
Caller-->>Administrator: Display the OTA package list

Delete an OTA Package

curl -sS -X DELETE "${WEB_BASE}/api/v1/ota/packages/ota_update.deb" \
-H "Authorization: Bearer ${TOKEN}"

Response rules:

Sequence diagram

sequenceDiagram
actor Administrator
participant Caller
participant WEBAPI
Administrator->>Caller: Delete an OTA package
Caller->>WEBAPI: DELETE /api/v1/ota/packages/{package_name}
WEBAPI-->>Caller: code=0 or error code
Caller-->>Administrator: Display the deletion result

Create an OTA Installation Task

curl -sS -X POST "${WEB_BASE}/api/v1/ota/tasks" \
-H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" \
-d '{"package_name":"ota_update.deb"}'

Success response example:

{
"code": 0,
"data": {
"task_id": "t_ota_001"
}
}

Notes:

• Success only indicates that the installation action has been initiated successfully; it does not mean that the upgrade is complete.

An invalid request body, invalid package name, or underlying installation failure returns 200 + code=1703.

Sequence diagram

sequenceDiagram
actor Administrator
participant Caller
participant WEBAPI
Administrator->>Caller: Select an OTA package and click Install
Caller->>WEBAPI: POST /api/v1/ota/tasks
WEBAPI-->>Caller: code=0 + task_id
Caller-->>Administrator: Indicate that the installation action has been initiated

Optional Large File Upload Capability

Usage Instructions

After large file upload is enabled, use the following upload service address:

UPLOAD_BASE="http://192.168.1.88:1080"

Notes:

UPLOAD_BASE is used to create upload sessions, resume uploads, query offsets, and cancel uploads.

After the upload is complete, query the map list or OTA package list through WEB_BASE to confirm that the file is available.

If large file upload is not enabled on site, the APIs at UPLOAD_BASE are unavailable.

This upload API applies only to the following two types of operation:

Additional notes:

startup and calibration files do not use large file upload; use the WEB small-file upload APIs directly.

If your operation is neither “upload a map package” nor “upload an OTA installation package,” you do not need to invoke /api/v1/files/.

Mapping Between Operations and Upload Parameters

The two operations map to upload parameters as follows:

| Operation | fileType | Example uploaded file | Permissions |

|:---:|:---:|:---:|

| Map package upload | map | map_example_2.zip | root |

| OTA package upload | ota | ota_update.deb | root |

Notes:

When uploading, ensure that fileType matches the intended use of the file.

Create an Upload Session

FILE="map_example_2.zip"
SIZE="$(stat -c %s "${FILE}")"
META_FILENAME="$(printf '%s' "${FILE}" | base64 -w0)"
META_TYPE="$(printf '%s' "map" | base64 -w0)"
curl -i -X POST "${UPLOAD_BASE}/api/v1/files/" \
-H "Authorization: Bearer ${TOKEN}" \
-H "Tus-Resumable: 1.0.0" \
-H "Upload-Length: ${SIZE}" \
-H "Upload-Metadata: filename ${META_FILENAME},fileType ${META_TYPE}" \
-H "Content-Length: 0"

A successful request typically returns:

201 Created

Location: /api/v1/files/...

To upload an OTA package, simply change fileType in Upload-Metadata to ota and change the file name to the corresponding OTA package name.

Sequence diagram

sequenceDiagram
actor Administrator
participant Caller
participant LargeFileUploadService
Administrator->>Caller: Select a map package or OTA package
Caller->>LargeFileUploadService: POST /api/v1/files/
LargeFileUploadService-->>Caller: 201 Created + Location
Caller-->>Administrator: Save Location for the subsequent upload

Resume an Upload, Query the Offset, or Cancel

Notes:

All three operations access the upload service at UPLOAD_BASE, not WEB_BASE.

After the upload is complete, query the WEB list API to confirm that the file is available.

Sequence diagram

sequenceDiagram
actor Administrator
participant Caller
participant LargeFileUploadService
alt Query offset
Caller->>LargeFileUploadService: HEAD {Location}
LargeFileUploadService-->>Caller: Upload-Offset + Upload-Length
else Resume upload
Caller->>LargeFileUploadService: PATCH {Location}
LargeFileUploadService-->>Caller: 204 No Content + Upload-Offset
else Cancel upload
Caller->>LargeFileUploadService: DELETE {Location}
LargeFileUploadService-->>Caller: 204 No Content
end

Typical Multi-API Flows

This chapter includes only workflows that combine multiple APIs.

Query Real-Time Status After Login

Invoke POST ${WEB_BASE}/api/v1/auth/login to obtain a token.

Use the token to invoke GET ${WEB_BASE}/api/v1/monitor/localization.

A response of 401 + 1004 indicates that the token has expired and you must log in again.

Sequence diagram

sequenceDiagram
actor User
participant Caller
participant WEBAPI
User->>Caller: Enter username and password
Caller->>WEBAPI: POST /api/v1/auth/login
WEBAPI-->>Caller: code=0 + token/role
Caller->>WEBAPI: GET /api/v1/monitor/localization<br/>Authorization: Bearer token
WEBAPI-->>Caller: code=0 + data
Caller-->>User: Display real-time status

Exception details:

A failed login returns 200 + code=1002

An invalid token returns 401 + code=1003

An expired token returns 401 + code=1004

Upload and Activate a startup File

Invoke POST /api/v1/config/startup/files/upload to upload the file and SHA256.

Invoke GET /api/v1/config/startup/files/list to confirm that the file appears in the list.

Invoke POST /api/v1/config/startup/files/active to activate the file.

Sequence diagram

sequenceDiagram
actor Administrator
participant Caller
participant WEBAPI
Administrator->>Caller: Select a startup file
Caller->>Caller: Calculate SHA-256
Caller->>WEBAPI: POST /api/v1/config/startup/files/upload<br/>multipart(file, sha256)
WEBAPI-->>Caller: code=0 + upload result
Caller->>WEBAPI: GET /api/v1/config/startup/files/list
WEBAPI-->>Caller: code=0 + items
Administrator->>Caller: Select the new file and activate it
Caller->>WEBAPI: POST /api/v1/config/startup/files/active
WEBAPI-->>Caller: code=0 + file_name
Caller-->>Administrator: Indicate that the switch succeeded

Exception details:

A non-root user receives 403 + code=1005

An incomplete form returns 400 + code=1001

A file validation failure returns 200 + code=1201

A file that cannot be activated returns 200 + code=1401

Upload and Switch a Map Package

Invoke POST ${UPLOAD_BASE}/api/v1/files/ to create a map upload session.

Use PATCH to upload the entire ZIP file.

Poll GET ${WEB_BASE}/api/v1/maps/packages/list until the new map directory appears.

Invoke POST ${WEB_BASE}/api/v1/maps/packages/active to switch the current map.

Sequence diagram

sequenceDiagram
actor Administrator
participant Caller
participant LargeFileUploadService
participant WEBAPI
Administrator->>Caller: Select a map ZIP file and start the upload
Caller->>LargeFileUploadService: POST /api/v1/files/<br/>Authorization + Upload-Length + Upload-Metadata(fileType=map)
LargeFileUploadService-->>Caller: 201 Created + Location
loop Upload chunks
Caller->>LargeFileUploadService: PATCH {Location}
LargeFileUploadService-->>Caller: 204 No Content + Upload-Offset
end
Caller-->>Administrator: Indicate that the upload is complete and processing is pending
Caller->>WEBAPI: GET /api/v1/maps/packages/list
WEBAPI-->>Caller: code=0 + items
Administrator->>Caller: Select and switch to the new map
Caller->>WEBAPI: POST /api/v1/maps/packages/active
WEBAPI-->>Caller: code=0 + dir

Exception details:

If upload session creation fails, check the root permissions and fileType=map

If PATCH returns 409, first issue HEAD {Location}, and then resume the upload

If the item does not appear in the list after the upload is complete, continue polling the map list

If switching maps fails, common responses are 200 + code=1401 or 403 + code=1005

Upload and Install an OTA Package

Invoke POST ${UPLOAD_BASE}/api/v1/files/ to create an ota upload session.

Use PATCH to upload the entire .deb file.

Poll GET ${WEB_BASE}/api/v1/ota/packages/list until the new package appears.

Invoke POST ${WEB_BASE}/api/v1/ota/tasks to create an installation task.

Sequence diagram

sequenceDiagram
actor Administrator
participant Caller
participant LargeFileUploadService
participant WEBAPI
Administrator->>Caller: Select an OTA package and start the upload
Caller->>LargeFileUploadService: POST /api/v1/files/<br/>Authorization + Upload-Length + Upload-Metadata(fileType=ota)
LargeFileUploadService-->>Caller: 201 Created + Location
loop Upload chunks
Caller->>LargeFileUploadService: PATCH {Location}
LargeFileUploadService-->>Caller: 204 No Content + Upload-Offset
end
Caller-->>Administrator: Indicate that the upload is complete and processing is pending
Caller->>WEBAPI: GET /api/v1/ota/packages/list
WEBAPI-->>Caller: code=0 + items
Administrator->>Caller: Select an OTA package and perform the installation
Caller->>WEBAPI: POST /api/v1/ota/tasks
WEBAPI-->>Caller: code=0 + task_id

Exception details:

If upload session creation fails, check the root permissions and fileType=ota

If the item does not appear in the list after the upload is complete, continue polling the OTA package list

An invalid installation request body returns 200 + code=1703

A non-root user performing the installation receives 403 + code=1005

task_id only indicates that the installation action has been initiated; it does not mean that the upgrade is complete

Download a File and Verify Its Integrity

This applies to startup and calibration file downloads; map downloads do not return X-File-Sha256.

Sequence diagram

sequenceDiagram
actor User
participant Caller
participant WEBAPI
Caller->>WEBAPI: GET list API
WEBAPI-->>Caller: code=0 + items
User->>Caller: Select the target file
Caller->>WEBAPI: GET download API
WEBAPI-->>Caller: File stream + Content-Disposition + X-File-Sha256
Caller-->>User: Save the file and optionally verify its digest

Exception details:

If the target does not exist, the response is 200 + code=1101

Map downloads do not return X-File-Sha256

FAQ

Why Does POST http://192.168.1.88:18080/api/v1/files/ Fail?

Because the large file upload API does not use WEB_BASE. Confirm that:

Large file upload is enabled on site

You are accessing http://192.168.1.88:1080/api/v1/files/

Why Doesn't a Map or OTA Package Appear in the List Immediately After the Upload Completes?

Because upload completion only means that the entire file has been uploaded; the list may take a short time to update. The correct procedure is:

Complete the upload

Wait briefly

Invoke the list API again to confirm

Why Does the units Parameter Have No Effect When Exporting Logs?

Because the units parameter is reserved and currently has no effect. It is recommended to pass only start_time and end_time.

Why Am I Prompted That I Am Unauthenticated a Few Minutes After a Successful Login?

Because the token expires after 120 seconds without access. If the token is not used for more than 120 seconds, it becomes invalid.

Why Is There No X-File-Sha256 When Downloading a Map Package?

Because map package downloads return a ZIP file stream and do not provide the X-File-Sha256 response header.