Upload a map

POST

/v1/maps/upload

• Web API (Projects, Maps, Content, Query)

Upload a map image with metadata via multipart/form-data. Upserts by (projectId, mapId) — if a map with the same ID exists, it is updated. Requires admin API key and X-Project-Id header.

Authorizations

• ApiKeyAuth

Parameters

Header Parameters

X-Project-Id

required

string format: uuid

Project UUID (sent as a header for endpoints that don’t include it in the path).

Request Body ^required

object

name

required

Display name for the map (max 255 characters).

string

mapId

required

Unique map identifier within the project (max 255 characters).

string

image

required

Map image file (PNG, JPEG, or WebP, max 10 MB).

string format: binary

worldMinX

required

Minimum X coordinate in world space.

number

worldMinY

required

Minimum Y coordinate in world space.

number

worldMaxX

required

Maximum X coordinate in world space.

number

worldMaxY

required

Maximum Y coordinate in world space.

number

imageWidth

required

Image width in pixels.

integer

imageHeight

required

Image height in pixels.

integer

Responses

200

Map updated (existing map with same mapId was found).

object

success

boolean

data

object

mapId

string

action

string

Allowed values: updated

201

Map created.

object

success

boolean

data

object

mapId

string

action

string

Allowed values: created

400

Invalid request parameters or body.

object

success

boolean

error

Human-readable error message.

string

401

Missing or invalid API key.

object

success

boolean

error

Human-readable error message.

string

429

Rate limit exceeded.

object

success

boolean

error

Human-readable error message.

string

Headers

X-RateLimit-Limit

integer

Maximum number of requests allowed per hour.

X-RateLimit-Remaining

integer

Number of requests remaining in the current window.

X-RateLimit-Reset

integer

Unix timestamp when the rate limit window resets.