Integration

Choose the right integration path for portal, SDK, REST, source imports, and automation.

Integrate Amend from the outside in: portal first, customer identity next, source evidence after that, and automation only once review rules are visible. This keeps the customer-facing path real while the agent layer matures.

Integration Map

Job	Use this surface	Details
Show roadmap, changelog, and feedback	Hosted portal or custom portal read endpoints	Customer surfaces
Add in-app request/update UI	`@amend/sdk` and `createAmendPanel`	Customer surfaces
Import GitHub/support/Slack evidence	Source event imports or signed GitHub webhooks	Source events
Control owner/admin records	Token-guarded REST or SDK owner methods	API reference
Tune proactive decisions	Automation rules plus review-first launch posture	Automation
Put docs and app on production hosts	`VITE_DOCS_URL`, docs host, Vercel rewrite/proxy	Production routing

Portal setup

Start with one workspace portal. Confirm these settings before inviting users:

Setting	Use
`workspaceSlug`	Stable public route for the portal
Roadmap visibility	Decides which roadmap items customers can inspect
Changelog visibility	Decides which shipped updates are public
Feedback mode	Open, authenticated, or closed intake
Custom copy	Explains what customers should submit

Local portal URLs can live under the web app. Production can use a custom domain or path once DNS is ready.

SDK Basics

Use the SDK when your product needs an update panel, request launcher, identity mapping, or user-specific shipped updates.

import { Amend } from "@amend/sdk";

const amend = new Amend({
  project: "amend-labs",
  apiBaseUrl: process.env.AMEND_API_BASE_URL ?? "/api/v1",
  token: process.env.AMEND_API_TOKEN,
});

Pass identity with stable IDs from your app, not display names alone:

await amend.identify({
  externalUserId: "user_456",
  accountId: "acct_123",
  email: "maya@example.com",
  name: "Maya",
  traits: { role: "admin" },
});

await amend.identifyAccount("acct_123", {
  name: "Northwind",
  plan: "enterprise",
});

Auth Rules

Public customer-facing reads and feedback writes do not require a token. Owner-level mutations use Authorization: Bearer <AMEND_API_TOKEN> when AMEND_API_TOKEN is configured in the Convex environment.

Auth level	Examples
Public	`GET portal`, `GET roadmap`, `GET changelog`, `POST feedback`
Customer	`POST identity`, `POST interactions`, `POST events`, unsubscribe
Owner	Projects, repositories, source imports, roadmap/changelog writes
Webhook	GitHub signature, Stripe signature, provider-specific verification

Production Links

The web app must not assume docs live at the same origin in every environment. Set VITE_DOCS_URL to the public docs root:

# local
VITE_DOCS_URL=http://docs.amend.localhost:1355/docs

# production product entry point
VITE_DOCS_URL=https://amend.sh/docs

# optional same-site proxy for self-hosted installs with their own routing
VITE_DOCS_URL=/docs

After this, product links can point to source-trace, integration, self-hosting, and launch without knowing where the docs app is deployed.