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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.