---
title: "Generate guidance for an onboarding checklist step."
method: POST
path: "/onboarding/guide"
tags: ["Onboarding"]
---

# Generate guidance for an onboarding checklist step.

`POST /onboarding/guide`

## Request

- Base URL: `https://api.mnemom.ai/v1`
- URL: `https://api.mnemom.ai/v1/onboarding/guide`
- Auth: HTTP bearer

MNE-5508: Accepts a checklist item ID and user context; generates LLM-driven guidance narration and a bounded action suggestion. Gated behind `ONBOARDING_GUIDE_ENABLED` (dark by default) and `ONBOARDING_GUIDE_ALLOWLIST` (defaults to @mnemom.ai). Requires authentication.

## Request body

- object
  - `checklist_item_id` string, required: The ID of the onboarding checklist item (e.g., 'org.create', 'agent.alignment-card').
  - `user_role` string, required: The user's role (e.g., 'organization_owner', 'developer', 'security_lead', 'compliance_officer').
  - `facts` object: Optional contextual facts about the user's state (e.g., org_exists: true, first_agent_chosen: false).
  - `completed_steps` string[]: Optional array of checklist item IDs the user has already completed.
  - `user_goal` string: Optional user-provided goal or context (e.g., 'Build a support bot', 'Set up trusted governance').
  - `org_id` string: Optional organization ID for multi-tenant context.
  - `user_id` string: Optional user ID (can be overridden from auth context).

## Response `200`

Guidance generated successfully. Returns narration, suggested action, next step, and session correlation ID.

- object
  - `narration` string, required: The LLM-generated guidance narration for this step.
  - `action` object: The suggested bounded action the user should take.
    - `type` 'navigate' | 'click' | 'fill-form' | 'wait-for-element' | 'read-text': The type of action to suggest.
    - `params` object: Action-specific parameters (e.g., url for navigate, selector for click).
  - `next_step` object: Metadata about the current step and estimated time.
    - `item_id` string: The ID of the next onboarding step.
    - `estimated_time` string: Estimated time to complete the step (e.g., '~2 min', '~5-10 min').
  - `session_id` string, required: Correlation ID for this guidance session (for telemetry).
  - `fallback` boolean, required: True if the response is a fallback (LLM service unavailable or validation error).
  - `error` string: Optional error message (only if fallback: true).

## Other responses

- `400`: Bad request
- `401`: Authentication required
- `403`: Forbidden
- `404`: Resource not found
- `429`: Rate-limit exceeded. The global per-IP limiter (100 requests/minute, applied to every `/v1/*` route) rejected this request. Back off until the window resets — `Retry-After` carries the cooldown in seconds and `X-RateLimit-Reset` the absolute reset time.
- `500`: Server error — request was well-formed but the server failed to fulfill it. Typically a downstream dependency (DB / RPC / external API) returned an unexpected error.
- `503`: Service temporarily unavailable (LLM service down). Returns fallback guidance.

---

[API](https://skmtc.dev/mnemom/apis/mnemom-api.md) · [All operations](https://skmtc.dev/mnemom/apis/mnemom-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mnemom/apis/mnemom-api/revisions/274b7a6ea182?raw)