Skip to content
Xplor-H2O
Sign inJoin free

Xplor-H2O API, version 1

The website and the phone apps use this same API. Machine-readable description: /api/v1/openapi.json (OpenAPI 3.1).

Me

  • GET/api/v1/me Signed in

    The signed-in person: roles, the pages and places they can act as.

  • GET/api/v1/me/roles Signed in

    Roles a person can hold, with their status for each.

  • POST/api/v1/me/roles Signed in, email confirmed

    Apply for a role (Captain, Trainer, Club Manager, ...). Roles that need approval wait for Host Admin.

  • GET/api/v1/me/follows Signed in

    Places and pages you follow (a bookmark list; there is no activity feed).

  • POST/api/v1/me/follows Signed in

    Follow a place or page.

  • DELETE/api/v1/me/follows/{entityId} Signed in

    Stop following a place or page.

  • GET/api/v1/me/saved Signed in

    Your saved places and listings (the phone apps keep these for offline use).

  • POST/api/v1/me/saved Signed in

    Save a place or listing.

  • DELETE/api/v1/me/saved/{targetKind}/{targetId} Signed in

    Remove a saved place or listing.

  • GET/api/v1/me/reviews Signed in

    Reviews you've written and where each one stands.

  • GET/api/v1/me/listings Signed in

    Your marketplace listings.

  • POST/api/v1/me/switch/return Signed in

    End a switch and return to the Super Admin's own account. Only while a Super Admin is signed in as this account. Signing out does the same.

Pages

  • POST/api/v1/pages Signed in, email confirmed

    Create a provider page, club or organization. Needs the matching active role; starts as a draft.

  • GET/api/v1/pages/{ref} Public

    A page by its web name. Drafts and private pages only for their staff.

  • PATCH/api/v1/pages/{ref} Signed in

    Edit a page's details. Needs page.edit on the page.

  • POST/api/v1/pages/{ref}/submit Signed in, email confirmed

    Send a draft page to Host Admin for review. Needs page.publish.

  • GET/api/v1/pages/{ref}/staff Signed in

    People who hold positions on a page or location. Needs page.view or location.view.

  • POST/api/v1/pages/{ref}/staff Signed in, email confirmed

    Invite someone by email to a position on a page or location. Needs page.staff or location.staff. Each person uses their own account.

  • DELETE/api/v1/pages/{ref}/staff/{memberId} Signed in

    Remove a position. The last manager can't be removed.

  • POST/api/v1/invitations/{token}/accept Signed in, email confirmed

    Accept a staff invitation sent to your email.

Locations

  • GET/api/v1/location-types Public

    Kinds of place.

  • GET/api/v1/locations Public

    Search published places by text, type, distance (near + radiusKm) or map area (bbox = west,south,east,north).

  • GET/api/v1/locations/{ref} Public

    A place, with its approved Access-by-Water information.

  • POST/api/v1/locations Signed in, email confirmed

    Add a place. Member-added places wait for Host review before they are public.

  • PATCH/api/v1/locations/{ref} Signed in

    Edit a place's business details (hours, prices, amenities, contact). Location managers (location.edit) or Host Admin: Locations. Access-by-Water is separate and Host-approved.

  • POST/api/v1/locations/{ref}/claims Signed in, email confirmed

    Claim a place you run. Host Admin checks the evidence; approval makes you its manager.

  • GET/api/v1/locations/{ref}/access Signed in

    Approach-information versions for a place: the published one, proposals and history. The place's managers and Host Admin: Locations.

  • POST/api/v1/locations/{ref}/access Signed in, email confirmed

    Propose new approach information (managers), or publish it directly (Host Admin: Locations, publish=true). Nothing a manager sends is public until Host Admin approves it. Every published version carries the not-for-navigation notice.

Media

  • POST/api/v1/media Signed in, email confirmed

    Start an upload: returns where to PUT the file. Then call /media/{id}/complete. Images (JPEG, PNG, WebP, HEIC) up to 15 MB; PDF evidence up to 15 MB. Uploads to object storage when configured.

  • POST/api/v1/media/{id}/complete Signed in, email confirmed

    Finish an upload: the file is checked, measured and thumbnailed.

Admin

  • GET/api/v1/admin/role-applications Signed in

    Role applications waiting for a decision. Host Admin with two-factor sign-in on. Sub-role: Providers.

  • POST/api/v1/admin/role-applications/{id}/decide Signed in

    Approve or reject a role application. Host Admin with two-factor sign-in on.

  • GET/api/v1/admin/pages Signed in

    Pages by status (default: waiting for review). Host Admin with two-factor sign-in on. Sub-role: Providers.

  • POST/api/v1/admin/pages/{id}/decide Signed in

    Approve (publish) or send back a page; or suspend an active one. Host Admin with two-factor sign-in on.

  • GET/api/v1/admin/claims Signed in

    Location claims. Host Admin with two-factor sign-in on. Sub-role: Locations.

  • POST/api/v1/admin/claims/{id}/decide Signed in

    Approve a claim (the claimant becomes Location Manager) or reject it. Host Admin with two-factor sign-in on.

  • GET/api/v1/admin/locations Signed in

    Places by visibility (default: waiting for review). Host Admin with two-factor sign-in on. Sub-role: Locations.

  • POST/api/v1/admin/locations/{id}/decide Signed in

    Publish or hide a place. Host Admin with two-factor sign-in on.

  • GET/api/v1/admin/media Signed in

    Uploaded media waiting for moderation. Host Admin with two-factor sign-in on. Sub-role: Content Moderator.

  • POST/api/v1/admin/media/{id}/decide Signed in

    Approve or reject uploaded media. Host Admin with two-factor sign-in on.

  • GET/api/v1/admin/users Signed in

    Find accounts by name or email. Host Admin with two-factor sign-in on. Sub-role: Users or Support.

  • POST/api/v1/admin/users/{id}/roles Signed in

    Grant or remove a role. Host Admin with two-factor sign-in on. Host Admin roles: Super Admin only. Other roles: Users or Providers.

  • POST/api/v1/admin/users/{id}/status Signed in

    Suspend or reinstate an account (signs them out everywhere). Host Admin with two-factor sign-in on. Sub-role: Users.

  • GET/api/v1/admin/audit Signed in

    The audit log, newest first. Host Admin with two-factor sign-in on. Sub-role: Super, Users, Risk or Support.

  • GET/api/v1/admin/contributions Signed in

    Reviews by state (default: waiting). Host Admin with two-factor sign-in on. Sub-role: Content Moderator.

  • POST/api/v1/admin/contributions/{id}/decide Signed in

    Publish, reject, or take down a review. Host Admin with two-factor sign-in on.

  • GET/api/v1/admin/reports Signed in

    Reported content. Host Admin with two-factor sign-in on. Sub-role: Content Moderator (reviews, photos) or Marketplace (listings).

  • POST/api/v1/admin/reports/{id}/decide Signed in

    Take the reported content down (closes every open report on it) or dismiss the report. Host Admin with two-factor sign-in on.

  • GET/api/v1/admin/listings Signed in

    Marketplace listings by state (default: waiting for review). Host Admin with two-factor sign-in on. Sub-role: Marketplace.

  • POST/api/v1/admin/listings/{id}/decide Signed in

    Approve, reject or take down a listing. Host Admin with two-factor sign-in on.

  • GET/api/v1/admin/access Signed in

    Approach-information proposals (default: waiting). Host Admin with two-factor sign-in on. Sub-role: Locations.

  • POST/api/v1/admin/access/{id}/decide Signed in

    Approve (publish, with the date it was checked) or reject an approach-information proposal. Host Admin with two-factor sign-in on.

  • GET/api/v1/admin/settings Signed in

    Platform settings, with placeholders for decisions the owner hasn't made yet. Host Admin with two-factor sign-in on. Any Host Admin may read; Super Admin edits.

  • PATCH/api/v1/admin/settings/{key} Signed in

    Change a setting (the same JSON type as before). Clears its placeholder flag. Host Admin with two-factor sign-in on. Super Admin only.

  • POST/api/v1/admin/users/{id}/switch Signed in

    Sign in as another user (switch user). Super Admin with two-factor on, re-checked with a current authenticator code. Not into Host Admins, Super Admins or suspended accounts. Lasts 60 minutes; while it lasts this session acts as the account and Host Admin tools are off. Audited.

  • GET/api/v1/admin/switches Signed in

    Switch-user history, newest first. Host Admin with two-factor sign-in on. Sub-role: Super or Risk.

Reviews

  • GET/api/v1/reviews Public

    Published reviews of one place or page (plus your own, whatever its state), with the rating summary.

  • POST/api/v1/reviews Signed in, email confirmed

    Review a place or a provider/club page. One live review per person per target; it waits for Host moderation before it is public. People who hold a position on the target can't review it. Daily limit: setting reviews.daily_limit.

  • PATCH/api/v1/reviews/{id} Signed in, email confirmed

    Edit your review. It goes back to moderation.

  • DELETE/api/v1/reviews/{id} Signed in

    Withdraw your own review. Nobody else can delete a review; report it instead.

  • POST/api/v1/reviews/{id}/response Signed in, email confirmed

    Reply publicly to a review of a place or page you run (null removes the reply). Needs location.respond on the place, or page.edit on the page.

  • POST/api/v1/reports Signed in, email confirmed

    Report a review, listing or photo to the moderators.

Marketplace

  • GET/api/v1/listing-categories Public

    Marketplace categories.

  • GET/api/v1/listings Public

    Browse live listings by text, category, distance (near + radiusKm) or map area (bbox). Newest first.

  • GET/api/v1/listings/{ref} Public

    One listing. Pending, sold and withdrawn listings only for the seller and Host Admin. The seller's contact details (contact) are included for signed-in members only.

  • POST/api/v1/listings Signed in, email confirmed

    List a personal item for sale (free). It waits for Host review; add photos with /media (contextKind listing). Give contactPhone and/or contactEmail (at least one): buyers contact you directly. The price is the seller's asking price, for display only. Settings: marketplace.listing_days, marketplace.max_open_listings.

  • PATCH/api/v1/listings/{ref} Signed in, email confirmed

    Edit your listing. Changing the title, description or category sends it back to review. Contact details can be changed but not both removed.

  • POST/api/v1/listings/{ref}/status Signed in, email confirmed

    Mark your listing sold, withdraw it, or relist it (renews the expiry).

Search

  • GET/api/v1/search Public

    Search everything at once: places, provider pages (captains, charters, scuba, rentals, ...), clubs and marketplace items, grouped by kind.

  • GET/api/v1/geocode Public

    Address search (MapTiler Geocoding, called server-side). Returns 503 not_configured when no key is set. Cached for a day; 20 searches a minute per person or IP.