Skip to main content

​
Overview

The Nautilus API allows authorized external systems to interact with the Nautilus platform programmatically. The canonical API is read-only and tenant-scoped. It exposes your organization’s sites, products, checkout links, purchases, contacts, marketing signups, forms, vouchers, links, automations, surveys, cases, and cancellation records, plus Sonny’s POS data for supported organizations. Its machine-readable contract is available without authentication:

​
Base URL

​
Authentication

All data endpoints require a Bearer token passed in the Authorization header.
Requests with a missing or invalid token receive a 401 Unauthorized response. The Bearer prefix is required and case-sensitive.

​
Key types

Nautilus issues two kinds of API keys:
  • Tenant-scoped keys — bound to a specific organization. All canonical data endpoints require a tenant-scoped key. Sends are attributed to that tenant and use the tenant’s own sender identity (email from your slug-derived address on @mail.nautilus.co, SMS from your configured tenant phone number).
  • Platform keys — legacy Nautilus-issued keys that send as the Nautilus brand (SMS from the Nautilus shortcode, email from contact@mail.nautilus.co). Platform keys work only for the message and email send endpoints.
Most integrations use tenant-scoped keys. Contact Nautilus to provision one for your organization.

​
Tenant isolation

The organization bound to your API key is the only tenant scope. Requests cannot supply or override an organization ID. Collection queries are always scoped to your organization, and detail endpoints return 404 for both missing and cross-tenant IDs so resource existence is never disclosed. Responses are built from narrow public serializers. They do not expose API credentials, provider configuration, access tokens, webhook secrets, raw provider payloads, or internal workflow data. Form, signup, and survey answer payloads also have sensitive internal keys removed recursively.

​
Canonical resources

All canonical endpoints use GET and share the collection envelope and cursor pagination. The four /api/v1/pos/sonnys/* resources are provider-specific. They are available only when your organization has the supported Sonny’s Shared data source; other organizations receive the route’s documented 400 or 404. Cancellation records include normalized signup discounts (signupDiscounts, hadSignupDiscount) and first-year billing coverage (firstYearPayments, firstYearPaymentCoverage) built from normalized billing events.

​
Legacy endpoints

The following endpoints predate the canonical API. They remain available and unchanged, and are marked deprecated in the OpenAPI document: Analytics endpoints require tenant-scoped keys because they return organization-scoped data.

​
Legacy date parameters

Legacy analytics date filters are interpreted in UTC. For members, retention offers, cancellations, and cancellation survey, date-only lower bounds such as 2026-01-01 start at 2026-01-01T00:00:00.000Z. Date-only upper bounds include the full day and end at 23:59:59.999Z. Cohort start and end values are truncated to their month. Explicit timestamps are used as exact inclusive instants for the other analytics endpoints. Invalid date values are ignored unless an endpoint documents stricter validation. Canonical endpoints are stricter: timestamp filters such as createdAfter must include an explicit UTC offset, for example 2026-07-01T00:00:00Z.