Skip to main content
All API endpoints return Server-Sent Events (SSE). This page explains the wire format and how to parse it.

​
Protocol Overview

SSE is a simple text-based protocol. Events are separated by blank lines, and each event has fields prefixed with event: and data:. 
event: progress
data: {"percentage":50,"message":"Processing..."}

event: complete
data: {"config":{...},"response":{...}}

​
Event Format

Each event consists of:
  1. event: line — The event type (progress, complete, or error)
  2. data: line — JSON payload
  3. Blank line — Event delimiter
The blank line after each event is required.

​
Event Types

​
progress

Sent periodically during processing. 
{
  "percentage": 50,
  "message": "Analyzing chart structure..."
}
FieldTypeDescription
percentagenumberProgress from 0-100
messagestringOptional status message

​
complete

Sent once when processing succeeds. Contains the final result. 
{
  "config": { ... },
  "response": {
    "message": "Changed to bar chart",
    "steps": ["Changed type", "Updated colors"]
  }
}

​
error

Sent when processing fails. 
{
  "error": "Invalid configuration",
  "code": "VALIDATION_ERROR",
  "retryable": false
}
FieldTypeDescription
errorstringError message
codestringError code (see Error Codes)
retryablebooleanWhether the request can be retried

​
Python Example

import requests
import json

response = requests.post(
    'https://agents.graphy.dev/api/v0/generate',
    headers={
        'Content-Type': 'application/json',
        'Authorization': 'Bearer YOUR_API_KEY'
    },
    json={'config': config, 'userPrompt': prompt},
    stream=True
)

event_type = None

for line in response.iter_lines():
    if not line:
        continue

    decoded = line.decode('utf-8')

    if decoded.startswith('event:'):
        event_type = decoded[6:].strip()
    elif decoded.startswith('data:'):
        data = json.loads(decoded[5:].strip())

        if event_type == 'progress':
            print(f"Progress: {data['percentage']}%")
        elif event_type == 'complete':
            print(f"Done: {data['config']}")
        elif event_type == 'error':
            print(f"Error: {data['error']}")

​
Connection Tips

Disable buffering to receive events in real-time: 
curl -N https://agents.graphy.dev/api/v0/generate ...

response = requests.post(..., stream=True)
Set appropriate timeouts. The initial connection should be quick, but processing may take up to 60 seconds: 
response = requests.post(url, ..., timeout=(5, 120))