Get started

Organization

Organizations

An organization and its settings: the workspace itineraries, zones and collections belong to. getOrganization takes a publishable key with the publishing scope, or a share token, and postOrganizationLookup takes no credential at all; every other operation here needs a session token beside the key.

The Organization object

An organization: the workspace itineraries, zones and collections belong to, together with the settings that shape its embeds. What the organization's agreement entitles it to is not part of it: the products a person's organizations hold are read as organization_capabilities on getMyOrganizations, and the one entitlement an embed paints by is white_label, which every read carries.

created_at

string (date-time)

required

Timestamp of the organization's creation.

etag

string

required

The version of the organization's own fields, the one the ETag of a read of it carries, opaque and compared whole. Send it as If-Match to make patchOrganization conditional. A change to the settings moves the settings' own etag and not this one, so a rename and a settings edit made at the same moment never refuse each other.

id

string (uuid)

required

Identifier of the organization, and the value every {organization_id} path takes.

name

string

required

Display name of the organization.

awaiting_agreement

boolean

required

Whether the organization was created to be covered by an agreement with Mountaya, which agreement_requested on postOrganization asks for, and no agreement has been set for it. It reads false again once one is. It never grants anything: an organization awaiting its agreement holds no product, and it is the agreement, once set, that grants the products it names. It tells a client to wait for the agreement rather than to ask for a card.

settings

object

required

The settings that shape the organization's embeds. They are changed through patchOrganizationSettings rather than through an organization update.

updated_at

string (date-time)

required

Timestamp of the organization's last change. Always present: it equals created_at until the organization is first changed.

white_label

boolean

required

Whether the organization may suppress the Mountaya mark on its embedded maps and exported video, which its agreement decides. It is the one entitlement this contract returns on the organization, so an embed decides whether to paint the mark from the read it already makes. When it cannot be read at that moment it reads false, which paints the mark.

The OrganizationSettings object

The settings that shape an organization's embeds, its Map Publishing settings, in three independent groups: the default props an embed starts from, the safety rules constraining what an embed may do, and the map theme. Each group is replaced whole rather than merged, so a partial update carries the complete group it changes.

etag

string

required

The version of the settings, the one the ETag of a read of them carries, opaque and compared whole. Send it as If-Match to make patchOrganizationSettings conditional. The settings are versioned apart from the organization's own fields, so a settings edit never refuses a rename made at the same moment, nor the other way round.

default_props

object

required

What an embed starts with when it names nothing itself: language, units, theme and the rest. An embed may override any of these per instance.

safety_rules

object

required

The ceilings an embed cannot raise, whatever it asks for. Unlike default_props, these are enforced rather than defaulted: an embed that requests a zoom outside the allowed window is refused, not clamped silently by the client.

theme

object

required

The organization's colors and typography for an embed. Always present: unset fields carry their neutral value rather than being absent, so a renderer reads every one of them unconditionally.

Create an organization

Creates an organization and makes the user the session token names its owner.

  • The new organization is not reachable with the key that created it. A publishable key acts on its own organization only, so every operation naming the new one is a 403 under that key, and no operation in this contract issues a key into another organization. Its subscription, keys and settings are managed with a key issued in it.
  • It starts with no subscription and holds no product, so every operation that needs one answers 402 until it does. There are two ways in. Self-serve, its first card opens the metered Data API subscription, through postOrganizationBillingProvision, postOrganizationBillingPaymentMethodSetup and postOrganizationBillingPaymentMethod in that order, and from then it holds data for as long as that subscription is in force. Under an agreement with Mountaya, which agreement_requested asks for, it holds exactly the products the agreement names once it is set: Map Studio, Map Publishing, the Tile API, Embedded Studio and White label are only ever granted this way. Until then awaiting_agreement reads true and the organization is not asked for a card.
  • Creating it also opens its billing account, whichever of the two ways it takes, normally within seconds of the answer and otherwise by the next weekly check at the latest: nothing is charged and no subscription is opened. Until the account is open, the billing operations that need one answer as they do for an organization without one, and postOrganizationBillingProvision opens it at once.
  • The optional website seeds the embed domain allowlist from its host, so a new organization starts restricted to its own site. Omit it and the allowlist starts empty, which allows every origin to call the API with the organization's keys, and lets no site but Mountaya's own frame its hosted embed, until it is set: by patchOrganizationSettings on a self-serve organization, and by Mountaya, as the agreement states, once an agreement covers it.
  • A name of more than 30 characters as sent, or of fewer than 2 once leading and trailing whitespace is trimmed, is a 400.
  • Send an Idempotency-Key: a create sent again without one makes a second organization. A create sent again with it, after the first failed with a 5xx once the organization was made, is the 409 coded IDEMPOTENCY_ANSWER_UNAVAILABLE, whose extensions.metadata.location names the organization made, /v1/organizations/{organization_id}, so carry on with that one rather than creating it again.
  • Each user creates at most 10 organizations a minute and 50 a day. Past either, the request is a 429 carrying Retry-After, and nothing is created.

Webhook events organization.created, organization.member.created, recorded by the task organization.create.

Headers

Idempotency-Key

string

in header

A value the caller chooses once per logical write and sends again, unchanged, on every retry of it, so a write whose answer was lost runs at most once. A UUID is the usual choice; any 1 to 255 printable ASCII characters without a space are accepted. The key is held for 12 hours, for the credential that sent it (the publishable key and the user its session token names) and for this operation.

Body

The organization's name, optionally the website whose host seeds its embed domain allowlist, and whether it is meant to be covered by an agreement.

name

string

in body

required

Display name of the organization: 2 to 30 characters as sent, and still at least 2 once leading and trailing whitespace is trimmed, which is the form it is stored in. A name is one line: a tab, a line break or a line separator between two of its characters is a 400, and one at either end is trimmed with the whitespace there.

website

string (uri)

in body

The organization's website as a full URL, scheme included. Its host seeds the embed domain allowlist, which is why the scheme is required rather than merely conventional: a bare host, or a scheme that is not http or https, would land in the allowlist and silently deny every embed. An empty string is accepted and seeds nothing. A host longer than the 253 characters a domain name may run to is a 400 at website, the limit every entry of the allowlist is held to.

agreement_requested

boolean

in body

Whether the organization is meant to be covered by an agreement with Mountaya rather than by a card. True records that choice, which awaiting_agreement on the organization then reports until an agreement is set, and the organization holds no product until that agreement grants the ones it names. It grants nothing itself and opens nothing. Omitted or false, the organization is self-serve: it holds no product until its first card opens the metered Data API subscription.

Response 201

The organization as created, with the user the session token names as its owner, no subscription and no product yet. Location names it, /v1/organizations/{organization_id}, and ETag carries its etag.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

Organization

required

An organization: the workspace itineraries, zones and collections belong to, together with the settings that shape its embeds. What the organization's agreement entitles it to is not part of it: the products a person's organizations hold are read as organization_capabilities on getMyOrganizations, and the one entitlement an embed paints by is white_label, which every read carries.

See the Organization object.

Errors 400, 401, 403, 409, 413, 429, 500, 504. See Errors.

curl -s -X POST https://api.mountaya.com/v1/organizations \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name": "Compagnie des Guides", "website": "https://guides.example.com"}'
201
Response
{
  "data": {
    "id": "d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b",
    "name": "Compagnie des Guides",
    "etag": "\"d7\"",
    "white_label": false,
    "awaiting_agreement": false,
    "created_at": "2026-01-14T09:20:11Z",
    "updated_at": "2026-08-01T02:14:07Z",
    "settings": {
      "etag": "\"d3\"",
      "default_props": {
        "preferred_language": "en",
        "preferred_theme": "light",
        "preferred_unit_length": "metric",
        "preferred_unit_pace": "per-time",
        "preferred_unit_slope": "degrees",
        "preferred_unit_temperature": "celsius",
        "segments_color": "",
        "terrain": "topo",
        "terrain_variant": "light",
        "with_access_restrictions": true,
        "with_collection_itineraries": true,
        "with_collection_zones": true,
        "with_directions_control": false,
        "with_download_control": false,
        "with_navigation_control": true,
        "with_overlays": [],
        "with_overlays_control": false,
        "with_preferences_control": true,
        "with_profile_analysis": true,
        "with_profile_characteristics": true,
        "with_profile_elevation": true,
        "with_profile_pace_control": true,
        "with_streetview_control": false,
        "with_terrains": []
      },
      "safety_rules": {
        "boundaries": [
          {
            "name": "Massif du Mont-Blanc",
            "bbox": [
              6.6,
              45.75,
              7.1,
              46
            ]
          }
        ],
        "domains": [
          "guides.example.com"
        ],
        "require_session_token": true,
        "with_collection_itineraries": true,
        "with_collection_zones": true,
        "with_overlays": [],
        "with_overlays_control": false,
        "with_profile_analysis": true,
        "with_profile_elevation": true,
        "zoom_max": 18,
        "zoom_min": 8
      },
      "theme": {
        "colors": {
          "ui": [
            "#ecefff",
            "#d5dafb",
            "#a9b1f1",
            "#7a87e9",
            "#5362e1",
            "#3a4bdd",
            "#2c40dc",
            "#1f32c4",
            "#182cb0",
            "#0a259c"
          ]
        }
      }
    }
  }
}

Resolve the organization a publishable key belongs to

POST
/v1/organizations/lookup

Takes a publishable key and returns the organization it was minted for. It is the bootstrap read an embed host makes before it knows anything: given only the key it was configured with, it needs the branding, the theme and the safety_rules its host page will be checked against, and it has no organization id to ask getOrganization with.

Takes no credential.

Body

The publishable key to resolve.

publishable_key

string

in body

required

The publishable key to resolve. It is sent in the BODY rather than in the X-API-Key header, and that is the whole shape of this operation: the key is the subject of the question, not the credential answering it.

Response 200

The organization the key belongs to, as getOrganization serves it, with its settings and white_label.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

Organization

required

An organization: the workspace itineraries, zones and collections belong to, together with the settings that shape its embeds. What the organization's agreement entitles it to is not part of it: the products a person's organizations hold are read as organization_capabilities on getMyOrganizations, and the one entitlement an embed paints by is white_label, which every read carries.

See the Organization object.

Errors 400, 404, 413, 429, 500, 504. See Errors.

# The key goes in the BODY. Sending it as X-API-Key does nothing here.
curl -s -X POST https://api.mountaya.com/v1/organizations/lookup \
  -H "Content-Type: application/json" \
  -d '{"publishable_key": "pk_9f3c2a71b845d0e4c7a6b3f180d92e5a"}' | jq '.data'
200
Response
{
  "data": {
    "id": "d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b",
    "name": "Compagnie des Guides",
    "etag": "\"d7\"",
    "white_label": false,
    "awaiting_agreement": false,
    "created_at": "2026-01-14T09:20:11Z",
    "updated_at": "2026-08-01T02:14:07Z",
    "settings": {
      "etag": "\"d3\"",
      "default_props": {
        "preferred_language": "en",
        "preferred_theme": "light",
        "preferred_unit_length": "metric",
        "preferred_unit_pace": "per-time",
        "preferred_unit_slope": "degrees",
        "preferred_unit_temperature": "celsius",
        "segments_color": "",
        "terrain": "topo",
        "terrain_variant": "light",
        "with_access_restrictions": true,
        "with_collection_itineraries": true,
        "with_collection_zones": true,
        "with_directions_control": false,
        "with_download_control": false,
        "with_navigation_control": true,
        "with_overlays": [],
        "with_overlays_control": false,
        "with_preferences_control": true,
        "with_profile_analysis": true,
        "with_profile_characteristics": true,
        "with_profile_elevation": true,
        "with_profile_pace_control": true,
        "with_streetview_control": false,
        "with_terrains": []
      },
      "safety_rules": {
        "boundaries": [
          {
            "name": "Massif du Mont-Blanc",
            "bbox": [
              6.6,
              45.75,
              7.1,
              46
            ]
          }
        ],
        "domains": [
          "guides.example.com"
        ],
        "require_session_token": true,
        "with_collection_itineraries": true,
        "with_collection_zones": true,
        "with_overlays": [],
        "with_overlays_control": false,
        "with_profile_analysis": true,
        "with_profile_elevation": true,
        "zoom_max": 18,
        "zoom_min": 8
      },
      "theme": {
        "colors": {
          "ui": [
            "#ecefff",
            "#d5dafb",
            "#a9b1f1",
            "#7a87e9",
            "#5362e1",
            "#3a4bdd",
            "#2c40dc",
            "#1f32c4",
            "#182cb0",
            "#0a259c"
          ]
        }
      }
    }
  }
}

Retrieve an organization

GET
/v1/organizations/{organization_id}

Returns the organization: its name, whether it awaits its agreement, whether it may leave the Mountaya mark off its maps (white_label), and the Map Publishing settings that shape what an embed of it looks like.

Path parameters

organization_id

string (uuid)

in path

required

Identifier of the organization the operation acts on. A publishable key reaches only its own organization: any other identifier is a 403, whether or not it exists, so the parameter cannot be used to probe which organization ids exist.

Response 200

The organization, with its settings and white_label, and its current etag in ETag.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

Organization

required

An organization: the workspace itineraries, zones and collections belong to, together with the settings that shape its embeds. What the organization's agreement entitles it to is not part of it: the products a person's organizations hold are read as organization_capabilities on getMyOrganizations, and the one entitlement an embed paints by is white_label, which every read carries.

See the Organization object.

Errors 400, 401, 402, 403, 404, 429, 500, 504. See Errors.

curl -s https://api.mountaya.com/v1/organizations/d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b \
  -H "X-API-Key: pk_your_publishable_key" | jq '.data'
200
Response
{
  "data": {
    "id": "d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b",
    "name": "Compagnie des Guides",
    "etag": "\"d7\"",
    "white_label": false,
    "awaiting_agreement": false,
    "created_at": "2026-01-14T09:20:11Z",
    "updated_at": "2026-08-01T02:14:07Z",
    "settings": {
      "etag": "\"d3\"",
      "default_props": {
        "preferred_language": "en",
        "preferred_theme": "light",
        "preferred_unit_length": "metric",
        "preferred_unit_pace": "per-time",
        "preferred_unit_slope": "degrees",
        "preferred_unit_temperature": "celsius",
        "segments_color": "",
        "terrain": "topo",
        "terrain_variant": "light",
        "with_access_restrictions": true,
        "with_collection_itineraries": true,
        "with_collection_zones": true,
        "with_directions_control": false,
        "with_download_control": false,
        "with_navigation_control": true,
        "with_overlays": [],
        "with_overlays_control": false,
        "with_preferences_control": true,
        "with_profile_analysis": true,
        "with_profile_characteristics": true,
        "with_profile_elevation": true,
        "with_profile_pace_control": true,
        "with_streetview_control": false,
        "with_terrains": []
      },
      "safety_rules": {
        "boundaries": [
          {
            "name": "Massif du Mont-Blanc",
            "bbox": [
              6.6,
              45.75,
              7.1,
              46
            ]
          }
        ],
        "domains": [
          "guides.example.com"
        ],
        "require_session_token": true,
        "with_collection_itineraries": true,
        "with_collection_zones": true,
        "with_overlays": [],
        "with_overlays_control": false,
        "with_profile_analysis": true,
        "with_profile_elevation": true,
        "zoom_max": 18,
        "zoom_min": 8
      },
      "theme": {
        "colors": {
          "ui": [
            "#ecefff",
            "#d5dafb",
            "#a9b1f1",
            "#7a87e9",
            "#5362e1",
            "#3a4bdd",
            "#2c40dc",
            "#1f32c4",
            "#182cb0",
            "#0a259c"
          ]
        }
      }
    }
  }
}

Update an organization

Changes the organization's own fields, merged into what is stored: a field left out keeps its value, and an empty object changes nothing and answers the organization as it stands. The display name is the whole of what is settable here: the Map Publishing settings are patchOrganizationSettings, the products the account holds follow from its agreement or its Data API subscription, and its limits from its agreement or the defaults. A change made here therefore cannot carry one of those along by accident.

  • Owner or admin only (403 otherwise).
  • A name of more than 30 characters as sent, or of fewer than 2 once leading and trailing whitespace is trimmed, is a 400.
  • It does not change the name invoices are addressed to once one has been set through patchOrganizationBillingInfo.
  • If-Match makes it conditional on the organization's etag. The settings carry an etag of their own, so a settings change made in the meantime never refuses this one.

Webhook events organization.updated, recorded by the task organization.update.

Path parameters

organization_id

string (uuid)

in path

required

Identifier of the organization the operation acts on. A publishable key reaches only its own organization: any other identifier is a 403, whether or not it exists, so the parameter cannot be used to probe which organization ids exist.

Headers

Idempotency-Key

string

in header

A value the caller chooses once per logical write and sends again, unchanged, on every retry of it, so a write whose answer was lost runs at most once. A UUID is the usual choice; any 1 to 255 printable ASCII characters without a space are accepted. The key is held for 12 hours, for the credential that sent it (the publishable key and the user its session token names) and for this operation.

If-Match

string

in header

Makes the write conditional on the resource still being the version the caller read: the ETag an earlier answer carried, which is also that resource's etag field, or * for any version. When the resource has changed since, the write is refused with 412 PRECONDITION_FAILED, nothing is changed, and the answer carries the current ETag, so the caller reads the resource again and decides. Omitted, the write is unconditional and the last write wins.

Body

The organization fields to change. Every field is optional; an omitted field keeps its current value.

name

string

in body

Display name of the organization: 2 to 30 characters as sent, and still at least 2 once leading and trailing whitespace is trimmed, which is the form it is stored in. Optional and not nullable: omit it to keep the current name. A name is one line: a tab, a line break or a line separator between two of its characters is a 400, and one at either end is trimmed with the whitespace there.

Response 200

The organization after the change, in full, with its new etag in ETag.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

Organization

required

An organization: the workspace itineraries, zones and collections belong to, together with the settings that shape its embeds. What the organization's agreement entitles it to is not part of it: the products a person's organizations hold are read as organization_capabilities on getMyOrganizations, and the one entitlement an embed paints by is white_label, which every read carries.

See the Organization object.

Errors 400, 401, 403, 404, 409, 412, 413, 429, 500, 504. See Errors.

curl -s -X PATCH https://api.mountaya.com/v1/organizations/d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" \
  -H "Content-Type: application/json" \
  -d '{"name": "Compagnie des Guides"}'
200
Response
{
  "data": {
    "id": "d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b",
    "name": "Compagnie des Guides",
    "etag": "\"d7\"",
    "white_label": false,
    "awaiting_agreement": false,
    "created_at": "2026-01-14T09:20:11Z",
    "updated_at": "2026-08-01T02:14:07Z",
    "settings": {
      "etag": "\"d3\"",
      "default_props": {
        "preferred_language": "en",
        "preferred_theme": "light",
        "preferred_unit_length": "metric",
        "preferred_unit_pace": "per-time",
        "preferred_unit_slope": "degrees",
        "preferred_unit_temperature": "celsius",
        "segments_color": "",
        "terrain": "topo",
        "terrain_variant": "light",
        "with_access_restrictions": true,
        "with_collection_itineraries": true,
        "with_collection_zones": true,
        "with_directions_control": false,
        "with_download_control": false,
        "with_navigation_control": true,
        "with_overlays": [],
        "with_overlays_control": false,
        "with_preferences_control": true,
        "with_profile_analysis": true,
        "with_profile_characteristics": true,
        "with_profile_elevation": true,
        "with_profile_pace_control": true,
        "with_streetview_control": false,
        "with_terrains": []
      },
      "safety_rules": {
        "boundaries": [
          {
            "name": "Massif du Mont-Blanc",
            "bbox": [
              6.6,
              45.75,
              7.1,
              46
            ]
          }
        ],
        "domains": [
          "guides.example.com"
        ],
        "require_session_token": true,
        "with_collection_itineraries": true,
        "with_collection_zones": true,
        "with_overlays": [],
        "with_overlays_control": false,
        "with_profile_analysis": true,
        "with_profile_elevation": true,
        "zoom_max": 18,
        "zoom_min": 8
      },
      "theme": {
        "colors": {
          "ui": [
            "#ecefff",
            "#d5dafb",
            "#a9b1f1",
            "#7a87e9",
            "#5362e1",
            "#3a4bdd",
            "#2c40dc",
            "#1f32c4",
            "#182cb0",
            "#0a259c"
          ]
        }
      }
    }
  }
}

Retrieve an organization's Map Publishing settings

GET
/v1/organizations/{organization_id}/settings

Returns the settings that shape an organization's embeds: the default props a viewer starts from, the map theme, and the safety rules a visitor can never exceed. Read it against the same object the PATCH beside it replaces: this is the whole of what that operation writes, and nothing else.

  • A session token minted for api without a user is asked for no member role on this read; one minted for studio-embedded without a user is the 401 a key alone gets. One that names a user is answered only while that user is a member of the organization, in any role, and is a 403 otherwise. Changing the settings takes the owner or admin role, which is why the PATCH needs a session token naming a user and this read does not.
  • The settings carry an etag of their own, versioned apart from the organization's: a settings change moves it and leaves the organization's alone, and a rename moves the organization's and leaves this one alone, so neither ever refuses the other.

Path parameters

organization_id

string (uuid)

in path

required

Identifier of the organization the operation acts on. A publishable key reaches only its own organization: any other identifier is a 403, whether or not it exists, so the parameter cannot be used to probe which organization ids exist.

Response 200

The settings that shape the organization's embeds, with their own etag in ETag.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

OrganizationSettings

required

The settings that shape an organization's embeds, its Map Publishing settings, in three independent groups: the default props an embed starts from, the safety rules constraining what an embed may do, and the map theme. Each group is replaced whole rather than merged, so a partial update carries the complete group it changes.

See the OrganizationSettings object.

Errors 400, 401, 403, 404, 429, 500, 504. See Errors.

# Any member role reads them, and an api session minted without a user needs none.
# Changing them takes the owner or admin role, which is why the PATCH needs a
# session token naming a user and this read does not.
curl -s https://api.mountaya.com/v1/organizations/d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b/settings \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" | jq '.data'
200
Response
{
  "data": {
    "etag": "\"d3\"",
    "default_props": {
      "preferred_language": "en",
      "preferred_theme": "light",
      "preferred_unit_length": "metric",
      "preferred_unit_pace": "per-time",
      "preferred_unit_slope": "degrees",
      "preferred_unit_temperature": "celsius",
      "segments_color": "",
      "terrain": "topo",
      "terrain_variant": "light",
      "with_access_restrictions": true,
      "with_collection_itineraries": true,
      "with_collection_zones": true,
      "with_directions_control": false,
      "with_download_control": false,
      "with_navigation_control": true,
      "with_overlays": [],
      "with_overlays_control": false,
      "with_preferences_control": true,
      "with_profile_analysis": true,
      "with_profile_characteristics": true,
      "with_profile_elevation": true,
      "with_profile_pace_control": true,
      "with_streetview_control": false,
      "with_terrains": []
    },
    "safety_rules": {
      "boundaries": [
        {
          "name": "Massif du Mont-Blanc",
          "bbox": [
            6.6,
            45.75,
            7.1,
            46
          ]
        }
      ],
      "domains": [
        "guides.example.com"
      ],
      "require_session_token": true,
      "with_collection_itineraries": true,
      "with_collection_zones": true,
      "with_overlays": [],
      "with_overlays_control": false,
      "with_profile_analysis": true,
      "with_profile_elevation": true,
      "zoom_max": 18,
      "zoom_min": 8
    },
    "theme": {
      "colors": {
        "ui": [
          "#ecefff",
          "#d5dafb",
          "#a9b1f1",
          "#7a87e9",
          "#5362e1",
          "#3a4bdd",
          "#2c40dc",
          "#1f32c4",
          "#182cb0",
          "#0a259c"
        ]
      }
    }
  }
}

Update an organization's Map Publishing settings

PATCH
/v1/organizations/{organization_id}/settings

Applies a partial update to the settings that shape an organization's embeds: the default props, the map theme, and the safety rules. Only the groups present in the request body are replaced; the omitted groups are preserved. A group that is present carries every one of its fields, so a partial group is a 400 rather than a partial change.

  • Owner or admin only (403 otherwise). That is the role difference from the GET beside it, and the reason this one needs a session token naming a user.
  • If-Match makes it conditional on the settings' own etag, which only a settings change moves: a rename made in the meantime never refuses it.
  • Three safety rules are set by Mountaya, and a request sends them as they stand: safety_rules.with_overlays and safety_rules.with_overlays_control on every organization, and safety_rules.domains on an organization covered by an agreement. A safety_rules group that changes any of them is a 403 whose entry names that field, and nothing is changed. with_overlays is compared as a set, so the order of its slugs changes nothing, and domains is compared once each entry is normalized the way it is stored. A self-serve organization's administrators set its domains themselves.
  • safety_rules.domains holds as many entries as the organization's agreement allows, 1 unless it says otherwise: a request that would leave more, and more than the list holds now, is refused at allowed-domains, a 429 coded LIMIT_REACHED with no Retry-After, and nothing is changed. Remove one first, or agree a higher limit. A list holding more than a lowered limit is kept: its entries may be edited or removed, and none added until it holds fewer than the limit.
  • The organization's limits, the per-minute rate limits and monthly allowances among them, are not settings and are not here: they are the organization's agreement's, and a caller that exhausts one is refused by the surface that limit governs.

Webhook events organization.settings.updated, recorded by the task organization.settings.update.

Path parameters

organization_id

string (uuid)

in path

required

Identifier of the organization the operation acts on. A publishable key reaches only its own organization: any other identifier is a 403, whether or not it exists, so the parameter cannot be used to probe which organization ids exist.

Headers

Idempotency-Key

string

in header

A value the caller chooses once per logical write and sends again, unchanged, on every retry of it, so a write whose answer was lost runs at most once. A UUID is the usual choice; any 1 to 255 printable ASCII characters without a space are accepted. The key is held for 12 hours, for the credential that sent it (the publishable key and the user its session token names) and for this operation.

If-Match

string

in header

Makes the write conditional on the resource still being the version the caller read: the ETag an earlier answer carried, which is also that resource's etag field, or * for any version. When the resource has changed since, the write is refused with 412 PRECONDITION_FAILED, nothing is changed, and the answer carries the current ETag, so the caller reads the resource again and decides. Omitted, the write is unconditional and the last write wins.

Body

The settings groups to replace. Every group is optional; a group that is present is replaced whole and carries every one of its fields, and a group that is absent is left as it is.

default_props

object

in body

What an embed starts with when it names nothing itself. Sent whole: the object REPLACES the stored one rather than merging into it, and every field in it is required, so a group that leaves one out is a 400 rather than a partial change.

theme

object

in body

The organization's colors and typography for an embed. Sent whole: the object REPLACES the stored one rather than merging into it, and every field in it is required.

safety_rules

object

in body

The ceilings an embed cannot raise. Sent whole: the object REPLACES the stored one rather than merging into it, and every rule in it is required, require_session_token included, so a group that leaves one out is a 400 rather than a change that drops it. with_overlays, with_overlays_control, and domains on an organization covered by an agreement, are sent as they stand, since Mountaya sets them: changing any of them is a 403.

Response 200

The settings after the change, in full: the groups that were replaced and the groups that were left alone, with the settings' new etag in ETag.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

OrganizationSettings

required

The settings that shape an organization's embeds, its Map Publishing settings, in three independent groups: the default props an embed starts from, the safety rules constraining what an embed may do, and the map theme. Each group is replaced whole rather than merged, so a partial update carries the complete group it changes.

See the OrganizationSettings object.

Errors 400, 401, 403, 404, 409, 412, 413, 429, 500, 504. See Errors.

# Groups are replaced wholesale, not merged: send safety_rules complete. Omitted
# GROUPS are preserved; a sent group missing a FIELD is a 400. Mountaya sets
# with_overlays and with_overlays_control, and the domains of an organization
# covered by an agreement, and a group that changes one is a 403, so read the
# group and send it back with the one rule changed.
URL=https://api.mountaya.com/v1/organizations/d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b/settings
curl -s "$URL" \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" \
  | jq '{safety_rules: (.data.safety_rules + {require_session_token: true})}' \
  | curl -s -X PATCH "$URL" \
      -H "X-API-Key: pk_your_publishable_key" \
      -H "X-Session-Token: sess_your_session_token" \
      -H "Content-Type: application/json" \
      -d @-
200
Response
{
  "data": {
    "etag": "\"d3\"",
    "default_props": {
      "preferred_language": "en",
      "preferred_theme": "light",
      "preferred_unit_length": "metric",
      "preferred_unit_pace": "per-time",
      "preferred_unit_slope": "degrees",
      "preferred_unit_temperature": "celsius",
      "segments_color": "",
      "terrain": "topo",
      "terrain_variant": "light",
      "with_access_restrictions": true,
      "with_collection_itineraries": true,
      "with_collection_zones": true,
      "with_directions_control": false,
      "with_download_control": false,
      "with_navigation_control": true,
      "with_overlays": [],
      "with_overlays_control": false,
      "with_preferences_control": true,
      "with_profile_analysis": true,
      "with_profile_characteristics": true,
      "with_profile_elevation": true,
      "with_profile_pace_control": true,
      "with_streetview_control": false,
      "with_terrains": []
    },
    "safety_rules": {
      "boundaries": [
        {
          "name": "Massif du Mont-Blanc",
          "bbox": [
            6.6,
            45.75,
            7.1,
            46
          ]
        }
      ],
      "domains": [
        "guides.example.com"
      ],
      "require_session_token": true,
      "with_collection_itineraries": true,
      "with_collection_zones": true,
      "with_overlays": [],
      "with_overlays_control": false,
      "with_profile_analysis": true,
      "with_profile_elevation": true,
      "zoom_max": 18,
      "zoom_min": 8
    },
    "theme": {
      "colors": {
        "ui": [
          "#ecefff",
          "#d5dafb",
          "#a9b1f1",
          "#7a87e9",
          "#5362e1",
          "#3a4bdd",
          "#2c40dc",
          "#1f32c4",
          "#182cb0",
          "#0a259c"
        ]
      }
    }
  }
}