Clarity Next Steps API

openapi: 3.2.0
info:
  title: Fast Next Steps API
  version: 0.1.0
tags:
- name: next_steps
paths:
  /api/v1/next-steps:
    get:
      tags:
      - next_steps
      summary: List Next Steps
      description: 'The caller''s own next steps in the project they are viewing.


        Only the ``shown`` group, in state waiting or shown (or snoozed with the snooze over),

        most important kind first, then newest; at most 3. Empty for staff, and when the project''s

        ``nextStepsEnabled`` flag is off.


        Raises:

        HTTPException: 401/403/404 from the shared token and project check.'
      operationId: list_next_steps_api_v1_next_steps_get
      security:
      - HTTPBearer: []
      parameters:
      - name: surface
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/Surface'
          description: Where the cards will be shown
          default: overview
        description: Where the cards will be shown
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NextStepListResponse'
        '401':
          description: Not authenticated
        '404':
          description: Not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/next-steps/{step_id}/events:
    post:
      tags:
      - next_steps
      summary: Post Next Step Event
      description: 'Record what happened to one of the caller''s cards, and move the step accordingly.


        ``shown`` sets ``first_shown_at`` once; ``clicked`` sets ``clicked_at``; ``snoozed`` hides it

        for 14 days; ``dismissed`` stops it; ``done`` closes it. Every accepted call appends an event.


        Raises:

        HTTPException: 404 when the step is not the caller''s (or not in this project, held back,

        or unknown), for staff, and when the flag is off — never 403.

        HTTPException: 422 for an unknown action or surface.


        Example:

        ```json

        {"action": "clicked", "surface": "overview"}

        ```'
      operationId: post_next_step_event_api_v1_next_steps__step_id__events_post
      security:
      - HTTPBearer: []
      parameters:
      - name: step_id
        in: path
        required: true
        schema:
          type: integer
          maximum: 9223372036854775807
          minimum: 1
          title: Step Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NextStepEventRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NextStepEventResponse'
        '401':
          description: Not authenticated
        '404':
          description: Not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    NextStepEventResponse:
      properties:
        id:
          type: integer
          title: Id
        state:
          type: string
          title: State
          description: The step's state after the event
      type: object
      required:
      - id
      - state
      title: NextStepEventResponse
    NextStepResponse:
      properties:
        id:
          type: integer
          title: Id
        kind:
          type: string
          title: Kind
          description: 'Which rule found it: draft_routine, routine_only_you, routine_failed, repeated_question'
          examples:
          - routine_failed
        title:
          type: string
          title: Title
          examples:
          - Your routine “Weekly churn” failed
        detail:
          type: string
          title: Detail
          examples:
          - Its last run did not finish. Open it to see what went wrong and run it again.
        action_label:
          type: string
          title: Action Label
          description: The card's action button
          examples:
          - Open the routine
        href:
          anyOf:
          - type: string
          - type: 'null'
          title: Href
          description: 'Where the action goes: a path inside the project (prefix it with /project/{id}). Set for link steps; null for prompt steps.'
          examples:
          - /routines/12
        prompt:
          anyOf:
          - type: string
          - type: 'null'
          title: Prompt
          description: A prepared copilot prompt the action puts in the composer. Set for prompt steps; null otherwise.
        state:
          type: string
          title: State
          description: waiting, shown or snoozed (a snooze that is over)
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - id
      - kind
      - title
      - detail
      - action_label
      - state
      - created_at
      title: NextStepResponse
      description: 'One card: the caller''s own step, in their own things'' words.'
    NextStepEventRequest:
      properties:
        action:
          type: string
          enum:
          - shown
          - clicked
          - dismissed
          - snoozed
          - done
          title: Action
          description: 'shown: the card was displayed; clicked: its action was taken; snoozed: ''Not now'' (back in 14 days); dismissed: never again; done: the person says it is done'
        surface:
          $ref: '#/components/schemas/Surface'
          description: Where the card was shown
          default: overview
      type: object
      required:
      - action
      title: NextStepEventRequest
      description: Something that happened to a card in the caller's browser.
      example:
        action: shown
        surface: overview
    Surface:
      type: string
      enum:
      - overview
      title: Surface
      description: Where a step is shown. v1 has one; the sync API's own events carry ``SYNC_SURFACE``.
    NextStepListResponse:
      properties:
        steps:
          items:
            $ref: '#/components/schemas/NextStepResponse'
          type: array
          title: Steps
          description: The caller's own steps, most important first, at most 3. Empty for staff and when the project's nextStepsEnabled flag is off.
      type: object
      required:
      - steps
      title: NextStepListResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
    HTTPBasic:
      type: http
      scheme: basic