> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clix.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> Connect your agent to Clix A2A, inspect the Agent Card, send a task, stream updates, and register a webhook.

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](https://console.clix.so)
* A Secret API Key prefixed with `clix_sk_`
* An HTTP client that can send JSON and read SSE

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

## Base URL

```text theme={null}
https://api.clix.so
```

## Step 1: Read the Public Agent Card

The public Agent Card requires no authentication.

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.clix.so/.well-known/agent-card.json \
    -H "A2A-Version: 1.0"
  ```

  ```python Python theme={null}
  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"])
  ```
</CodeGroup>

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

```bash theme={null}
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": {}
  }'
```

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

## Step 3: Send Your First Task

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

<CodeGroup>
  ```bash curl theme={null}
  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"
                }
              }
            }
          ]
        }
      }
    }'
  ```

  ```python Python theme={null}
  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": "user@example.com",
                                  "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"])
  ```
</CodeGroup>

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:

```json theme={null}
{
  "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.

<CodeGroup>
  ```bash curl theme={null}
  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"
                }
              }
            }
          ]
        }
      }
    }'
  ```

  ```python Python theme={null}
  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"])
  ```
</CodeGroup>

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

```text theme={null}
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.

```bash theme={null}
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"
    }
  }'
```

```bash theme={null}
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.

```bash theme={null}
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

<CardGroup cols={3}>
  <Card title="API Reference" icon="code" href="/a2a/api-reference">
    Review every method, data type, and error code
  </Card>

  <Card title="Advanced Features" icon="bolt" href="/a2a/advanced-features">
    See webhook payloads, SSE behavior, and idempotency details
  </Card>

  <Card title="Skills" icon="robot" href="/a2a/skills">
    Pick the exact payload shape for each built-in skill
  </Card>
</CardGroup>