Skip to main content
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"
Look for these v1 fields in the response:
FieldMeaning
supportedInterfacesEndpoint URL and binding metadata
capabilitiesstreaming, pushNotifications, extendedAgentCard
securitySchemesRequired header auth scheme
skillsThe 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": "user@example.com",
                "plan": "premium"
              }
            }
          }
        ]
      }
    }
  }'
Important request fields:
FieldMeaning
message.messageIdUnique message ID and fallback idempotency key
message.roleUse "user" for client-authored messages
message.parts[].data.skillExplicit Clix skill selector
Important response header:
HeaderMeaning
X-Request-IDResponse 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"
              }
            }
          }
        ]
      }
    }
  }'
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.
StatusCauseFix
401 UnauthorizedMissing or invalid secret keySend a valid X-API-Key header
403 ForbiddenPublic or browser-safe API keySwitch 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