Skip to main content

​
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

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