Clix Documentation

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:

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.

{
  "jsonrpc": "2.0",
  "id": "resub-1",
  "method": "SubscribeToTask",
  "params": {
    "id": "task-uuid"
  }
}

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

Task Webhooks

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

Register a Webhook

{
  "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.

{
  "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

If present, Clix uses X-Clix-Idempotency-Key
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:

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 '{ ... }'

Set X-Clix-Idempotency-Key explicitly in production. It keeps retry behavior independent from your message IDs.

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.

User Guide

Migration

Quick Start (Installation)

Essentials

Campaigns

Model Context Protocol

Agent Skills

Agent-to-Agent (A2A)

Integrations

API Reference

Troubleshooting

Security & Ops

Advanced Features

Streaming Behavior

SSE Envelope

SubscribeToTask

Task Webhooks

Register a Webhook

Callback Shape

Callback Headers

Webhook URL Safety

Idempotency

Resolution Order

Behavior

Operational Guidance

​Streaming Behavior

​SSE Envelope

​SubscribeToTask

​Task Webhooks

​Register a Webhook

​Callback Shape

​Callback Headers

​Webhook URL Safety

​Idempotency

​Resolution Order

​Behavior

​Operational Guidance

Streaming Behavior

SSE Envelope

SubscribeToTask

Task Webhooks

Register a Webhook

Callback Shape

Callback Headers

Webhook URL Safety

Idempotency

Resolution Order

Behavior

Operational Guidance