Developers

API reference and troubleshooting

Find REST endpoints, scopes, request examples, limits and recovery steps, with a downloadable OpenAPI contract.

Contract and versions

Open the REST v1 OpenAPI JSONThe same generated contract used to check the platform and private SDK. Includes request, response and field-value schemas.

The base origin is https://maphere.app. REST endpoints use /api/v1; the hosted viewer uses control protocol v1 and the protected-access extension v1. The SDK is an unpublished private preview (0.0.0); pin an approved artifact. Protected access and content APIs require platform v0.3.0 or a compatible later deployment. Public control-v1 clients remain compatible.

Use the contract in a local API explorer or code generator. Do not submit credentials or customer responses to a public documentation service. Internal rendering endpoints are not supported customer APIs.

REST endpoints and scopes

All paths below start with /api/v1/maps/{publicId}, where publicId is the SDK map UUID from Share. Send Authorization: Bearer followed by the secret map-scoped API key from your backend. These endpoints do not provide browser CORS access.

Method and path	Required scope	Success
POST /viewer-sessions	viewer:tokens	201 — viewing token, expiry, map ID and parent origin
GET /places?stage=published&limit=50	places:read + field grants	200 — permitted values, definitions, ETag and pagination cursor
PATCH /places/{placeId}	places:write + write grants	200 — new saved draft revision and ETag; never publishes
GET /export	map:export	200 — complete active publication export, excluding image bytes

Create a viewing session — HTTP request

POST /api/v1/maps/33333333-3333-4333-8333-333333333333/viewer-sessions
Authorization: Bearer <server-secret-key>
Content-Type: application/json

{"parentOrigin":"https://portal.example.com"}

Update a draft after reading its ETag — HTTP request

PATCH /api/v1/maps/33333333-3333-4333-8333-333333333333/places/bookshop
Authorization: Bearer <server-secret-key>
Content-Type: application/json
If-Match: "draft:12"

{"values":{"name":"Harbour Books","description":null}}

Replace the example ETag with the draft GET response’s ETag, including quotes. JSON bodies require Content-Type: application/json. Unknown properties are rejected. Responses include X-Request-Id and private, no-store caching headers. Published ETags identify snapshots; they cannot authorize draft writes.

Limits and retries

Limit	Current value
Authenticated customer API	120 requests per fixed minute per key
Protected viewer resources	600 requests per fixed minute per viewing token
Places and PATCH	1–100 places per page; 128 KiB JSON body; 1–64 fields per update
Keys	Expiry 1–365 days; default 90 days; at most 20 active keys per map
Viewing sessions	At most 5 minutes; up to 1,000 active sessions per key
Server SDK	20-second default timeout; AbortSignal support; 8 MiB maximum JSON response

Honor Retry-After on 429 and 503, use bounded attempts and add jitter. Reads may be retried after transient failure. Reconcile a draft before retrying a write with an unknown outcome. The SDK does not retry HTTP operations automatically; repeating a viewing-session request can create another token.

Errors and recovery

Stable API error envelope — JSON response

{
  "error": {
    "code": "REVISION_CONFLICT",
    "message": "The draft changed. Read the current draft before retrying.",
    "requestId": "11111111-1111-4111-8111-111111111111"
  }
}

Status or code	What to check
401 UNAUTHORIZED	Key/token expiry, revocation, correct map and workspace availability
403 FORBIDDEN / FIELD_FORBIDDEN	Required scopes, exact field grants and parent origin
409 CURSOR_EXPIRED	Content changed; discard partial pages and restart pagination
412 REVISION_CONFLICT	Read the current draft and reconcile the competing edit
428 PRECONDITION_REQUIRED	Supply the draft ETag in If-Match, including quotes
429 RATE_LIMITED / 503 SERVICE_UNAVAILABLE	Wait for Retry-After; reduce volume or investigate availability
CONNECTION_TIMEOUT	Published map, embed enablement, exact origin, website frame-src and network
ACCESS_DENIED	Check visitor authorization, key permissions and recent publication or access changes; destroy and reconnect after resolving access
ACCESS_TIMEOUT	Check the token callback and backend latency
VIEWER_RELOADED	Destroy the old connection and reconnect to a consistent publication
INVALID_RESPONSE	SDK/API compatibility or malformed upstream response; retain the request ID

Branch on status and code, not error-message text. Proxies and network failures may return non-JSON responses. For support, record the request ID, operation, time, SDK build and browser version. Do not include secrets, Authorization headers, cookies, viewing tokens or private map values.