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

# SSE Format

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:`.

```text theme={null}
event: progress
data: {"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.

```json theme={null}
{
  "message": "Analyzing chart structure..."
}
```

| Field     | Type     | Description    |
| --------- | -------- | -------------- |
| `message` | `string` | Status message |

Agent-emitted progress events also include `agentId`, `executionId`, and `iteration` identifiers.

### complete

Sent once when processing succeeds. Contains the final result.

```json theme={null}
{
  "config": { ... },
  "response": {
    "message": "Changed to bar chart",
    "steps": ["Changed type", "Updated colors"]
  }
}
```

### error

Sent when processing fails.

```json theme={null}
{
  "error": "Invalid configuration",
  "code": "VALIDATION_ERROR",
  "retryable": false
}
```

| Field       | Type      | Description                                         |
| ----------- | --------- | --------------------------------------------------- |
| `error`     | `string`  | Error message                                       |
| `code`      | `string`  | Error code (see [Error Codes](/agents/rest/errors)) |
| `retryable` | `boolean` | Whether the request can be retried                  |

***

## Python Example

```python theme={null}
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['message']}")
        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:

```bash theme={null}
curl -N https://agents.graphy.dev/api/v0/generate ...
```

```python theme={null}
response = requests.post(..., stream=True)
```

**Set appropriate timeouts.** The initial connection should be quick, but processing may take up to 60 seconds:

```python theme={null}
response = requests.post(url, ..., timeout=(5, 120))
```