Integrate Clarity

Call the Clarity card and chat from your backend, over the SDK or REST.

Clarity is available to your backend through the TypeScript SDK and a REST API. Both authenticate with a single x-api-key issued in your admin dashboard, and both return the same two response shapes:

• The card: two short sections (marketContext and positionsAnalysis), follow-up suggestions, citations, and a staleness indicator. Built for portfolio commentary above the fold.

• The chat: a streamed answer with citations and follow-ups, for a conversational "ask Clarity" surface delivering market, asset, and portfolio insights.

To embed Clarity directly in a browser without building UI, see Embed Clarity. To understand the holdings model these calls run against, see Portfolio context.

---

Set up the client

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

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

REST calls use the same base URL and key:

POST https://api.motifapp.ai/api/v1/clarity/card
x-api-key: <motif-api-key>
content-type: application/json

---

Clarity card

Reference a persisted portfolio by id, or pass holdings inline for stateless calls.

SDK

const card = await motif.clarity.card({ portfolioId: 'ppf_...' })

console.log(card.marketContext)     // markdown
console.log(card.positionsAnalysis) // markdown
console.log(card.followUps)         // string[]
console.log(card.staleness)         // { ageOfNewestDays: 1 } | null
console.log(card.narrative)         // story threads behind the card

Or inline:

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

REST

POST /v1/clarity/card

{ "portfolioId": "ppf_..." }

Response:

{
  "asOf": "2026-05-22T16:30:00Z",
  "marketContext": "Markdown summarising what's moving the market...",
  "positionsAnalysis": "Markdown summarising what's affecting these holdings...",
  "followUps": [
    "How is the NVDA earnings beat affecting my position?"
  ],
  "citations": [
    { "claimId": "...", "entityName": "NVIDIA", "label": "Q3 earnings call" }
  ],
  "staleness": { "ageOfNewestDays": 1 },
  "externalId": "acme-user-42",
  "partnerPortfolioId": "ppf_...",
  "narrative": { "stories": [], "stateChanges": [], "sources": [], "summary": {} }
}

staleness.ageOfNewestDays is how recent Clarity's freshest source is. Render a "data may be stale" badge above your tolerance. narrative carries the structured story-thread view behind the card — see Story threads behind the answer.

---

Clarity chat

Chat streams the answer so you can render it as it generates.

SDK

motif.clarity.chat(...) returns an AsyncGenerator. Iterate it with for await:

for await (const event of motif.clarity.chat({
  threadId: 'thread_abc',
  portfolioId: 'ppf_...',
  messages: [{ id: 'msg_1', role: 'user', content: 'Why is NVDA down today?' }],
})) {
  if (event.type === 'TEXT_MESSAGE_CONTENT') {
    process.stdout.write(event.delta)
  } else if (event.type === 'CUSTOM' && event.name === 'clarity-answer') {
    console.log('\nCitations:', event.value.citations)
    console.log('Follow-ups:', event.value.followUps)
  }
}

The final answer arrives as a CUSTOM event whose name is clarity-answer. Its value carries the structured answer (answerMarkdown, citations, followUps, staleness). Prefer it over the accumulated text chunks. Pass an AbortSignal as the second argument to cancel a stream.

The stream also emits a CUSTOM event named graph-metadata; its value.narrative carries the structured story-thread view behind the answer — stories, what developed, and what changed — for rendering alongside the prose. See Story threads behind the answer.

REST

POST /v1/clarity/chat

{
  "threadId": "thread_abc",
  "portfolioId": "ppf_...",
  "messages": [
    { "id": "msg_1", "role": "user", "content": "Why is NVDA down today?" }
  ]
}

The response is a text/event-stream of data:-prefixed JSON events. Branch on type, and for CUSTOM also branch on name:

type	Meaning
TEXT_MESSAGE_CONTENT	Streaming text chunk of the answer (delta: string)
CUSTOM	Final answer when name is "clarity-answer"; value has answerMarkdown, citations, followUps, staleness
CUSTOM	Story-thread view when name is "graph-metadata"; value.narrative carries the stories, developments, and state changes behind the answer
TOOL_CALL_START / TOOL_CALL_ARGS / TOOL_CALL_END / TOOL_CALL_RESULT	Internal tool traces, safe to ignore for display
RUN_ERROR	An error occurred

The stream terminates when the connection closes. A RUN_FINISHED event may precede the close.

threadId is optional but recommended. It lets Clarity correlate turns within a conversation. Supply portfolio inline instead of portfolioId for stateless callers.

---

Next steps

• Portfolio context: the holdings, trades, and profile model

• Embed Clarity: render Clarity in a browser with no API key exposure

• API reference: full endpoint and error reference