---
title: "Guide Nudge Endpoint"
method: POST
path: "/guide/nudge"
tags: ["guide"]
---

# Guide Nudge Endpoint

`POST /guide/nudge`

## Request

- Base URL: `https://api.framesail.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.framesail.com/guide/nudge`
- Auth: HTTP bearer

Send the first-run message due for the place the user is in and return
it; null when nothing is due. The app calls this on every page a new user
opens in a channel or a project. Ownership of either is checked; outside
both there are no first-run messages.

## Request body

- GuideNudgeRequest
  - `project_id` string, nullable
  - `channel_id` string, nullable
  - `route` string, required

## Response `200`

Successful Response

- GuideThreadMessage: One stored message of the thread, as the panel renders it.
  - `id` string, required
  - `scope` 'global' | 'channel' | 'project', required
  - `scope_id` string, nullable, required
  - `role` 'user' | 'assistant' | 'nudge', required
  - `content` string, required
  - `nudge_id` string, nullable, required
  - `category` string, nullable, required
  - `chips` GuideChip[], required
    - `label` string, required
    - `kind` 'navigate' | 'question' | 'preset', required
    - `value` string, required
    - `highlight` string, nullable
  - `preset` GuidePreset, required: A preset message as the panel renders it (generation/guide/presets.py).
    - `id` string, required
    - `title` string, required
    - `blocks` union[], required
      - union
        - GuideTextBlock
          - `type` 'text'
          - `text` string, required
        - GuideTipBlock
          - `type` 'tip'
          - `text` string, required
        - GuideTemplatesBlock: The channel style's two template images, as they are now.
          - `type` 'templates'
        - GuideListBlock: Numbered rows: steps to read, or options to pick from.
          - `type` 'list'
          - `items` GuideListItem[], required
            - `title` string, required
            - `detail` string, required
            - `link` string, nullable
            - `highlight` string, nullable
    - `page` string, nullable
    - `highlight` string, nullable
    - `route` string, nullable
  - `rating` 'up' | 'down', nullable
  - `created_at` string, required

## Other responses

- `422`: Validation Error

---

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