Quickstart

Create an organization and API key, install the SDK, and make your first call.

This walks you from zero to your first Motif API call. You'll set up an organization, create a key, and either ask Clarity about a portfolio or profile a user.

---

1. Set up your organization

1. Sign in to the admin panel at admin.motifapp.ai.

2. Create an organization (or accept an invite to an existing one).

3. Wait for Motif to activate the organization. New organizations start in PENDING. API and SDK access is blocked until they're ACTIVE.

See Organization & team for the full lifecycle.

---

2. Create an API key

In the admin panel, go to Settings → API keys and create a key. Copy it immediately. Production keys are shown only once. The key's environment (production or sandbox) is inferred from the organization.

Treat the key like a password: it's an organization-wide secret and must never reach the browser. See API keys and Authentication.

---

3. Install the SDK

npm install @motif-ai/sdk

import { createClient } from '@motif-ai/sdk'

const motif = createClient({
  apiKey: process.env.MOTIF_API_KEY!,
  // baseURL defaults to https://api.motifapp.ai/api
})

The SDK is server-side only. For browser integrations, use the iframe embed.

---

4a. Ask Clarity about a portfolio

If you have customer holdings, ask Clarity for portfolio commentary in one call:

const card = await motif.clarity.card({
  portfolio: {
    currentHoldings: [
      { ticker: 'AAPL', quantity: 100 },
      { ticker: 'NVDA', quantity: 30 },
    ],
    profile: { riskTolerance: 'moderate' },
  },
})

console.log(card.marketContext)     // what's moving the market now
console.log(card.positionsAnalysis) // what's affecting these holdings

See Integrate Clarity for card, chat, and persisted portfolios.

---

4b. Profile a user

To build an investor profile, create a Motif user and run profiling against the questions you configured in the admin panel:

const user = await motif.users.create({
  email: '[e-mail]',
  name: 'Jane Smith',
  externalId: 'your_internal_user_123',
})

const userClient = motif.forUser(user.id)

const questions = await userClient.profile.getQuestions({ type: 'Basic' })
for (const question of questions) {
  await userClient.profile.saveAnswer({ questionId: question.id, answer: answerFor(question) })
}

const profile = await userClient.profile.computeInvestorProfile()
const strategy = await userClient.strategies.generate()

Your customers never need a Motif login. Your backend owns their authentication and passes the Motif user id through the SDK. See Profiling and Investment proposals.

---

Next steps

• Authentication: headers, environments, and rate limits

• Clarity: how the research engine works

• SDK reference: the full client surface