Upload a map
POST /v1/maps/upload
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 the resources:write scope (API key or OAuth Bearer token) and the X-Project-Id header.
Unlike other Web API endpoints, this response is flat: mapId and
action sit alongside success rather than nested under data.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Header Parameters
Section titled “Header Parameters ”Project UUID (sent as a header for endpoints that don’t include it in the path).
Request Body required
Section titled “Request Body required ”object
Display name for the map (max 255 characters).
Unique map identifier within the project (max 255 characters).
Map image file (PNG, JPEG, or WebP, max 10 MB).
Minimum X coordinate in world space.
Minimum Y coordinate in world space.
Maximum X coordinate in world space.
Maximum Y coordinate in world space.
Image width in pixels.
Image height in pixels.
Responses
Section titled “ Responses ”Map updated (existing map with same mapId was found).
object
Map created.
object
Invalid request parameters or body.
RFC 9457 Problem Details. Served with the application/problem+json
media type. error_category, retryable, and retry_after are
Framedash extension members. type always defaults to about:blank,
so it is always present; detail and the extension members are present
only when applicable.
object
Problem type URI; about:blank when no specific type applies.
Short, human-readable summary of the problem type.
HTTP status code.
Human-readable explanation specific to this occurrence.
Extension member categorizing the error.
Extension member; true when retrying may succeed (e.g. 429, 503).
Extension member; suggested retry delay in seconds, when applicable.
Missing or invalid API key.
RFC 9457 Problem Details. Served with the application/problem+json
media type. error_category, retryable, and retry_after are
Framedash extension members. type always defaults to about:blank,
so it is always present; detail and the extension members are present
only when applicable.
object
Problem type URI; about:blank when no specific type applies.
Short, human-readable summary of the problem type.
HTTP status code.
Human-readable explanation specific to this occurrence.
Extension member categorizing the error.
Extension member; true when retrying may succeed (e.g. 429, 503).
Extension member; suggested retry delay in seconds, when applicable.
API key with resources:write scope required.
RFC 9457 Problem Details. Served with the application/problem+json
media type. error_category, retryable, and retry_after are
Framedash extension members. type always defaults to about:blank,
so it is always present; detail and the extension members are present
only when applicable.
object
Problem type URI; about:blank when no specific type applies.
Short, human-readable summary of the problem type.
HTTP status code.
Human-readable explanation specific to this occurrence.
Extension member categorizing the error.
Extension member; true when retrying may succeed (e.g. 429, 503).
Extension member; suggested retry delay in seconds, when applicable.
Rate limit exceeded.
RFC 9457 Problem Details. Served with the application/problem+json
media type. error_category, retryable, and retry_after are
Framedash extension members. type always defaults to about:blank,
so it is always present; detail and the extension members are present
only when applicable.
object
Problem type URI; about:blank when no specific type applies.
Short, human-readable summary of the problem type.
HTTP status code.
Human-readable explanation specific to this occurrence.
Extension member categorizing the error.
Extension member; true when retrying may succeed (e.g. 429, 503).
Extension member; suggested retry delay in seconds, when applicable.
Headers
Section titled “Headers ”Maximum number of requests allowed per hour.
Number of requests remaining in the current window.
Unix timestamp when the rate limit window resets.
Number of seconds to wait before retrying. Present only on 429
responses. Because the limit uses a sliding window, honor this value
per response rather than scheduling a retry for the reset time.