Embed API Reference

This reference covers the public surface used by the embeddable Martha chat client.

Distribution

Martha supports two v1 distribution paths:

• Hosted static assets for no-build hosts.
• Public npm package for framework apps and modern JavaScript builds.

Hosted Static Assets

All v1 embed assets are served from the canonical Martha app host:

https://martha.nomadriver.co/embed/v1/

Files:

• martha-chat.ce.js - custom element bundle
• martha-chat.es.js - ESM mount API
• martha-chat.react.js - React wrapper
• martha-chat.svelte.js - Svelte wrapper
• martha-chat.css - shared CSS

The recommended default for third-party developers is the custom element bundle:

<script type="module" src="https://martha.nomadriver.co/embed/v1/martha-chat.ce.js"></script>

Operators can print the current hosted URLs with:

martha clients embed urls

They can generate framework-specific snippets with:

martha clients embed snippet <client-key-or-name> --framework html
martha clients embed snippet <client-key-or-name> --framework react
martha clients embed snippet <client-key-or-name> --framework svelte
martha clients embed snippet <client-key-or-name> --framework esm

npm Package

Install:

npm install @aiaiai-pt/martha-chat

Exports:

Export	Description
@aiaiai-pt/martha-chat	Imperative mount API, client helpers, and shared types.
@aiaiai-pt/martha-chat/web-component	Defines <martha-chat> as a side effect and re-exports the base API.
@aiaiai-pt/martha-chat/react	React wrapper.
@aiaiai-pt/martha-chat/svelte	Svelte component exports.
@aiaiai-pt/martha-chat/css	Shared widget CSS.

React and Svelte are optional peer dependencies. They are only required when the host imports the corresponding framework entrypoint.

Package consumers should import the CSS explicitly:

import "@aiaiai-pt/martha-chat/css";

For the custom element entrypoint, the component renders in Shadow DOM. Bundled apps should pass a CSS asset URL:

import stylesheetUrl from "@aiaiai-pt/martha-chat/css?url";
import "@aiaiai-pt/martha-chat/web-component";

window.MarthaChat = {
  stylesheetUrl,
  getAccessToken: async () => "martha-or-embed-access-token"
};

Hosted custom-element installs get the stylesheet URL automatically because the JavaScript and CSS files are served from the same /embed/v1/ folder.

Web Component

Element name:

<martha-chat></martha-chat>

Common attributes:

Attribute	Required	Description
api-url	Yes	Base Martha URL, for example https://martha.example.com.
client-key	Yes	Martha Client key or client identifier configured for embedding.
selected-client-id	No	Legacy alias used as the selected Client id when client-key is absent. Prefer client-key for embeds.
launcher	No	Enables floating launcher mode. Without it, the widget renders inline.
placement	No	Launcher placement, usually bottom-right or bottom-left.
default-open	No	Opens the launcher widget immediately.
title	No	Chat title shown in the widget chrome.
placeholder	No	Composer placeholder text.
welcome-message	No	Initial welcome copy.
allow-uploads	No	Overrides manifest upload feature for this instance.
allow-feedback	No	Overrides manifest feedback feature for this instance.
token-provider	No	Name of a provider in window.MarthaChat.tokenProviders.
z-index	No	Launcher z-index.
stylesheet-url	No	Alternate CSS URL.

The default host page token provider is configured on window.MarthaChat:

window.MarthaChat = {
  getAccessToken: async () => "martha-or-embed-access-token"
};

For npm custom-element installs, window.MarthaChat.stylesheetUrl can point at the bundled @aiaiai-pt/martha-chat/css asset. The stylesheet-url HTML attribute can override it per widget instance.

For multiple widgets with different auth providers, set named providers and reference them with token-provider:

<martha-chat
  api-url="https://martha.nomadriver.co"
  client-key="sales"
  token-provider="sales"
></martha-chat>

<script>
  window.MarthaChat = {
    tokenProviders: {
      sales: async () => window.hostAuth.getSalesToken()
    }
  };
</script>

Do not pass tokens through HTML attributes.

Manifest

GET /api/embed/manifest/{client_key}
Origin: https://host.example.com

Returns the embed configuration for a Client if embeds are enabled and the request origin is allowlisted.

Example response:

{
  "client_key": "partner-client",
  "client_id": 42,
  "tenant_display_name": null,
  "default_mode": "launcher",
  "auth_modes": ["host-token", "embed-token"],
  "features": {
    "uploads": false,
    "history": false,
    "feedback": true,
    "voice": false
  },
  "theme": {}
}

Failure cases:

• 400 when Origin is missing or malformed.
• 403 when embeds are disabled or the origin is not allowed.
• 404 when the Client cannot be found.

Successful responses include:

Access-Control-Allow-Origin: <allowed-origin>
Vary: Origin

Embed Token

Embed-token mode uses a dedicated Keycloak confidential client per Martha Client. Admins provision that credential from Martha Admin or the CLI; host backends use it to obtain a service-account token.

Provision Credentials

POST /api/admin/clients/{client_id}/embed-credentials
Authorization: Bearer <human-admin-token>

Response:

{
  "client_id": 42,
  "client_key": "partner-client",
  "service_account_client_id": "martha-embed-partner-client-42",
  "client_secret": "secret-value",
  "token_endpoint": "https://keycloak.example.com/realms/martha/protocol/openid-connect/token",
  "created": true,
  "rotated": false,
  "embed_token_credentials_updated_at": "2026-05-09T20:00:00"
}

The secret is backend-only. Existing credentials are not returned again; rotate to issue a new secret.

Rotate Credentials

POST /api/admin/clients/{client_id}/embed-credentials/rotate
Authorization: Bearer <human-admin-token>

Returns the same shape as provisioning with rotated: true and the new secret.

Revoke Credentials

DELETE /api/admin/clients/{client_id}/embed-credentials
Authorization: Bearer <human-admin-token>

Response:

{
  "client_id": 42,
  "client_key": "partner-client",
  "service_account_client_id": "martha-embed-partner-client-42",
  "revoked": true
}

Revocation deletes the Keycloak service-account client and clears the Martha Client link.

Mint Token

POST /api/embed/tokens
Authorization: Bearer <embed-credential-service-account-or-super-admin-token>
Origin: https://host.example.com
Content-Type: application/json

Request:

{
  "client_key": "partner-client",
  "external_user_id": "host-user-123",
  "display_name": "Ada Lovelace",
  "session_id": "optional-session-id",
  "expires_in": 900
}

Response:

{
  "access_token": "eyJ...",
  "expires_in": 900,
  "token_type": "Bearer"
}

Rules:

• The caller must be the Client's dedicated embed credential service account or a Martha super admin.
• The Origin must be allowlisted for the Client.
• expires_in is bounded by the Martha embed token TTL configuration.
• The host backend owns user authentication before minting this token.
• The service account token and client secret must never be sent to the browser.

Scoped Uploads

POST /api/embed/sessions/{session_id}/uploads
Authorization: Bearer <embed-or-host-token>
Origin: https://host.example.com
Content-Type: multipart/form-data

The request must include a file field.

Response:

{
  "collection_id": 123,
  "document_id": 456,
  "filename": "example.pdf",
  "context": "Uploaded file example.pdf"
}

Rules:

• The Client must have the uploads embed feature enabled.
• The session must belong to the authenticated user and Client.
• The origin must be allowlisted.
• The upload is scoped to the active embed session.

This endpoint is separate from normal document collection APIs. It is designed so an embedded host can attach files to the current chat without receiving broad document collection permissions.

Origin Policy

Embed origins are exact http or https origins:

https://host.example.com
https://app.host.example.com
http://localhost:5173

Invalid origin values:

https://host.example.com/path
https://*.example.com
https://host.example.com?x=1

Production hosts should use HTTPS. Localhost origins are for development and depend on Martha's local embed origin setting.

Supported Auth Modes

host-token means the host browser already has a Martha-compatible user token and returns it from getAccessToken.

embed-token means the host backend mints a short-lived Martha embed token for its authenticated user.

Standalone PKCE login from arbitrary third-party host pages is deferred and is not a supported v1 embed mode.

Security Notes

• Treat the Client key as public configuration.
• Treat service tokens and embed token signing secrets as backend-only secrets.
• Allowlist only origins you control or have approved.
• Keep host permissions attached to the Martha Client; do not rely on client-side flags for authorization.
• Do not expose normal document collection APIs through embed tokens unless a later product decision explicitly adds that scope.