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
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"
| 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"
}
}
}
]
}
}
}'
| 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 |
| Header | Meaning |
|---|
X-Request-ID | Response header for tracing and support investigations |
{
"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"
}
}
}
]
}
}
}'
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"
}
}
}'
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
