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.
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.
idstring (uuid)
Identifier of the user this relation is about.
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_idstring (uuid)
Identifier of the person, the user the session token names.
organization_idstring (uuid)
Identifier of the organization. It is what every organization-scoped operation takes as its organization_id path parameter.
organization_namestring
The organization's display name, as it appears to its members.
organization_capabilitiesarray of string
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_entitlementsarray of string
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.
rolestring
One of: owner, admin, contributor, viewer
What this person may do in this organization.
joined_atstring (date-time)
When the person joined: when the invitation was accepted, or when the organization was created for its owner.
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.
languagestring
One of: en, fr, es, it, de, zh, ja
The language user-facing content is written in.
themestring
One of: auto, light, dark
The color theme the interface is painted in.
lengthstring
One of: metric, imperial
The measurement system distances, elevations and lengths are shown in.
pacestring
One of: per-time, per-distance
The form a travel rate is shown in, time over distance or distance over time.
slopestring
One of: degrees, percentage
The unit a gradient is shown in.
temperaturestring
One of: celsius, fahrenheit
The unit a temperature is shown in.
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_idstring (uuid)
Identifier of the organization the notifications are about.
user_idstring (uuid)
Identifier of the member, the user the session token names.
notificationsarray of NotificationPreference
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.
/v1/me/organizationsReturns 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
cursorstring
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.
limitinteger (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.
extensionsobject
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.
dataarray of Membership
Errors 400, 401, 402, 403, 429, 500, 504. See Errors.
/v1/me/preferencesReturns 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.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataPreferences
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.
Errors 400, 401, 402, 403, 404, 429, 500, 504. See Errors.
/v1/me/preferencesChanges 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-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 preferences to change. Send only what is changing.
languagestring
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.
themestring
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.
lengthstring
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.
pacestring
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.
slopestring
in body
One of: degrees, percentage
The unit a gradient is shown in. Optional and not nullable: omit it to keep the current unit.
temperaturestring
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.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataPreferences
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.
Errors 400, 401, 402, 403, 404, 409, 413, 429, 500, 504. See Errors.
/v1/me/invitationsReturns 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
cursorstring
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.
limitinteger (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.
extensionsobject
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.
dataarray of UserInvitation
Errors 400, 401, 402, 403, 429, 500, 504. See Errors.
/v1/me/invitations/{invitation_id}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_idstring (uuid)
in path
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-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.
Response 200
The invitation is declined, or nothing with that identifier was waiting for this user. data is null.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataany | null
Always null: this operation answers with no payload.
Errors 400, 401, 402, 403, 404, 409, 429, 500, 504. See Errors.
/v1/me/invitations/{invitation_id}/acceptAccepts 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_idstring (uuid)
in path
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-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.
Response 200
The membership the invitation became, with the role it granted and joined_at set to the moment of acceptance.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataMembership
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.
Errors 400, 401, 402, 403, 404, 409, 429, 500, 504. See Errors.
/v1/me/organizations/{organization_id}/notification-preferencesReturns 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_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 notification emails the user receives about the organization.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataNotificationPreferences
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.
Errors 400, 401, 402, 403, 404, 429, 500, 504. See Errors.
/v1/me/organizations/{organization_id}/notification-preferencesTurns 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-changedormember-removed, is always sent: naming one is a400naming it, and nothing is changed. So is naminginvitation, 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_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.
Body
The notifications to turn on or off. Send only what is changing.
notificationsarray of NotificationPreferenceUpdate
in body
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.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataNotificationPreferences
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.
Errors 400, 401, 402, 403, 404, 409, 413, 429, 500, 504. See Errors.