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

# Extract Agent

> Build a chart-ready dataset from unstructured text, images, PDFs, or .xlsx spreadsheets. Provide sourceText, attachments, or both.

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


Build a chart-ready dataset from unstructured text, images, PDFs, or Excel spreadsheets. Returns a `GraphConfig` with the extracted data via Server-Sent Events.

## Request body

Provide `sourceText`, `attachments`, or both — at least one is required. Each attachment is `{ kind: "image" | "document" | "spreadsheet", mimeType, dataBase64 }`, where `dataBase64` is RFC 4648 standard base64 (not a `data:` URL). Limits: 8 images (2 MB each), 2 PDFs (6 MB each), 2 spreadsheets (6 MB each); 12 attachments and 12 MB combined.

The legacy `images` array is deprecated — use `attachments` with `kind: "image"`. `images` and `attachments` cannot be combined.

## 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":"Extracting dataset from source content..."}

event: complete
data: {"config":{...},"response":{"message":"Extraction complete"},"extractMeta":{"confidence":"high","needsUserInput":false,"warnings":[]}}
```

**Final response data:**

```typescript theme={null}
interface ExtractResponse {
  config: GraphConfig;
  response: {
    message: string;
  };
  extractMeta: ExtractMeta | null;
  lastAccuracyEvaluation?: ExtractAccuracyEvaluation;
}
```

## HTTP Status Codes

| Status | Description                      |
| ------ | -------------------------------- |
| 200    | Success (stream begins)          |
| 400    | Invalid request body / no source |
| 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/extract
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/extract:
    post:
      tags:
        - Agents
      summary: Extract Agent
      description: >
        Build a chart-ready dataset from unstructured text, images, PDFs, or
        .xlsx spreadsheets. Provide sourceText, attachments, or both.


        The response is a Server-Sent Events (SSE) stream with progress,
        complete, and error events.
      operationId: extractFromProse
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExtractRequest'
            example:
              sourceText: >-
                In Q3, the Direct channel brought in $1.9M, Partner $0.4M, and
                Marketplace $1.1M.
              metadata:
                callId: req-extract-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/ExtractCompleteEvent'
                  - $ref: '#/components/schemas/ErrorEvent'
        '400':
          description: Bad Request - Invalid request body
        '401':
          description: Unauthorized - Invalid or missing API key
components:
  schemas:
    ExtractRequest:
      type: object
      description: >-
        Provide sourceText, attachments, or both — at least one is required.
        images and attachments are mutually exclusive.
      properties:
        sourceText:
          type: string
          maxLength: 500000
          description: Raw text to extract data from
        attachments:
          type: array
          maxItems: 12
          description: >-
            Images (max 8), PDFs (max 2), and spreadsheets (max 2). Preferred
            over images[].
          items:
            $ref: '#/components/schemas/ExtractAttachment'
        images:
          type: array
          maxItems: 8
          description: Deprecated — use attachments with kind "image".
          items:
            type: object
            properties:
              mimeType:
                type: string
              dataBase64:
                type: string
        metadata:
          $ref: '#/components/schemas/Metadata'
    ProgressEvent:
      title: Progress event
      description: SSE event name is "progress"
      type: object
      properties:
        message:
          type: string
    ExtractCompleteEvent:
      title: Extract complete event
      description: SSE event name is "complete"
      type: object
      properties:
        config:
          $ref: '#/components/schemas/GraphConfig'
        response:
          type: object
          properties:
            message:
              type: string
        extractMeta:
          $ref: '#/components/schemas/ExtractMeta'
        lastAccuracyEvaluation:
          type: object
          description: Optional final accuracy self-check
          properties:
            score:
              type: number
            issues:
              type: array
              items:
                type: string
            sufficient:
              type: boolean
            summary:
              type: string
    ErrorEvent:
      title: Error event
      description: SSE event name is "error"
      type: object
      properties:
        message:
          type: string
    ExtractAttachment:
      type: object
      description: >-
        An image, PDF, or spreadsheet to extract data from. Construct directly
        or via the SDK build*Attachment helpers.
      properties:
        kind:
          type: string
          enum:
            - image
            - document
            - spreadsheet
        mimeType:
          type: string
          description: >-
            e.g. image/png, application/pdf, or
            application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
        dataBase64:
          type: string
          description: >-
            RFC 4648 standard base64 of the file bytes (raw bytes, not a data
            URL)
        filename:
          type: string
          description: Optional; spreadsheets only
      required:
        - kind
        - mimeType
        - dataBase64
    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
    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
    ExtractMeta:
      title: Extraction trust metadata
      type: object
      description: Trust metadata for the extraction; null when unavailable
      properties:
        confidence:
          type: string
          enum:
            - high
            - medium
            - low
        needsUserInput:
          type: boolean
        warnings:
          type: array
          items:
            type: string
  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/

````