API reference

REST endpoints for partner portfolios, Clarity, and embed tokens.

Base URL: https://api.motifapp.ai/api

All endpoints accept and return JSON and require the x-api-key header, except the Clarity card and chat endpoints, which also accept a short-lived x-embed-token from the iframe flow. The same endpoints exist on staging at https://staging.backend.motifapp.ai/api with a staging key.

x-api-key: <motif-api-key>

Requests fail with 401 if the key is missing or invalid, and 403 if the organization is inactive or the key isn't org-linked. See Authentication.

The TypeScript SDK wraps these endpoints, including the user, profiling, questionnaire, and strategy operations not detailed below. Reach for raw REST when you're not on Node, or when you need an operation the wrapper doesn't expose yet (for example POST /v1/sdk/reports/generate).

---

Partner portfolios

A partner portfolio is the persisted form of a portfolio context.

Create

POST /v1/sdk/partner-portfolios

{
  "externalId": "acme-user-42",
  "baseCurrency": "USD",
  "currentHoldings": [
    { "ticker": "AAPL", "quantity": 100, "costBasis": 170.50, "currency": "USD" },
    { "ticker": "NVDA", "quantity": 30,  "costBasis": 410.20, "currency": "USD" }
  ],
  "profile": { "riskTolerance": "moderate", "horizonYears": 7 }
}

externalId is required and must be unique within your organization. Response: the portfolio, echoing the input with id, createdAt, and updatedAt.

Read, update, delete

GET    /v1/sdk/partner-portfolios/{id}
PATCH  /v1/sdk/partner-portfolios/{id}
DELETE /v1/sdk/partner-portfolios/{id}

PATCH accepts the same shape as create. Supply only the fields you want to change.

Record trades

POST /v1/sdk/partner-portfolios/{id}/trades

{
  "trades": [
    { "ticker": "NVDA", "side": "BUY", "quantity": 5, "price": 502.10, "executedAt": "2026-05-22T16:00:00Z" }
  ],
  "currentHoldings": [
    { "ticker": "AAPL", "quantity": 100, "costBasis": 170.50 },
    { "ticker": "NVDA", "quantity": 35,  "costBasis": 422.50 }
  ]
}

Appends the trades to the log (capped at the most recent 5000 by executedAt) and replaces currentHoldings atomically. To change historicHoldings, use PATCH instead.

---

Clarity card

POST /v1/clarity/card

Reference a persisted portfolio with { "portfolioId": "ppf_..." }, or pass { "portfolio": { ... } } inline.

{
  "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": {} }
}

narrative carries the structured story-thread view behind the card — the same stories, developments, and state changes described in Story threads behind the answer.

---

Clarity chat

POST /v1/clarity/chat

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

Responds with text/event-stream of data:-prefixed JSON events. Branch on type, and for CUSTOM also branch on name:

type	Meaning
TEXT_MESSAGE_CONTENT	Streaming chunk of the answer (delta: string)
CUSTOM	When name is clarity-answer, value holds the final answer with answerMarkdown, citations, followUps, staleness
CUSTOM	When name is graph-metadata, value.narrative holds the stories, developments, and state changes behind the answer
TOOL_CALL_START / TOOL_CALL_ARGS / TOOL_CALL_END / TOOL_CALL_RESULT	Tool-call traces, safe to ignore
RUN_ERROR	Error

The stream terminates when the connection closes. A terminal RUN_FINISHED event may precede the close. There is no [DONE] sentinel. threadId is optional but recommended.

---

Embed token

POST /v1/sdk/clarity/embeds

{
  "portfolioId": "ppf_...",
  "allowedOrigins": ["https://app.acme.com"],
  "ttlSeconds": 600,
  "scope": ["card", "chat"]
}

Mints a short-lived token bound to one portfolio and one or more allowed origins. ttlSeconds defaults to 600 (max 3600, min 30). scope defaults to ["card", "chat"]. See Embed Clarity for the full flow.

---

Errors

Status	Meaning
400	Validation error in the request body. The response includes issues.
401	Missing or invalid x-api-key / x-embed-token.
403	Organization inactive, scope mismatch, origin not allowed, or portfolio binding violation.
404	The referenced resource doesn't exist in your organization.
500	Server error. Safe to retry after a short backoff.

See Error handling for handling patterns.