Get started

Users

The user the session token names, under /v1/me: their membership of the key's organization, the display preferences that follow the person into every organization, and the invitations to the key's organization waiting for their answer. No path names a user, so no request reads or answers for anybody else. Every operation here needs a session token naming a user beside the key.

The RelationToUser object

A reference to a user by id alone. Resources name their author with this (created_by). No operation resolves an arbitrary user id: a display name is found by matching the id against getOrganizationMembers, which lists the organization's members with the name each has set, so an author who has since left the organization, or who never set a name, has none to show.

id

string (uuid)

required

Identifier of the user this relation is about.

The Membership object

A person's membership of one organization they have joined. It pairs the person and the organization, so it has no identifier of its own and names both: user_id and organization_id. It carries the organization's identity with the role, so a client can name the organization and read the person's role in it without a second read.

user_id

string (uuid)

required

Identifier of the person, the user the session token names.

organization_id

string (uuid)

required

Identifier of the organization. It is what every organization-scoped operation takes as its organization_id path parameter.

organization_name

string

required

The organization's display name, as it appears to its members.

organization_capabilities

array of string

required

The products the organization holds, as Capability members, each at most once and sorted alphabetically. Empty when it holds none, as a new organization does. It is what the organization holds, never what this member may do with it: the role and studio_entitlements say that.

studio_entitlements

array of string

required

What this person may use of Map Studio in this organization, as StudioEntitlement members, each at most once and sorted alphabetically. Mountaya resolves it from what the organization holds and from the role, as StudioEntitlement describes: embed, publish, video-export and video-organization-modes only where the organization holds Map Publishing, and white-label only where it holds White label. A change of agreement or of role reaches it on the next read. Read with a publishable key, it is narrowed by the organization's safety rules, as what the key is served is: profile-insights only when with_profile_analysis is set, map-pois only when with_overlays admits the points of interest, and map-overlays only when it admits another overlay. It authorizes nothing by itself, since every request is still refused by its own rule.

role

string

required

One of: owner, admin, contributor, viewer

What this person may do in this organization.

joined_at

string (date-time)

required

When the person joined: when the invitation was accepted, or when the organization was created for its owner.

The Preferences object

A user's own display preferences: the language they read in, the theme they see, and the four units every figure this API returns is rendered in. They belong to the PERSON rather than to an organization, so they follow the user across every organization they are a member of.

language

string

required

One of: en, fr, es, it, de, zh, ja

The language user-facing content is written in.

theme

string

required

One of: auto, light, dark

The color theme the interface is painted in.

length

string

required

One of: metric, imperial

The measurement system distances, elevations and lengths are shown in.

pace

string

required

One of: per-time, per-distance

The form a travel rate is shown in, time over distance or distance over time.

slope

string

required

One of: degrees, percentage

The unit a gradient is shown in.

temperature

string

required

One of: celsius, fahrenheit

The unit a temperature is shown in.

The NotificationPreferences object

Which notification emails about an organization a member receives. A member is sent each one unless they turned it off, and a security notification is always sent.

organization_id

string (uuid)

required

Identifier of the organization the notifications are about.

user_id

string (uuid)

required

Identifier of the member, the user the session token names.

notifications

array of NotificationPreference

required

One entry per notification the member can receive in the organization: the security notifications, member-role-changed and member-removed, locked on; collection-deleted; and for an owner or an admin, webhook-endpoint-failing and webhook-endpoint-disabled. The invitation email goes to an address before it is a member's, and is never listed.

List the acting user's memberships

Returns the memberships of the user the session token names, each carrying the organization's name and the products it holds beside the role, so a client can label the organization it acts in, and tell whether it holds Map Studio, without a second read. Under a publishable key that is the user's membership of the key's organization alone: a one-entry list, or an empty one while the user has not joined it, as a user whose invitation is still waiting has not. An invitation is not a membership: getMyInvitations lists those.

Query parameters

cursor

string

in query

Where the page starts: the next_cursor the previous page reported at extensions.metadata.pagination, sent back unchanged. Omitted, the listing starts at its first item.

limit

integer (int32)

in query

default: 50

How many items one page holds, between 1 and 100; 50 when omitted, on every listing that pages. extensions.metadata.pagination.limit reports the size the page was served at. A page shorter than limit is not how the end is told: the end is a next_cursor of null. The page is cut after authorization, so it never widens what a caller can read.

Response 200

One page of the acting user's memberships: under a publishable key, the membership in the key's organization as the only entry, or no entry while the user has not joined it. extensions.metadata.pagination reads next_cursor: null at the end of the listing.

extensions

object

required

The envelope's second half, everything the answer carries that is not the answer itself. Here that is metadata.pagination alone: the limit this page was served at and the cursor of the next page, null on the last.

data

array of Membership

required

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

curl -s https://api.mountaya.com/v1/me/organizations \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" | jq '.data'
200
Response
{
  "data": [
    {
      "user_id": "7a4e1c98-3b52-4f60-9d81-c05e2f7a83b1",
      "organization_id": "d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b",
      "organization_name": "Compagnie des Guides",
      "organization_capabilities": [
        "publishing",
        "studio-online"
      ],
      "role": "contributor",
      "studio_entitlements": [
        "context-menu-insights",
        "copilot",
        "embed",
        "map-overlays",
        "map-pois",
        "profile-insights",
        "publish",
        "video-export",
        "video-organization-modes"
      ],
      "joined_at": "2026-01-14T09:20:11Z"
    }
  ],
  "extensions": {
    "metadata": {
      "pagination": {
        "limit": 50,
        "next_cursor": "eyJ2IjoxLCJzIjoiLXVwZGF0ZWRfYXQifQ"
      }
    }
  }
}

Retrieve the acting user's display preferences

Returns the six preferences the user the session token names reads and renders by: the language, the theme, and the units of length, pace, slope and temperature.

Response 200

All six preferences of the user the session token names.

extensions

object

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

data

Preferences

required

A user's own display preferences: the language they read in, the theme they see, and the four units every figure this API returns is rendered in. They belong to the PERSON rather than to an organization, so they follow the user across every organization they are a member of.

See the Preferences object.

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

curl -s https://api.mountaya.com/v1/me/preferences \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" | jq '.data'
200
Response
{
  "data": {
    "language": "fr",
    "theme": "dark",
    "length": "metric",
    "pace": "per-distance",
    "slope": "percentage",
    "temperature": "celsius"
  }
}

Update the acting user's display preferences

Changes any of the six preferences the user the session token names reads and renders by, and returns all six afterwards. Every field is optional and independent: what is sent is changed, what is omitted is left alone, and the reply is the whole set rather than the part that moved.

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 preferences to change. Send only what is changing.

language

string

in body

One of: en, fr, es, it, de, zh, ja

The language user-facing content is written in. Optional and not nullable: omit it to keep the current language.

theme

string

in body

One of: auto, light, dark

The color theme the interface is painted in. Optional and not nullable: omit it to keep the current theme.

length

string

in body

One of: metric, imperial

The measurement system distances, elevations and lengths are shown in. Optional and not nullable: omit it to keep the current system.

pace

string

in body

One of: per-time, per-distance

The form a travel rate is shown in, time over distance or distance over time. Optional and not nullable: omit it to keep the current form.

slope

string

in body

One of: degrees, percentage

The unit a gradient is shown in. Optional and not nullable: omit it to keep the current unit.

temperature

string

in body

One of: celsius, fahrenheit

The unit a temperature is shown in. Optional and not nullable: omit it to keep the current unit.

Response 200

All six preferences after the change, not only the ones that changed.

extensions

object

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

data

Preferences

required

A user's own display preferences: the language they read in, the theme they see, and the four units every figure this API returns is rendered in. They belong to the PERSON rather than to an organization, so they follow the user across every organization they are a member of.

See the Preferences object.

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

curl -s -X PATCH https://api.mountaya.com/v1/me/preferences \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" \
  -H "Content-Type: application/json" \
  -d '{"length": "imperial", "theme": "dark"}' | jq '.data'
200
Response
{
  "data": {
    "language": "fr",
    "theme": "dark",
    "length": "metric",
    "pace": "per-distance",
    "slope": "percentage",
    "temperature": "celsius"
  }
}

List the invitations waiting for the acting user

Returns the invitations waiting for an answer from the user the session token names, each with the organization's name and the products it holds and the role accepting grants, so a person can decide without a second read. Under a publishable key that is the invitations to the key's organization alone.

Query parameters

cursor

string

in query

Where the page starts: the next_cursor the previous page reported at extensions.metadata.pagination, sent back unchanged. Omitted, the listing starts at its first item.

limit

integer (int32)

in query

default: 50

How many items one page holds, between 1 and 100; 50 when omitted, on every listing that pages. extensions.metadata.pagination.limit reports the size the page was served at. A page shorter than limit is not how the end is told: the end is a next_cursor of null. The page is cut after authorization, so it never widens what a caller can read.

Response 200

One page of the invitations waiting for the acting user, newest first. Empty when none is waiting, a member's usual answer. extensions.metadata.pagination reads next_cursor: null at the end of the listing.

extensions

object

required

The envelope's second half, everything the answer carries that is not the answer itself. Here that is metadata.pagination alone: the limit this page was served at and the cursor of the next page, null on the last.

data

array of UserInvitation

required

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

curl -s https://api.mountaya.com/v1/me/invitations \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" | jq '.data'
200
Response
{
  "data": [
    {
      "id": "3d6f0a2b-4c1e-4f87-9b25-7e0c1d9a6f43",
      "organization_id": "d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b",
      "organization_name": "Compagnie des Guides",
      "organization_capabilities": [
        "publishing",
        "studio-online"
      ],
      "role": "contributor",
      "created_at": "2026-10-20T09:12:44Z",
      "expires_at": "2026-11-19T09:12:44Z"
    }
  ],
  "extensions": {
    "metadata": {
      "pagination": {
        "limit": 50,
        "next_cursor": "eyJ2IjoxLCJzIjoiLXVwZGF0ZWRfYXQifQ"
      }
    }
  }
}

Decline an invitation

Declines an invitation waiting for the user the session token names, which frees the seat it held. The organization sees it leave getOrganizationInvitations, and may invite the address again.

  • Only the invited person declines, and only an invitation that is theirs: one made to an address their account has verified, to the key's organization.
  • Declining is an act on the invitation's state rather than on a resource, so an identifier naming nothing waiting for this user answers 200 and changes nothing: an invitation already declined, withdrawn or lapsed, another person's, one to an address the account has not verified, and one that never existed. A decline racing a withdrawal is therefore not an error, and nobody learns from it which invitation ids exist.
  • A user whose declined invitation was their only tie to the organization holds nothing there afterwards, so a decline they send again is refused with 403 unless it carries the first request's Idempotency-Key, which answers it with the first one's 200.
  • An invitation already accepted is gone as well: the person is a member, and leaves with deleteOrganizationMember.

Webhook events organization.invitation.declined, recorded by the task organization.invitation.decline.

Path parameters

invitation_id

string (uuid)

in path

required

Identifier of the invitation, the id an OrganizationInvitation or a UserInvitation carries. One that names no invitation this caller may see, an expired one included, is answered as each operation says: a read or an acceptance answers it 404, and a withdrawal or a decline, which leave it gone either way, answer 200.

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.

Response 200

The invitation is declined, or nothing with that identifier was waiting for this user. data is null.

extensions

object

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

data

any | null

required

Always null: this operation answers with no payload.

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

curl -s -X DELETE https://api.mountaya.com/v1/me/invitations/3d6f0a2b-4c1e-4f87-9b25-7e0c1d9a6f43 \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token"
200
Response
{
  "data": null
}

Accept an invitation

POST
/v1/me/invitations/{invitation_id}/accept

Accepts an invitation waiting for the user the session token names, which makes them a member of the organization with the role it grants, and answers the membership. The invitation is consumed: it leaves getMyInvitations and getOrganizationInvitations, and the person is listed by getOrganizationMembers from then on.

  • Only the invited person accepts. An invitation is theirs when it was made to an address their account has verified, and is to the key's organization. Any other identifier is a 404: an invitation to an address the account has not verified, another person's, one already answered, withdrawn or lapsed, and one that names nothing all answer alike.
  • It takes no seat. The invitation has held its seat since it was made, so accepting is never refused for the organization's seats.
  • The session token the person used before joining needs no replacing: it acts as the member, in the role granted, from the next request.
  • Accepting consumes the invitation, so the same request sent again is a 404 and changes nothing, unless it carries the first request's Idempotency-Key, which answers it with the first one's 200.

Webhook events organization.invitation.accepted, organization.member.created, organization.invitation.deleted, recorded by the task organization.invitation.accept.

Path parameters

invitation_id

string (uuid)

in path

required

Identifier of the invitation, the id an OrganizationInvitation or a UserInvitation carries. One that names no invitation this caller may see, an expired one included, is answered as each operation says: a read or an acceptance answers it 404, and a withdrawal or a decline, which leave it gone either way, answer 200.

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.

Response 200

The membership the invitation became, with the role it granted and joined_at set to the moment of acceptance.

extensions

object

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

data

Membership

required

A person's membership of one organization they have joined. It pairs the person and the organization, so it has no identifier of its own and names both: user_id and organization_id. It carries the organization's identity with the role, so a client can name the organization and read the person's role in it without a second read.

See the Membership object.

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

curl -s -X POST https://api.mountaya.com/v1/me/invitations/3d6f0a2b-4c1e-4f87-9b25-7e0c1d9a6f43/accept \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" \
  -H "Idempotency-Key: $(uuidgen)"
200
Response
{
  "data": {
    "user_id": "7a4e1c98-3b52-4f60-9d81-c05e2f7a83b1",
    "organization_id": "d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b",
    "organization_name": "Compagnie des Guides",
    "organization_capabilities": [
      "publishing",
      "studio-online"
    ],
    "role": "contributor",
    "studio_entitlements": [
      "context-menu-insights",
      "copilot",
      "embed",
      "map-overlays",
      "map-pois",
      "profile-insights",
      "publish",
      "video-export",
      "video-organization-modes"
    ],
    "joined_at": "2026-01-14T09:20:11Z"
  }
}

Retrieve the acting user's notification emails for an organization

GET
/v1/me/organizations/{organization_id}/notification-preferences

Returns which notification emails about the organization the user the session token names receives. Every one is on until the member turns it off, and the security notifications, a role changed or a removal made by somebody else, are always sent: they are listed locked, with the reason.

  • An owner and an admin are listed the notifications about the organization's webhook endpoints as well; a contributor and a viewer are not, and are sent none.
  • The invitation email goes to an address before it belongs to a member, and is never listed.

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 notification emails the user receives about the organization.

extensions

object

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

data

NotificationPreferences

required

Which notification emails about an organization a member receives. A member is sent each one unless they turned it off, and a security notification is always sent.

See the NotificationPreferences object.

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

curl -s https://api.mountaya.com/v1/me/organizations/d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b/notification-preferences \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" | jq '.data.notifications'
200
Response
{
  "data": {
    "organization_id": "d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b",
    "user_id": "7a4e1c98-3b52-4f60-9d81-c05e2f7a83b1",
    "notifications": [
      {
        "notification": "member-role-changed",
        "email": true,
        "locked": true,
        "locked_reason": "Security notifications are always sent."
      },
      {
        "notification": "member-removed",
        "email": true,
        "locked": true,
        "locked_reason": "Security notifications are always sent."
      },
      {
        "notification": "collection-deleted",
        "email": false,
        "locked": false,
        "locked_reason": null
      }
    ]
  }
}

Turn the acting user's notification emails for an organization on or off

PATCH
/v1/me/organizations/{organization_id}/notification-preferences

Turns notification emails about the organization on or off for the user the session token names, and answers them all afterwards. A notification left out keeps its setting. A user changes their own and nobody else's, so this names nobody: it writes those of the user the session token names.

  • A security notification, member-role-changed or member-removed, is always sent: naming one is a 400 naming it, and nothing is changed. So is naming invitation, which no member is sent, or a webhook endpoint's notification as a contributor or a viewer.
  • Any role changes them, a viewer's included, since they change nothing the organization holds.

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.

Body

The notifications to turn on or off. Send only what is changing.

notifications

array of NotificationPreferenceUpdate

in body

required

One entry per notification to set, at least one, each notification at most once: naming one twice is a 400 naming the second.

Response 200

Every notification email the user receives about the organization after the change, not only the ones that changed.

extensions

object

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

data

NotificationPreferences

required

Which notification emails about an organization a member receives. A member is sent each one unless they turned it off, and a security notification is always sent.

See the NotificationPreferences object.

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

curl -s -X PATCH https://api.mountaya.com/v1/me/organizations/d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b/notification-preferences \
  -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 '{"notifications": [{"notification": "collection-deleted", "email": false}]}'
200
Response
{
  "data": {
    "organization_id": "d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b",
    "user_id": "7a4e1c98-3b52-4f60-9d81-c05e2f7a83b1",
    "notifications": [
      {
        "notification": "member-role-changed",
        "email": true,
        "locked": true,
        "locked_reason": "Security notifications are always sent."
      },
      {
        "notification": "member-removed",
        "email": true,
        "locked": true,
        "locked_reason": "Security notifications are always sent."
      },
      {
        "notification": "collection-deleted",
        "email": false,
        "locked": false,
        "locked_reason": null
      }
    ]
  }
}