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

# Advanced Features

> Streaming semantics, task webhooks, idempotency, and operational guidance for Clix A2A.

## Streaming Behavior

Clix exposes two streaming methods:

* `SendStreamingMessage` to create a task and stream status events
* `SubscribeToTask` to fetch the current status snapshot for an existing task

### SSE Envelope

Each SSE `data:` line contains a JSON-RPC response envelope:

```text theme={null}
data: {"jsonrpc":"2.0","id":"stream-1","result":{"statusUpdate":{"taskId":"task-uuid","contextId":"ctx-uuid","status":{"state":"submitted"}}}}

data: {"jsonrpc":"2.0","id":"stream-1","result":{"statusUpdate":{"taskId":"task-uuid","contextId":"ctx-uuid","status":{"state":"completed","timestamp":"2026-03-11T12:00:00Z"}}}}
```

Current built-in Clix skills emit status updates only. The A2A v1 `StreamResponse` type can carry `artifactUpdate`, but Clix does not currently emit artifact updates during streaming.

### SubscribeToTask

`SubscribeToTask` is useful when you want the latest known task state over the SSE transport. The current implementation emits a single `statusUpdate` event and closes the stream.

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": "resub-1",
  "method": "SubscribeToTask",
  "params": {
    "id": "task-uuid"
  }
}
```

<Warning>
  Do not treat `SubscribeToTask` as a long-lived live stream reconnection mechanism. Today it returns a snapshot, not a resumed event stream.
</Warning>

## Task Webhooks

Task push notifications are outbound webhooks for task lifecycle events. They are not device push notifications.

### Register a Webhook

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": "push-1",
  "method": "CreateTaskPushNotificationConfig",
  "params": {
    "taskId": "task-uuid",
    "url": "https://example.com/a2a-webhook",
    "token": "verify-me",
    "authentication": {
      "scheme": "Bearer",
      "credentials": "webhook-secret"
    }
  }
}
```

### Callback Shape

Clix sends an HTTP `POST` request whose JSON body is a JSON-RPC request with `method: "tasks/pushNotification"`. The actual task event is nested under `params.result`.

```json theme={null}
{
  "jsonrpc": "2.0",
  "method": "tasks/pushNotification",
  "params": {
    "result": {
      "statusUpdate": {
        "taskId": "task-uuid",
        "contextId": "ctx-uuid",
        "status": {
          "state": "completed",
          "timestamp": "2026-03-11T12:00:00Z"
        }
      }
    }
  }
}
```

### Callback Headers

If the config includes authentication or a token, Clix sends:

* `Authorization: <scheme> <credentials>`
* `X-A2A-Token: <token>`

### Webhook URL Safety

Clix rejects unsafe webhook destinations. Loopback, link-local, site-local, and other local-only addresses are blocked. Use a publicly reachable HTTPS endpoint.

## Idempotency

`SendMessage` supports idempotent retries.

### Resolution Order

1. If present, Clix uses `X-Clix-Idempotency-Key`
2. Otherwise, Clix falls back to `message.messageId`

### Behavior

* Same key and same request body: cached response is replayed
* Same key while the original request is still running: HTTP `409 Conflict`
* Same key with a different request body: HTTP `409 Conflict`

Example:

```bash theme={null}
curl -X POST https://api.clix.so/a2a \
  -H "Content-Type: application/json" \
  -H "A2A-Version: 1.0" \
  -H "X-API-Key: clix_sk_your_secret_key" \
  -H "X-Clix-Idempotency-Key: request-123" \
  -d '{ ... }'
```

<Tip>
  Set `X-Clix-Idempotency-Key` explicitly in production. It keeps retry behavior independent from your message IDs.
</Tip>

## Operational Guidance

* Always send `A2A-Version: 1.0` for new integrations. Missing the header switches you to V0.
* Capture `X-Request-ID` from every response. It is the fastest way to trace a failed task with support logs.
* Use explicit `data.skill` payloads instead of text-only requests when deterministic routing matters.
* Document and test only the `JSONRPC` binding advertised in the Agent Card. Do not assume alternate A2A transports are available.