> ## 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.

# Annotation Agent

> Add highlights, tooltips, stickers, and other annotations to a chart with natural language.

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


Add highlights, tooltips, stickers, and other annotations to a chart with natural language. Send a `GraphConfig` and a prompt, receive an updated `GraphConfig` via Server-Sent Events.

## 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":"Adding annotations..."}

event: complete
data: {"config":{...},"response":{"message":"Highlighted the March peak","steps":["Added highlight","Added tooltip"]}}
```

**Final response data:**

```typescript theme={null}
interface AnnotateResponse {
  config: GraphConfig;
  response: {
    message: string;
    steps?: 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/annotate
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/annotate:
    post:
      tags:
        - Agents
      summary: Annotation Agent
      description: >
        Add highlights, tooltips, stickers, and other annotations to a chart
        with natural language.


        The response is a Server-Sent Events (SSE) stream with progress,
        complete, and error events.
      operationId: generateAnnotations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateRequest'
            example:
              config:
                type: column
                data:
                  columns:
                    - key: month
                      label: Month
                    - key: revenue
                      label: Revenue
                  rows:
                    - month: Jan
                      revenue: 100
                    - month: Feb
                      revenue: 140
                    - month: Mar
                      revenue: 220
              userPrompt: Highlight the March peak and add a tooltip explaining it
              metadata:
                callId: req-annotate-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/

````