Getting Started API and SDK

Quick start

Three things: load the bundle, mount the element, and tell the platform when a step is really finished. The checklist itself — steps, their texts, the theme — lives in the console, not in your code.

1. Load the bundle and mount the widget

Paste this into the layout your authenticated app already has. The element boots itself: it reads the project config, generates a visitor id for people you don't know yet, fetches their progress, and renders.

<script
  src="https://gettingstarted.marthaia.com/sdk/v1/gs.min.js"
  defer></script>

<getting-started
  endpoint="https://gettingstarted.marthaia.com"
  project-key="pk_your_publishable_key"
  user-id="u_1234"
  locale="en"></getting-started>

• project-key is the project's publishable key (pk_…). It ships to browsers by design; the secret key never does.
• user-id is optional. Omit it while you don't know who is looking and the widget tracks an anonymous visitor instead; hand it over later and the anonymous history is merged into that user once.
• disabled on the element renders nothing — a kill switch you can ship ahead of a rollout.

2. Report a step from your app

The SDK tells you when a step is clicked, but almost nothing is finished by a click. When the real event happens in your own code, say so and the widget re-renders:

const gs = document.querySelector('getting-started')

await gs.complete('first_project')   // POST /complete → the new state
console.log(gs.state.progress.percent)

3. Or report it from your backend

For events your browser never sees — a payment settled, an integration connected — use the secret key server-to-server. It never leaves your server.

curl -X POST https://gettingstarted.marthaia.com/api/gs/v1/server/complete \
  -H "X-GS-Secret: sk_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{"userId":"u_1234","stepKey":"first_payment"}'

{
  "data": {
    "subjectId": "k9f2xq1m4b7w3zt",
    "locale": "en",
    "dismissed": false,
    "completed": ["first_payment", "first_project"],
    "steps": [
      { "key": "first_project", "completed": true },
      { "key": "first_payment", "completed": true },
      { "key": "invite_teammate", "completed": false }
    ],
    "progress": { "completed": 2, "total": 3, "nextKey": "invite_teammate", "percent": 67 },
    "version": 7
  }
}

Both keys are in the console at /preview/keys — every section has its own URL (/preview/steps, /preview/users, /preview/stats, …), so a page can be bookmarked, shared and reloaded. A key is handed over when it is created, and it can be shown again at any time from that screen: the platform keeps an encrypted copy beside the hash it authenticates with, and only your account can read it. When a credential has to be replaced, rotate it rather than revoking it and starting over.

Embedding

The widget is one custom element, <getting-started>, built from a plain script tag with no bundler and no framework, and a thin React wrapper for hosts that would rather pass props.

Attributes

Every attribute is observed. Values in the Default column marked "theme" come from the project config fetched at boot, not from the element.

Host behaviour

• What reboots the widget: endpoint, project-key, locale and visitor-id — the config and state are read again. theme, position, layout and z-index re-render in place.
• Two bundles, one element: /sdk/v1/gs.min.js (IIFE — registers the tag and exposes window.GS) and /sdk/v1/gs.esm.js (ESM). Load one of them, never both: each carries its own copy of the class and the first registration wins.
• npm, if you prefer: import '@gs/web' registers <getting-started>; defineGettingStarted('my-checklist') picks a different tag name.
• SSR-safe: importing @gs/web on the server touches no window and no document; the React wrapper renders the element tag and hydrates on the client.
• Shadow DOM: the widget owns its styles, so it cannot collide with yours. Hosts style it through the --gs-* custom properties and the part="…" hooks — see Theming.
• Accessibility: the panel and the sheet are labelled dialogs, the sheet traps focus, Esc closes both, the mobile peek is a role="button" operable with Enter/Space, and prefers-reduced-motion disables the entry animations.
• No third-party requests: the bundle has zero runtime dependencies and calls nothing but your endpoint.

Metadata

A checklist is rarely just a checklist: which plan someone is on, whether they are an admin, which cohort they signed up in. Pass those facts as meta and they are stored with the subject, sent back on every read, and visible in the console's Users tab. The server never interprets them.

<getting-started
  endpoint="https://gettingstarted.marthaia.com"
  project-key="pk_your_publishable_key"
  meta='{"plan":"pro","tenant":"acme"}'></getting-started>

Any call may carry metadata, and what arrives is merged into what is stored. From the imperative API:

// Identifying is the natural moment to say who this user is.
await widget.identify('u_4821', { plan: 'team', seats: 12 })

// Or later, when the host learns something new — this persists immediately.
await widget.setMeta({ plan: 'enterprise' })

// Read back what every call currently carries.
widget.meta

Shape

A flat JSON object of strings, numbers, booleans or null. Nested objects and arrays are refused.

Size

At most 1 KB of serialised JSON, 24 keys, 40-character key names and 200-character string values. A bigger payload is refused with meta_too_large, never truncated.

Merging

Keys merge over what is already stored. Sending null for a key deletes it.

Never sent

Omit meta and nothing changes: existing metadata is kept, and a subject that never had any has no meta field at all.

Not for secrets

This is not a place for personal data or credentials — it is handed to the widget in plain sight and rendered in the console.

A malformed meta attribute is reported through the gs:error event rather than silently ignored.

React

The wrapper maps props to attributes (projectKey → project-key), events to callbacks, and exposes the imperative API through a ref. React is a peer dependency; it is never bundled.

import { GettingStarted, useGettingStarted } from '@gs/react'

export function App({ me }) {
  return (
    <GettingStarted
      endpoint="https://gettingstarted.marthaia.com"
      projectKey="pk_your_publishable_key"
      userId={me?.id}
      locale="en"
      onStepCompleted={(key, state) => console.log(key, state.progress)}
      onCompletedAll={() => celebrate()}
      onError={(error) => console.warn('gs', error.code, error.message)}
    />
  )
}

// imperative API + live state
function Progress() {
  const gs = useGettingStarted()
  return (
    <>
      <getting-started ref={gs.ref} endpoint="https://gettingstarted.marthaia.com"
        project-key="pk_your_publishable_key" user-id="u_1234" />
      <p>{gs.state?.progress.percent}%</p>
      <button onClick={() => gs.complete('first_project')}>I shipped it</button>
    </>
  )
}

The wrapper's ref (and useGettingStarted()) exposes element, state, complete, identify, refresh, open, close, dismiss, reset, getState, getConfig and setState.

Events

Every event is a bubbling, composed CustomEvent dispatched on the element, so a listener anywhere in your app can hear it.

const gs = document.querySelector('getting-started')

gs.addEventListener('gs:step-completed', (event) => {
  const { key, state } = event.detail
  track('checklist_step', { key, percent: state.progress.percent })
})

gs.addEventListener('gs:error', (event) => {
  const { code, message, status } = event.detail
  report(code, message, status)
})

The SDK's own error codes, which never come from the API, are network_error (the request failed or timed out), invalid_response (a response missing its data envelope), not_configured (no config, no endpoint or no key), unsupported and sdk_error.

JavaScript API

Everything the widget does is available to the host on the element itself.

Methods

The methods that talk to the API reject with the error they got, and emit gs:error. Await them in a try/catch if a failure needs to change what your app does next.

Properties

Draft previews

The console's Preview tab builds the widget with unsaved changes by injecting the config as a property. With no endpoint and no project-key, nothing ever leaves the browser:

const el = document.createElement('getting-started')
el.configOverride = myConfig   // a whole /config payload
el.setAttribute('locale', 'en')
document.body.appendChild(el)

el.setState({ completed: ['first_project'] })   // drive the UI locally

These two members are additive: with both endpoint and project-key set, state calls still reach the server; without them, complete, dismiss and reset change only the local state.

REST API

Everything the widget does is a documented HTTP call you can make yourself — from a browser with the publishable key, from your backend with the secret key, and from the console with your account session.

Conventions

Rate limits

Exceeding a budget answers 429 with a Retry-After header (seconds) and the rate_limited code.

curl https://gettingstarted.marthaia.com/api/gs/v1/config?locale=en \
  -H "X-GS-Key: pk_your_publishable_key"

{
  "data": {
    "project": { "id": "2yz1a0b9c8d7e6f", "slug": "snkconnect", "name": "SNKConnect" },
    "defaultLocale": "en",
    "locales": ["en", "fr"],
    "version": 7,
    "desktopLayout": "panel",
    "mobileLayout": "peek",
    "completedBehavior": "hide",
    "theme": { "...": "see Theming" },
    "customCss": null,
    "steps": [
      {
        "key": "first_project",
        "position": 1,
        "actionUrl": "/projects/new",
        "openInNewTab": false,
        "icon": "🚀",
        "required": true,
        "enabled": true,
        "texts": {
          "label": "Create your first project",
          "description": "Everything else starts here.",
          "doneText": "Project created",
          "ctaText": "Create"
        }
      }
    ]
  }
}

curl "https://gettingstarted.marthaia.com/api/gs/v1/state?userId=u_1234&locale=en" \
  -H "X-GS-Key: pk_your_publishable_key"

{
  "data": {
    "subjectId": "k9f2xq1m4b7w3zt",
    "locale": "en",
    "meta": { "plan": "pro", "tenant": "acme" },
    "dismissed": false,
    "completed": ["first_payment", "first_project"],
    "steps": [
      { "key": "first_project", "completed": true },
      { "key": "first_payment", "completed": true },
      { "key": "invite_teammate", "completed": false }
    ],
    "progress": { "completed": 2, "total": 3, "nextKey": "invite_teammate", "percent": 67 },
    "version": 7
  }
}

curl -X POST https://gettingstarted.marthaia.com/api/gs/v1/complete \
  -H "X-GS-Key: pk_your_publishable_key" \
  -H "Content-Type: application/json" \
  -d '{"userId":"u_1234","stepKey":"first_project","locale":"en"}'

{
  "data": {
    "subjectId": "k9f2xq1m4b7w3zt",
    "locale": "en",
    "dismissed": false,
    "completed": ["first_project"],
    "steps": [
      { "key": "first_project", "completed": true },
      { "key": "first_payment", "completed": false },
      { "key": "invite_teammate", "completed": false }
    ],
    "progress": { "completed": 1, "total": 3, "nextKey": "first_payment", "percent": 33 },
    "version": 7
  }
}

{
  "data": {
    "subjectId": "k9f2xq1m4b7w3zt",
    "locale": "en",
    "dismissed": true,
    "completed": ["first_project"],
    "steps": [
      { "key": "first_project", "completed": true },
      { "key": "first_payment", "completed": false },
      { "key": "invite_teammate", "completed": false }
    ],
    "progress": { "completed": 1, "total": 3, "nextKey": "first_payment", "percent": 33 },
    "version": 7
  }
}

{
  "data": {
    "subjectId": "k9f2xq1m4b7w3zt",
    "locale": "en",
    "dismissed": false,
    "completed": [],
    "steps": [
      { "key": "first_project", "completed": false },
      { "key": "first_payment", "completed": false },
      { "key": "invite_teammate", "completed": false }
    ],
    "progress": { "completed": 0, "total": 3, "nextKey": "first_project", "percent": 0 },
    "version": 7
  }
}

curl -X POST https://gettingstarted.marthaia.com/api/gs/v1/identify \
  -H "X-GS-Key: pk_your_publishable_key" \
  -H "Content-Type: application/json" \
  -d '{"visitorId":"v_9Kd2mQ4pLz1rTb7n","userId":"u_1234"}'

{
  "data": {
    "subjectId": "k9f2xq1m4b7w3zt",
    "locale": "en",
    "dismissed": false,
    "completed": ["first_project"],
    "steps": [
      { "key": "first_project", "completed": true },
      { "key": "first_payment", "completed": false },
      { "key": "invite_teammate", "completed": false }
    ],
    "progress": { "completed": 1, "total": 3, "nextKey": "first_payment", "percent": 33 },
    "version": 7
  }
}

curl -N "https://gettingstarted.marthaia.com/api/gs/v1/stream?key=pk_your_publishable_key&userId=u_1234"

event: progress
data: {"subjectId":"k9f2xq1m4b7w3zt","completed":["first_project"],"version":7}

: heartbeat

{ "data": { "presets": [
  { "id": "martha", "name": "Martha IA", "description": "…", "theme": { "accentColor": "#EF562F", … } },
  { "id": "indigo", "name": "Indigo", "description": "…", "theme": { … } }
] } }

curl -X POST https://gettingstarted.marthaia.com/api/gs/v1/server/complete \
  -H "X-GS-Secret: sk_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{"userId":"u_1234","stepKey":"first_payment"}'

{
  "data": {
    "subjectId": "k9f2xq1m4b7w3zt",
    "locale": "en",
    "dismissed": false,
    "completed": ["first_payment"],
    "steps": [
      { "key": "first_project", "completed": false },
      { "key": "first_payment", "completed": true },
      { "key": "invite_teammate", "completed": false }
    ],
    "progress": { "completed": 1, "total": 3, "nextKey": "first_project", "percent": 33 },
    "version": 7
  }
}

curl -X POST https://gettingstarted.marthaia.com/api/gs/v1/server/state \
  -H "X-GS-Secret: sk_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{"userId":"u_1234"}'

{
  "data": {
    "subjectId": "k9f2xq1m4b7w3zt",
    "locale": "en",
    "dismissed": false,
    "completed": ["first_payment"],
    "steps": [
      { "key": "first_project", "completed": false },
      { "key": "first_payment", "completed": true },
      { "key": "invite_teammate", "completed": false }
    ],
    "progress": { "completed": 1, "total": 3, "nextKey": "first_project", "percent": 33 },
    "version": 7
  }
}

curl -X POST https://gettingstarted.marthaia.com/api/gs/v1/admin/projects/2yz1a0b9c8d7e6f/keys \
  -H "Authorization: your_account_session" \
  -H "Content-Type: application/json" \
  -d '{"type":"publishable","label":"production"}'

{
  "data": {
    "id": "k8m2p4q6r8s0t2u",
    "key": "pk_2yz1a0b9c8d7e6f_9xQ2vLm4Tz1rB7nWc8Ka5Pd3Fg6Hj0Kq",
    "prefix": "pk_2yz1a0b9c",
    "type": "publishable",
    "label": "production",
    "revealable": true
  }
}

{
  "data": {
    "id": "k8m2p4q6r8s0t2u",
    "prefix": "pk_2yz1a0b9c",
    "revoked": true
  }
}

{
  "data": {
    "id": "k8m2p4q6r8s0t2u",
    "key": "pk_2yz1a0b9c8d7e6f_9xQ2vLm4Tz1rB7nWc8Ka5Pd3Fg6Hj0Kq",
    "prefix": "pk_2yz1a0b9c",
    "type": "publishable",
    "label": "production",
    "revealable": true
  }
}

{
  "data": {
    "id": "m4n6p8q0r2s4t6u",
    "key": "pk_2yz1a0b9c8d7e6f_A1b2C3d4E5f6G7h8J9k0L1m2N3o4P5q",
    "prefix": "pk_2yz1a0b9c",
    "type": "publishable",
    "label": "production",
    "revealable": true,
    "revokedKeyId": "k8m2p4q6r8s0t2u"
  }
}

{
  "data": {
    "subjects": 1284,
    "completions": 5310,
    "dismissed": 214,
    "completedAll": 356,
    "dismissRate": 0.1667,
    "perStep": { "first_project": 842, "first_payment": 511, "invite_teammate": 129 }
  }
}

{
  "data": {
    "items": [
      {
        "id": "5agfb5nbdc0si7b",
        "userId": "user-42",
        "visitorId": "v_9f1c…",
        "locale": "fr",
        "disabled": false,
        "dismissed": false,
        "completed": 2,
        "total": 3,
        "percent": 67,
        "lastSeenAt": "2026-09-26 14:54:40.425Z",
        "completedAt": ""
      }
    ],
    "totalItems": 1284,
    "requiredTotal": 3,
    "limit": 50,
    "offset": 0
  }
}

{
  "data": { "subjectId": "5agfb5nbdc0si7b", "disabled": true }
}

{
  "data": {
    "subjectId": "k9f2xq1m4b7w3zt",
    "locale": "en",
    "dismissed": false,
    "completed": [],
    "steps": [
      { "key": "first_project", "completed": false },
      { "key": "first_payment", "completed": false },
      { "key": "invite_teammate", "completed": false }
    ],
    "progress": { "completed": 0, "total": 3, "nextKey": "first_project", "percent": 0 },
    "version": 7
  }
}

{
  "data": {
    "deleted": true,
    "subjectId": "k9f2xq1m4b7w3zt"
  }
}

Theming

The theme lives on the project and arrives inside the config. The widget renders in a shadow root, so your page's CSS cannot reach in, and only the properties below reach out. A project that has never been themed still renders: every missing field falls back to the default theme.

Ready-made themes

You do not have to design a theme to have one. Six presets ship with the product and are also served at GET /api/gs/v1/themes. Each is a complete theme — colours, radius, font, texts and icons — so applying one cannot leave a field behind. The console's Theme tab shows them as swatches; pick one, then adjust anything you like.

Theme fields

Texts, and where each one appears

The shipped defaults are French, because the product's first project was — override them for your own language. Step labels and descriptions are not here: they come from each step's translations.

The subtitle is an ICU plural: {count, plural, =0 {…} one {# …} other {# …}}, with count, completed, total and percent available to it. The dismissal copy takes the same variables.

Dismissing a checklist that is not finished asks first: it used to be one silent click with no way back, so a visitor could lose their checklist without meaning to. A checklist at 100% is still dismissed in one click, and dismiss() — the host's own call — stays immediate either way.

A theme, in full

{
  "mode": "auto",
  "accentColor": "#E5352B",
  "accentTextColor": "#FFFFFF",
  "backgroundColor": "#111111",
  "surfaceColor": "rgba(255,255,255,0.06)",
  "textColor": "#FFFFFF",
  "mutedTextColor": "rgba(255,255,255,0.45)",
  "borderColor": "rgba(255,255,255,0.08)",
  "radius": 16,
  "fontFamily": "DM Sans, system-ui, sans-serif",
  "panelWidth": 360,
  "peekOffset": 74,
  "progressStyle": "bar",
  "zIndex": 2147483000,
  "breakpoint": 1024,
  "position": "right",
  "icons": { "peek": "👋", "close": "×", "arrow": "→" },
  "texts": {
    "title": "Getting started",
    "subtitle": "{count, plural, =0 {All done.} one {# action left.} other {# actions left.}}",
    "nextCta": "Next step",
    "noteTitle": "You don't have to follow an order.",
    "noteBody": "Complete the actions that matter to you.",
    "continue": "Continue",
    "dismiss": "Hide",
    "close": "Close",
    "reopen": "Getting started",
    "dismissTitle": "Hide the checklist?",
    "dismissBody": "{count, plural, =0 {All done.} one {# action left.} other {# actions left.}} Your progress is saved.",
    "dismissLater": "Back at my next visit",
    "dismissNever": "Don't show it again",
    "dismissCancel": "Cancel"
  },
  "textsByLocale": {
    "fr": { "title": "Bien démarrer", "nextCta": "Prochaine étape" }
  }
}

Styling from the host

The theme is applied to the element as CSS custom properties, so a host can override any of them from its own stylesheet. Values you set before the widget's first render win over the config.

getting-started {
  --gs-accent: #7C3AED;
  --gs-panel-width: 400px;
  --gs-peek-offset: 88px;   /* clear your bottom nav */
  --gs-breakpoint: 900px;   /* host-only: where the peek takes over */
}

• The properties are --gs-accent, --gs-accent-text, --gs-bg, --gs-surface, --gs-text, --gs-muted, --gs-border, --gs-radius, --gs-font, --gs-z-index, --gs-panel-width and --gs-peek-offset. --gs-breakpoint exists only for the host — it is not part of the theme.
• customCss on the project is injected into the shadow root after the built-in stylesheet, for anything the properties cannot reach.
• Structural parts carry part names — panel, sheet, peek, handle, launcher, step, backdrop — so you can style them with ::part() from your own CSS.

Errors

Every failure — validation, key, origin, limit — uses one envelope. The HTTP status says how to react; code says what happened, and is stable enough to branch on.

{
  "error": {
    "code": "invalid_step",
    "message": "Unknown step key",
    "details": { "stepKey": "foo" }
  }
}

details appears only when there is something structured to say — invalid_step carries stepKey, origin_not_allowed carries origin, and rate_limited carries retryAfterSeconds in addition to the Retry-After header.

Two statuses are not errors: 304 from /config when your If-None-Match still matches, and 204 from the CORS preflight. One documented code, 409 conflict, is reserved but no v1 endpoint returns it.

AI prompt

The fastest installation is to hand the job to a coding assistant. Each prompt below is self-contained — it names the endpoint, the file to edit and the attributes to set — so the assistant answers with a diff instead of a guess. Replace pk_… and sk_… with your own keys from the console, and the step key with one of the steps you configured there. These are the same three prompts the landing page shows, from one file, so the site and this reference cannot disagree about how the widget is installed.

Add the Getting Started onboarding checklist to this project. Two edits, no package, no wrapper component.

1. Load the widget once, just before </body> in the app's main layout:
<script src="https://gettingstarted.marthaia.com/sdk/v1/gs.min.js" defer></script>

2. Render it once, in the layout that signed-in users see:
<getting-started
  endpoint="https://gettingstarted.marthaia.com"
  project-key="pk_REPLACE_WITH_MY_KEY"
  user-id="REPLACE_WITH_MY_USER_ID"
  locale="en"></getting-started>

Rules: user-id must be my app's stable id for the signed-in user, because that is what progress is stored against; if nobody is signed in yet, omit user-id and the widget keeps progress per browser. locale should follow the user's language. Do not restyle the widget with CSS — it renders inside a shadow root and takes its colours from the project theme.

Wire the Getting Started checklist into this Next.js app (App Router).

1. Load the script once, in app/layout.tsx:
import Script from 'next/script'
<Script src="https://gettingstarted.marthaia.com/sdk/v1/gs.min.js" strategy="afterInteractive" />

2. Render the widget in the authenticated layout only, e.g. app/(app)/layout.tsx:
<getting-started
  endpoint="https://gettingstarted.marthaia.com"
  project-key="pk_REPLACE_WITH_MY_KEY"
  user-id={session.user.id}
  locale={locale} />

3. It is a custom element, so declare it once for TypeScript:
declare global {
  namespace JSX {
    interface IntrinsicElements {
      'getting-started': { endpoint?: string; 'project-key'?: string; 'user-id'?: string; locale?: string }
    }
  }
}

Do not write a React wrapper or a context provider: the element fetches its own config and keeps its own state.

Mark a checklist step complete from my backend when the user actually does the thing, instead of waiting for them to click it.

POST https://gettingstarted.marthaia.com/api/gs/v1/server/complete
X-GS-Secret: sk_REPLACE_WITH_MY_SECRET_KEY
Content-Type: application/json

{"userId":"REPLACE_WITH_MY_USER_ID","stepKey":"REPLACE_WITH_MY_STEP_KEY"}

Call this after the transaction that performs the action commits. Treat a non-2xx as a logged warning, never as a reason to fail the user's action. Keep the secret key on the server — it must never reach the browser. The widget shows the change on its next state fetch.

Replace pk_… and sk_… with your own keys from the console — and the step key with one of the steps you configured there. Nothing in these prompts is tied to a framework version, and none of them asks an assistant to invent an API: every endpoint they name is documented in full in the reference.