Core API reference
Use this page as the API hub for Narrative SDKv1.5.
OpenAPI Explorer is the primary endpoint contract source. The API guide pages focus on integration workflow and implementation recommendations.
Start here
OpenAPI Explorer
Browse endpoint-level contracts in the sidebar API Explorer (contract file:
openapi/nsdk-v1.5.yaml).Authentication guide
Session lifecycle, refresh strategy, and auth integration baseline.
Coach API guide
Sessionized chat flow, streaming behavior, and follow-up integration.
Money API guide
Metrics and action-state integration patterns.
Growth API guide
Opportunity-to-project lifecycle integration.
Integrations API guide
Provider connection and disconnection lifecycle.
Endpoint catalog
Authentication
| Endpoint | Description | Auth | Required input | 200 response |
|---|---|---|---|---|
POST /api/auth/login | Authenticate user and issue tokens. | No | Body: email, password | accessToken, refreshToken, userId, tenantId |
POST /api/auth/refresh | Rotate access and refresh tokens. | No | Body: refreshToken | accessToken, refreshToken |
POST /api/auth/logout | Invalidate current user session. | Yes | None | ok |
GET /api/auth/me | Return authenticated user scope. | Yes | None | userId, tenantId, email |
Coach
| Endpoint | Description | Auth | Required input | 200 response |
|---|---|---|---|---|
GET /api/coach/bootstrap | Load initial coach state. | Yes | None | session object |
POST /api/chat/session/create | Create a new chat session. | Yes | Body: chatType, userId | sessionId, chatType, createdAt |
POST /api/chat/send | Send a message and receive SSE stream. | Yes | Body: sessionId, userId, payloadType, payload | SSE stream accepted |
Money
| Endpoint | Description | Auth | Required input | 200 response |
|---|---|---|---|---|
GET /api/money/metrics | Return summary metric cards. | Yes | Query: asOfDate (YYYY-MM-DD) | asOfDate, currency, cards[] |
GET /api/money/actions | Return prioritized action list. | Yes | Query: asOfDate (YYYY-MM-DD) | items[] |
POST /api/money/action/status/set | Update money action status. | Yes | Body: userId, insightId, status; optional reason | ok, insightId, status |
Growth
| Endpoint | Description | Auth | Required input | 200 response |
|---|---|---|---|---|
GET /api/growth/opps | Return growth opportunities. | Yes | Query: asOfDate (YYYY-MM-DD) | asOfDate, items[] |
POST /api/projects/from_opp | Create project from opportunity. | Yes | Body: insightId | projectId, insightId, isActive |
Integrations
| Endpoint | Description | Auth | Required input | 200 response |
|---|---|---|---|---|
GET /api/integrations | List user integrations. | Yes | Optional query: integration_type | integrations[] |
POST /api/integrations/saltedge/connect | Start SaltEdge connection flow. | Yes | None | connect_url |
Error model
Common error payload for400, 401, 404, 429, and 500 responses: