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

# Version Compatibility

> Differences between Clix A2A V1 and legacy V0, with concrete migration guidance.

Clix supports both A2A V1 and legacy V0. New integrations should use V1 by sending `A2A-Version: 1.0`.

<Warning>
  If you omit the `A2A-Version` header, Clix resolves the request as V0 (`0.3`).
</Warning>

## Method Mapping

| V1                                 | V0                                    |
| ---------------------------------- | ------------------------------------- |
| `SendMessage`                      | `message/send`                        |
| `SendStreamingMessage`             | `message/stream`                      |
| `GetTask`                          | `tasks/get`                           |
| `ListTasks`                        | `tasks/list`                          |
| `CancelTask`                       | `tasks/cancel`                        |
| `SubscribeToTask`                  | `tasks/resubscribe`                   |
| `CreateTaskPushNotificationConfig` | `tasks/pushNotificationConfig/set`    |
| `GetTaskPushNotificationConfig`    | `tasks/pushNotificationConfig/get`    |
| `ListTaskPushNotificationConfigs`  | `tasks/pushNotificationConfig/list`   |
| `DeleteTaskPushNotificationConfig` | `tasks/pushNotificationConfig/delete` |
| `GetExtendedAgentCard`             | `agent/getAuthenticatedExtendedCard`  |

## Key Wire-Format Differences

### Agent Card

| Area                     | V1                                        | V0                                                  |
| ------------------------ | ----------------------------------------- | --------------------------------------------------- |
| Endpoint metadata        | `supportedInterfaces`                     | `url`, `preferredTransport`, `additionalInterfaces` |
| Auth metadata            | `securitySchemes`, `securityRequirements` | `securitySchemes`, `security`                       |
| Extended card capability | `capabilities.extendedAgentCard`          | `supportsAuthenticatedExtendedCard`                 |
| Protocol version field   | Per interface `protocolVersion`           | Top-level `protocolVersion`                         |

### Message and Task Objects

| Area               | V1                                                | V0                                                                      |
| ------------------ | ------------------------------------------------- | ----------------------------------------------------------------------- |
| Part discriminator | No `kind` field                                   | `kind` is required on parts                                             |
| Message shape      | `messageId`, `role`, `parts`                      | Same camelCase fields plus `kind: "message"`                            |
| Task shape         | `id`, `contextId`, `status`, `artifacts`          | Same camelCase fields plus `kind: "task"`                               |
| Stream events      | JSON-RPC envelope with v1 `StreamResponse` result | JSON-RPC envelope with V0 event objects such as `kind: "status-update"` |

### Pagination

| Area           | V1                                              | V0                |
| -------------- | ----------------------------------------------- | ----------------- |
| Request params | `pageSize`, `pageToken`                         | `limit`, `offset` |
| Response shape | `{ tasks, nextPageToken, pageSize, totalSize }` | Array of tasks    |
| Total count    | First page only in current Clix implementation  | Not returned      |

### Push Notification Config Params

| Operation | V1                                                                                            | V0                                                        |
| --------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| Create    | `params` is the config object itself with `taskId`, `url`, `id?`, `token?`, `authentication?` | `params` is `{ taskId, pushNotificationConfig: { ... } }` |
| Get       | `{ taskId, id }`                                                                              | `{ id, pushNotificationConfigId }`                        |
| List      | `{ taskId }`                                                                                  | `{ id }`                                                  |
| Delete    | `{ taskId, id }`                                                                              | `{ id, pushNotificationConfigId }`                        |

### SendMessage Result Shape

| Version | Result                              |
| ------- | ----------------------------------- |
| V1      | `{ "result": { "task": { ... } } }` |
| V0      | `{ "result": { ...task... } }`      |

## Role and State Values

The protocol values are the same across Clix V0 and V1:

* Roles serialize as `user`, `agent`, and `unspecified`
* Task states serialize as `submitted`, `working`, `completed`, `failed`, and other lowercase protocol values

The main compatibility differences are method names, container shapes, and pagination models, not the role or state strings.

## Example Migration

### V0 request

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": "req-1",
  "method": "message/send",
  "params": {
    "message": {
      "kind": "message",
      "messageId": "msg-1",
      "role": "user",
      "parts": [
        {
          "kind": "data",
          "data": {
            "skill": "create-user",
            "projectUserId": "user_123"
          }
        }
      ]
    }
  }
}
```

### V1 request

Send this request with `A2A-Version: 1.0`. If you omit the header, Clix interprets the request as V0.

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": "req-1",
  "method": "SendMessage",
  "params": {
    "message": {
      "messageId": "msg-1",
      "role": "user",
      "parts": [
        {
          "data": {
            "skill": "create-user",
            "projectUserId": "user_123"
          }
        }
      ]
    }
  }
}
```

## Migration Checklist

1. Start sending `A2A-Version: 1.0` on every request, including the public Agent Card request.
2. Rename JSON-RPC methods from slash-style V0 names to the PascalCase V1 names.
3. Remove `kind` fields from message parts and stop expecting `kind` on messages, tasks, and stream events.
4. Update `SendMessage` callers to read `result.task` instead of reading the task directly from `result`.
5. Replace `limit` and `offset` with `pageSize` and `pageToken`, and update your parser for the paged `ListTasks` response object.
6. Update task webhook config params to the V1 `taskId` and `id` field names.

## When to Keep V0

Keep V0 only if you already have a deployed client that depends on the older method names or older object wrappers. For any new integration, V1 is the stable documentation target.