> ## Documentation Index
> Fetch the complete documentation index at: https://docs.graphy.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Narrative Agent

> Generate a chart's title, subtitle, and caption. Narrative is written into config.content as TipTap JSON. Requires userPrompt.

The response is a Server-Sent Events (SSE) stream with progress, complete, and error events.


Generate a chart's title, subtitle, and caption with natural language. Send a `GraphConfig` and a prompt, receive an updated `GraphConfig` via Server-Sent Events. Narrative is written into `config.content` as TipTap JSON.

## Request body

`userPrompt` is **required** — the narrative agent needs an instruction to write against. Which fields are produced (title only, title + caption, or all three) depends on the storytelling level derived from `metadata.effort`.

## Response

The response is a Server-Sent Events stream. See [SSE Format](/agents/rest/sse) for parsing details.

```text theme={null}
event: progress
data: {"message":"Generating narrative..."}

event: complete
data: {"config":{...},"response":{"message":"Wrote a title and caption"}}
```

**Final response data:**

```typescript theme={null}
interface NarrateResponse {
  config: GraphConfig;
  response: {
    message: string;
  };
}
```

## HTTP Status Codes

| Status | Description                |
| ------ | -------------------------- |
| 200    | Success (stream begins)    |
| 400    | Invalid request body       |
| 401    | Invalid or missing API key |
| 429    | Rate limit exceeded        |
| 500    | Internal server error      |

Errors may also arrive as SSE events within a 200 response. See [Error Codes](/agents/rest/errors).


## OpenAPI

````yaml POST /api/v0/narrate
openapi: 3.1.0
info:
  title: Graphy AI Agents API
  version: 0.1.0
  description: AI-powered chart generation and modification API
servers:
  - url: https://agents.graphy.dev
    description: Production
security:
  - bearerAuth: []
paths:
  /api/v0/narrate:
    post:
      tags:
        - Agents
      summary: Narrative Agent
      description: >
        Generate a chart's title, subtitle, and caption. Narrative is written
        into config.content as TipTap JSON. Requires userPrompt.


        The response is a Server-Sent Events (SSE) stream with progress,
        complete, and error events.
      operationId: generateNarrative
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateRequest'
            example:
              config:
                type: line
                data:
                  columns:
                    - key: month
                      label: Month
                    - key: users
                      label: Active Users
                  rows:
                    - month: Jan
                      users: 1200
                    - month: Feb
                      users: 1800
                    - month: Mar
                      users: 3100
              userPrompt: Write a punchy title and a one-line caption
              metadata:
                callId: req-narrate-1
                locale: EN_US
      responses:
        '200':
          description: SSE stream with progress and completion events
          content:
            text/event-stream:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ProgressEvent'
                  - $ref: '#/components/schemas/CompleteEvent'
                  - $ref: '#/components/schemas/ErrorEvent'
        '400':
          description: Bad Request - Invalid request body
        '401':
          description: Unauthorized - Invalid or missing API key
components:
  schemas:
    GenerateRequest:
      type: object
      properties:
        config:
          $ref: '#/components/schemas/GraphConfig'
        userPrompt:
          type: string
          maxLength: 10000
          description: Natural language instruction describing the desired changes
        metadata:
          $ref: '#/components/schemas/Metadata'
      required:
        - config
        - userPrompt
    ProgressEvent:
      title: Progress event
      description: SSE event name is "progress"
      type: object
      properties:
        message:
          type: string
    CompleteEvent:
      title: Complete event
      description: SSE event name is "complete"
      type: object
      properties:
        config:
          $ref: '#/components/schemas/GraphConfig'
        response:
          type: object
          properties:
            message:
              type: string
              description: Human-readable explanation of the changes made
            steps:
              type: array
              items:
                type: string
              description: Breakdown of individual modifications
    ErrorEvent:
      title: Error event
      description: SSE event name is "error"
      type: object
      properties:
        message:
          type: string
    GraphConfig:
      type: object
      description: >-
        The graph configuration object used to render charts. See [Graph Config
        Schema](/sdk/reference/graph-config) for the complete reference.
      properties:
        type:
          type: string
          enum:
            - line
            - areaStacked
            - bar
            - groupedBar
            - stackedBar
            - 100StackedBar
            - column
            - groupedColumn
            - stackedColumn
            - 100StackedColumn
            - combo
            - pie
            - donut
            - funnel
            - heatmap
            - scatter
            - bubble
            - waterfall
            - table
            - mekko
          description: The chart type
        data:
          type: object
          properties:
            columns:
              type: array
              items:
                type: object
                properties:
                  key:
                    type: string
                  label:
                    type: string
            rows:
              type: array
              items:
                type: object
                additionalProperties: true
      required:
        - type
        - data
    Metadata:
      type: object
      description: Optional tracking information for requests
      properties:
        callId:
          type: string
          description: >-
            Required when metadata is provided. Unique identifier for tracking
            and debugging.
        locale:
          type: string
          enum:
            - EN_GB
            - EN_US
            - AR
            - PT_PT
          description: Locale for responses
        effort:
          type: string
          enum:
            - low
            - medium
            - high
          description: >-
            Preferred invocation tier; forwarded on the invocation (including
            nested agents). When omitted, it can be inferred from
            `storytellingEffort` or defaults to `medium`.
        storytellingEffort:
          type: string
          enum:
            - none
            - low
            - medium
            - high
          description: >-
            Deprecated. Prefer `effort`. When set without `effort`, the server
            derives `effort` for propagation. For chart generation, an explicit
            value still controls narrative richness when both `effort` and
            `storytellingEffort` are present (`storytellingEffort` wins for the
            chart).
      required:
        - callId
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Your Graphy API key (starts with graphy_). Create one in the Graphy
        console at https://agents.graphy.dev/console/

````