Skip to content

Mint robot map upload (beta)

Beta
POST
/v1/robots/maps
curl --request POST \
--url https://api.example.yas/v1/robots/maps \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "partnerId": "partner", "schemaVersion": "2026-11", "sourceSystem": "partner-export", "robotId": "rbt_example", "mapId": "map_1", "mapVersion": "2026-10", "unitM": 1, "contentType": "occupancy_grid", "byteLength": 1048576 }'

Beta. Mint a URL for one map with the server key. Send partnerId, schemaVersion, sourceSystem, robotId, mapId, unitM, contentType, and byteLength. The robot must already exist for this partner. unitM must be 1. contentType is occupancy_grid or point_cloud; PUT the bytes with Content-Type: application/octet-stream. byteLength is 1 to 52428800 (50 MiB), or the lower configured Storage limit. A second mint for the same partnerId, robotId and mapId replaces only the open upload. The live map stays unchanged until complete succeeds. Replaced Storage objects are retired safely after their credentials expire. contentSha256 and pointCount are stored but not verified.

Upload credentials last two hours; expiresAt is the credential deadline in ISO-8601 UTC. Complete within 24 hours of minting. The bytes enter private Storage on upload and become ready only after complete verifies their length and type. Storage does not bind the signed URL to byteLength; a mismatched file may be stored temporarily but cannot become ready. Uploads cannot overwrite an object. Mint a new upload after invalid content. Each partner may have at most 10 outstanding upload reservations totaling at most 1 GiB across maps and media. Each reservation uses the effective bucket limit, including abandoned uploads until safe cleanup. Revoking Robots access immediately blocks mint and complete, but an issued Storage credential may remain usable until it expires. Uncompleted objects are cleaned after upload credentials and sessions expire; ready media and the current live map are retained.

contentBase64 is not accepted and returns 400 invalid_body. Send byteLength, upload the bytes to the signed URL, then call complete.

Media typeapplication/json
object
partnerId
required

Partner id. It must match the server key.

string
schemaVersion
required

Schema version of this body. Example: 2026-11.

string
sourceSystem
required

Name of the system that sent this body. Example: partner-export.

string
robotId
required

Robot id. The robot must already exist.

string
mapId
required

Map id. A second mint replaces only the open upload. The live map changes when complete succeeds.

string
unitM
required

One map unit is one metre. The only allowed value is 1.

integer
Allowed values: 1
contentType
required

Map format: occupancy_grid or point_cloud.

string
Allowed values: occupancy_grid point_cloud
byteLength
required

Exact uploaded size from 1 to 52428800 bytes, subject to the lower configured Storage limit. Verified at complete.

integer
>= 1 <= 52428800
mapVersion

Version label stored with this upload. The live map stays as it is until complete.

string
originXM

Map origin X in metres.

number
originYM

Map origin Y in metres.

number
originZM

Map origin Z in metres.

number
contentSha256

SHA-256 of the bytes to upload. Stored and not checked.

string
pointCount

Point count the partner reports. Stored and not checked against the bytes.

integer
firmwareVersion

Firmware version at the time of this call.

string
metadata

Extra fields from the partner. Stored as sent.

object
key
additional properties
any

Example

{
"partnerId": "partner",
"schemaVersion": "2026-11",
"sourceSystem": "partner-export",
"robotId": "rbt_example",
"mapId": "map_1",
"mapVersion": "2026-10",
"unitM": 1,
"contentType": "occupancy_grid",
"byteLength": 1048576
}

Signed upload URL minted. The signed URL lasts two hours; complete within 24 hours of minting.

Media typeapplication/json
object
robotId
required
string
mapId
required
string
uploadUrl
required

PUT raw bytes here before expiresAt. The private object becomes ready only after complete. Do not share or log this credential.

string format: uri
objectKey
required

Assigned by YAS. Send the bytes to uploadUrl. Do not set this value yourself.

string
expiresAt
required

Upload credential expiry in ISO-8601 UTC, two hours after minting. Complete has a separate 24-hour deadline.

string format: date-time
byteLength
required

Declared byteLength. Complete rejects an object whose actual size differs.

integer

Example

{
"robotId": "rbt_example",
"mapId": "map_1",
"uploadUrl": "https://upload.example.yas/maps/map_1",
"objectKey": "partners/partner/robot/rbt_example/map/map_1/20261015T100000123Z",
"expiresAt": "2026-10-15T12:00:00.000Z",
"byteLength": 1048576
}
400A required field is missing or invalid, the content type is unsupported, or contentBase64 was sent. No upload is created.
Media typeapplication/json
object
error
required

Stable error code. No stack trace.

string

Example

{
"error": "invalid_body"
}
401The server key is missing or wrong.
Media typeapplication/json
object
error
required

Stable error code. No stack trace.

string

Example

{
"error": "invalid_credentials"
}
403A server key may be limited to vehicles, robots, or both. A call outside that limit is 403 `forbidden` and stores nothing. `identity_mismatch` means `partnerId` does not match the server key.
Media typeapplication/json
object
error
required

Stable error code. No stack trace.

string

Example

{
"error": "forbidden"
}
404Unknown `robotId`. Nothing in this call is stored.
Media typeapplication/json
object
error
required

Stable error code. No stack trace.

string

Example

{
"error": "not_found"
}
413The declared size exceeds the effective Storage limit (at most 52428800 bytes).
Media typeapplication/json
object
error
required

Stable error code. No stack trace.

string

Example

{
"error": "payload_too_large"
}
429Outstanding upload reservations reached the partner limit. Retry after cleanup releases capacity.
Media typeapplication/json
object
error
required

Stable error code. No stack trace.

string

Example

{
"error": "upload_quota_exceeded"
}
503Storage or its required configuration is unavailable. Retry after the Retry-After interval.
Media typeapplication/json
object
error
required

Stable error code. No stack trace.

string

Example

{
"error": "unavailable"
}