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.
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_atstring (date-time)
Timestamp of the organization's creation.
etagstring
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.
idstring (uuid)
Identifier of the organization, and the value every {organization_id} path takes.
namestring
Display name of the organization.
awaiting_agreementboolean
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.
settingsobject
The settings that shape the organization's embeds. They are changed through patchOrganizationSettings rather than through an organization update.
updated_atstring (date-time)
Timestamp of the organization's last change. Always present: it equals created_at until the organization is first changed.
white_labelboolean
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 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.
etagstring
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_propsobject
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_rulesobject
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.
themeobject
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.
/v1/organizationsCreates 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
403under 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
402until it does. There are two ways in. Self-serve, its first card opens the metered Data API subscription, throughpostOrganizationBillingProvision,postOrganizationBillingPaymentMethodSetupandpostOrganizationBillingPaymentMethodin that order, and from then it holdsdatafor as long as that subscription is in force. Under an agreement with Mountaya, whichagreement_requestedasks 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 thenawaiting_agreementreads 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
postOrganizationBillingProvisionopens it at once. - The optional
websiteseeds 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: bypatchOrganizationSettingson 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 a5xxonce the organization was made, is the409codedIDEMPOTENCY_ANSWER_UNAVAILABLE, whoseextensions.metadata.locationnames 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
429carryingRetry-After, and nothing is created.
Webhook events organization.created, organization.member.created, recorded by the task organization.create.
Headers
Idempotency-Keystring
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.
namestring
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. 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.
websitestring (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_requestedboolean
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.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataOrganization
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.
Errors 400, 401, 403, 409, 413, 429, 500, 504. See Errors.
/v1/organizations/lookupTakes 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_keystring
in body
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.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataOrganization
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.
Errors 400, 404, 413, 429, 500, 504. See Errors.
/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_idstring (uuid)
in path
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.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataOrganization
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.
Errors 400, 401, 402, 403, 404, 429, 500, 504. See Errors.
/v1/organizations/{organization_id}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-Matchmakes it conditional on the organization'setag. The settings carry anetagof 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_idstring (uuid)
in path
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-Keystring
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-Matchstring
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.
namestring
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.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataOrganization
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.
Errors 400, 401, 403, 404, 409, 412, 413, 429, 500, 504. See Errors.
/v1/organizations/{organization_id}/settingsReturns 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
apiwithout a user is asked for no member role on this read; one minted forstudio-embeddedwithout a user is the401a 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
etagof 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_idstring (uuid)
in path
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.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataOrganizationSettings
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.
Errors 400, 401, 403, 404, 429, 500, 504. See Errors.
/v1/organizations/{organization_id}/settingsApplies 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-Matchmakes it conditional on the settings' ownetag, 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_overlaysandsafety_rules.with_overlays_controlon every organization, andsafety_rules.domainson an organization covered by an agreement. Asafety_rulesgroup that changes any of them is a403whose entry names that field, and nothing is changed.with_overlaysis compared as a set, so the order of its slugs changes nothing, anddomainsis compared once each entry is normalized the way it is stored. A self-serve organization's administrators set itsdomainsthemselves. safety_rules.domainsholds 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 atallowed-domains, a429codedLIMIT_REACHEDwith noRetry-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_idstring (uuid)
in path
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-Keystring
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-Matchstring
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_propsobject
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.
themeobject
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_rulesobject
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.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataOrganizationSettings
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.
Errors 400, 401, 403, 404, 409, 412, 413, 429, 500, 504. See Errors.