Clix Documentation

This guide walks through the recommended v1 flow: discover the Agent Card, fetch the authenticated extended card, execute a task, inspect the request ID, stream updates, and register a task webhook.

Prerequisites

A Clix project created at console.clix.so
A Secret API Key prefixed with clix_sk_
An HTTP client that can send JSON and read SSE

/a2a accepts only Secret API Keys. Public keys and browser-exposed keys are rejected.

Base URL

https://api.clix.so

Step 1: Read the Public Agent Card

The public Agent Card requires no authentication.

curl https://api.clix.so/.well-known/agent-card.json \
  -H "A2A-Version: 1.0"

import httpx

response = httpx.get(
    "https://api.clix.so/.well-known/agent-card.json",
    headers={"A2A-Version": "1.0"},
)
agent_card = response.json()
print(agent_card["name"])
print(agent_card["supportedInterfaces"][0]["url"])
print(agent_card["capabilities"]["streaming"])

Look for these v1 fields in the response:

Field	Meaning
`supportedInterfaces`	Endpoint URL and binding metadata
`capabilities`	`streaming`, `pushNotifications`, `extendedAgentCard`
`securitySchemes`	Required header auth scheme
`skills`	The four Clix skills and examples

Step 2: Fetch the Authenticated Extended Card

GetExtendedAgentCard is an authenticated JSON-RPC method on /a2a.

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" \
  -d '{
    "jsonrpc": "2.0",
    "id": "card-1",
    "method": "GetExtendedAgentCard",
    "params": {}
  }'

The current Clix implementation returns the same v1 Agent Card schema as the public card, with a project-aware description.

Step 3: Send Your First Task

This example runs the create-user skill synchronously with SendMessage.

curl -i -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" \
  -d '{
    "jsonrpc": "2.0",
    "id": "req-1",
    "method": "SendMessage",
    "params": {
      "message": {
        "messageId": "msg-1",
        "role": "user",
        "parts": [
          {
            "text": "Create a user in Clix"
          },
          {
            "data": {
              "skill": "create-user",
              "projectUserId": "user_123",
              "properties": {
                "email": "[email protected]",
                "plan": "premium"
              }
            }
          }
        ]
      }
    }
  }'

import httpx

response = httpx.post(
    "https://api.clix.so/a2a",
    headers={
        "Content-Type": "application/json",
        "A2A-Version": "1.0",
        "X-API-Key": "clix_sk_your_secret_key",
    },
    json={
        "jsonrpc": "2.0",
        "id": "req-1",
        "method": "SendMessage",
        "params": {
            "message": {
                "messageId": "msg-1",
                "role": "user",
                "parts": [
                    {"text": "Create a user in Clix"},
                    {
                        "data": {
                            "skill": "create-user",
                            "projectUserId": "user_123",
                            "properties": {
                                "email": "[email protected]",
                                "plan": "premium",
                            },
                        }
                    },
                ],
            }
        },
    },
)

task = response.json()["result"]["task"]
print(response.headers["X-Request-ID"])
print(task["id"])
print(task["status"]["state"])
print(task["artifacts"][0]["parts"][0]["data"])

Important request fields:

Field	Meaning
`message.messageId`	Unique message ID and fallback idempotency key
`message.role`	Use `"user"` for client-authored messages
`message.parts[].data.skill`	Explicit Clix skill selector

Important response header:

Header	Meaning
`X-Request-ID`	Response header for tracing and support investigations

Example response excerpt:

{
  "jsonrpc": "2.0",
  "id": "req-1",
  "result": {
    "task": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "contextId": "ctx-001",
      "status": {
        "state": "completed",
        "timestamp": "2026-03-11T12:00:00Z"
      },
      "artifacts": [
        {
          "artifactId": "art-001",
          "name": "user-result",
          "parts": [
            {
              "data": {
                "userId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                "projectUserId": "user_123"
              }
            }
          ]
        }
      ]
    }
  }
}

Step 4: Stream Status Updates with SSE

Use SendStreamingMessage when you want task progress over Server-Sent Events.

curl -N -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" \
  -d '{
    "jsonrpc": "2.0",
    "id": "stream-1",
    "method": "SendStreamingMessage",
    "params": {
      "message": {
        "messageId": "msg-stream-1",
        "role": "user",
        "parts": [
          {
            "data": {
              "skill": "track-event",
              "eventName": "purchase",
              "deviceId": "device_abc",
              "properties": {
                "amount": 29.99,
                "currency": "USD"
              }
            }
          }
        ]
      }
    }
  }'

import json
import httpx

with httpx.stream(
    "POST",
    "https://api.clix.so/a2a",
    headers={
        "Content-Type": "application/json",
        "A2A-Version": "1.0",
        "X-API-Key": "clix_sk_your_secret_key",
    },
    json={
        "jsonrpc": "2.0",
        "id": "stream-1",
        "method": "SendStreamingMessage",
        "params": {
            "message": {
                "messageId": "msg-stream-1",
                "role": "user",
                "parts": [
                    {
                        "data": {
                            "skill": "track-event",
                            "eventName": "purchase",
                            "deviceId": "device_abc",
                            "properties": {"amount": 29.99, "currency": "USD"},
                        }
                    }
                ],
            }
        },
    },
) as response:
    for line in response.iter_lines():
        if line.startswith("data: "):
            event = json.loads(line[6:])
            print(event["result"]["statusUpdate"]["status"]["state"])

Current built-in Clix skills emit JSON-RPC SSE envelopes like:

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

Step 5: Read the Task Later

You can re-read the task directly or list tasks for a context.

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" \
  -d '{
    "jsonrpc": "2.0",
    "id": "req-2",
    "method": "GetTask",
    "params": {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  }'

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" \
  -d '{
    "jsonrpc": "2.0",
    "id": "req-3",
    "method": "ListTasks",
    "params": {
      "pageSize": 10,
      "contextId": "ctx-001"
    }
  }'

ListTasks returns tasks, nextPageToken, pageSize, and totalSize. On follow-up cursor requests, the current Clix implementation returns totalSize: 0, so capture the first page if you need the total count.

Step 6: Register a Task Webhook

Task push notifications are webhooks for task lifecycle events.

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" \
  -d '{
    "jsonrpc": "2.0",
    "id": "req-4",
    "method": "CreateTaskPushNotificationConfig",
    "params": {
      "taskId": "550e8400-e29b-41d4-a716-446655440000",
      "url": "https://example.com/a2a-webhook",
      "token": "verify-me",
      "authentication": {
        "scheme": "Bearer",
        "credentials": "webhook-secret"
      }
    }
  }'

Clix will call your webhook with a JSON-RPC request whose method is tasks/pushNotification and whose event payload is inside params.result.

Authentication Errors

If authentication fails, /a2a returns HTTP errors instead of a JSON-RPC method result.

Status	Cause	Fix
`401 Unauthorized`	Missing or invalid secret key	Send a valid `X-API-Key` header
`403 Forbidden`	Public or browser-safe API key	Switch to a Secret API Key with the `clix_sk_` prefix

Next Steps

API Reference

Review every method, data type, and error code

Advanced Features

See webhook payloads, SSE behavior, and idempotency details

Skills

Pick the exact payload shape for each built-in skill

​Prerequisites

​Base URL

​Step 1: Read the Public Agent Card

​Step 2: Fetch the Authenticated Extended Card

​Step 3: Send Your First Task

​Step 4: Stream Status Updates with SSE

​Step 5: Read the Task Later

​Step 6: Register a Task Webhook

​Authentication Errors

​Next Steps

API Reference

Advanced Features

Skills

Prerequisites

Base URL

Step 1: Read the Public Agent Card

Step 2: Fetch the Authenticated Extended Card

Step 3: Send Your First Task

Step 4: Stream Status Updates with SSE

Step 5: Read the Task Later

Step 6: Register a Task Webhook

Authentication Errors

Next Steps