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

# API Reference

> Reference for Clix A2A endpoints, JSON-RPC methods, task types, and error semantics.

All `/a2a` method calls use JSON-RPC 2.0 over HTTPS. Public agent discovery uses `GET /.well-known/agent-card.json`.

## Endpoints

| Path                           | Method | Auth        | Description                    |
| ------------------------------ | ------ | ----------- | ------------------------------ |
| `/.well-known/agent-card.json` | `GET`  | None        | Public Agent Card              |
| `/a2a`                         | `POST` | `X-API-Key` | Authenticated JSON-RPC methods |

**Base URL:** `https://api.clix.so`

## Headers

| Header                   | Direction | Required    | Description                                                                    |
| ------------------------ | --------- | ----------- | ------------------------------------------------------------------------------ |
| `A2A-Version`            | Request   | Recommended | Use `1.0`. Omitting it defaults to V0 (`0.3`).                                 |
| `Content-Type`           | Request   | For `/a2a`  | Must be `application/json`.                                                    |
| `X-API-Key`              | Request   | For `/a2a`  | Secret API Key with the `clix_sk_` prefix.                                     |
| `X-Clix-Idempotency-Key` | Request   | Optional    | Explicit idempotency key for `SendMessage`. Falls back to `message.messageId`. |
| `X-Request-ID`           | Response  | Always      | Correlation header for tracing and support.                                    |

## JSON-RPC Methods

### SendMessage

Creates and executes a task synchronously. The response returns when the task reaches a terminal or interrupted state.

**Request**

```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"
          }
        }
      ]
    }
  }
}
```

**Response**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": "req-1",
  "result": {
    "task": {
      "id": "task-uuid",
      "contextId": "ctx-uuid",
      "status": {
        "state": "completed",
        "timestamp": "2026-03-11T12:00:00Z"
      },
      "artifacts": [
        {
          "artifactId": "art-uuid",
          "name": "user-result",
          "parts": [
            {
              "data": {
                "userId": "uuid",
                "projectUserId": "user_123"
              }
            }
          ]
        }
      ],
      "history": []
    }
  }
}
```

### SendStreamingMessage

Creates a task and streams task events over Server-Sent Events.

The SSE stream does not emit raw `StreamResponse` objects. Each `data:` line contains a JSON-RPC response envelope:

```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"}}}}
```

<Note>
  Current built-in Clix skills emit `statusUpdate` events. They do not currently emit `artifactUpdate` events during streaming.
</Note>

### GetTask

Reads a task by ID.

**Request**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": "req-2",
  "method": "GetTask",
  "params": {
    "id": "task-uuid"
  }
}
```

**Response**

`GetTask` returns the task directly as `result`, not inside `result.task`.

### ListTasks

Lists tasks with cursor pagination.

Supported params:

| Param       | Type    | Description                                                    |
| ----------- | ------- | -------------------------------------------------------------- |
| `contextId` | string  | Filter tasks by context                                        |
| `status`    | string  | Filter by protocol state value such as `completed` or `failed` |
| `pageSize`  | integer | Page size. The current default is `50`.                        |
| `pageToken` | string  | Cursor returned by a previous response                         |

**Request**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": "req-3",
  "method": "ListTasks",
  "params": {
    "pageSize": 20,
    "contextId": "ctx-uuid"
  }
}
```

**Response**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": "req-3",
  "result": {
    "tasks": [
      {
        "id": "task-uuid",
        "contextId": "ctx-uuid",
        "status": {
          "state": "completed"
        },
        "artifacts": [],
        "history": []
      }
    ],
    "nextPageToken": "base64-cursor",
    "pageSize": 20,
    "totalSize": 42
  }
}
```

<Note>
  On the first page, `totalSize` contains the total matching count. On later cursor requests, the current Clix implementation returns `0`.
</Note>

### CancelTask

Cancels a non-terminal task.

**Request**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": "req-4",
  "method": "CancelTask",
  "params": {
    "id": "task-uuid"
  }
}
```

**Response**

Returns the task directly as `result`, with `status.state` set to `canceled`.

### SubscribeToTask

Streams the current state of an existing task over SSE.

**Request**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": "req-5",
  "method": "SubscribeToTask",
  "params": {
    "id": "task-uuid"
  }
}
```

**Response**

```text theme={null}
data: {"jsonrpc":"2.0","id":"req-5","result":{"statusUpdate":{"taskId":"task-uuid","contextId":"ctx-uuid","status":{"state":"completed"}}}}
```

<Note>
  The current Clix implementation emits a single status snapshot for the current task state and closes the stream. It does not resume a live execution stream.
</Note>

### CreateTaskPushNotificationConfig

Registers a webhook for task events.

**Request**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": "req-6",
  "method": "CreateTaskPushNotificationConfig",
  "params": {
    "taskId": "task-uuid",
    "url": "https://example.com/a2a-webhook",
    "token": "verify-me",
    "authentication": {
      "scheme": "Bearer",
      "credentials": "webhook-secret"
    }
  }
}
```

**Response**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": "req-6",
  "result": {
    "id": "config-uuid",
    "taskId": "task-uuid",
    "url": "https://example.com/a2a-webhook",
    "token": "verify-me",
    "authentication": {
      "scheme": "Bearer",
      "credentials": "webhook-secret"
    }
  }
}
```

### GetTaskPushNotificationConfig

Reads a single task webhook config.

**Request**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": "req-7",
  "method": "GetTaskPushNotificationConfig",
  "params": {
    "taskId": "task-uuid",
    "id": "config-uuid"
  }
}
```

Both `taskId` and `id` are required.

### ListTaskPushNotificationConfigs

Lists webhook configs for a task.

**Request**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": "req-8",
  "method": "ListTaskPushNotificationConfigs",
  "params": {
    "taskId": "task-uuid"
  }
}
```

**Response**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": "req-8",
  "result": {
    "configs": [
      {
        "id": "config-uuid",
        "taskId": "task-uuid",
        "url": "https://example.com/a2a-webhook"
      }
    ],
    "nextPageToken": ""
  }
}
```

The current Clix implementation returns the full config list for the task and an empty `nextPageToken`.

### DeleteTaskPushNotificationConfig

Deletes a task webhook config.

**Request**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": "req-9",
  "method": "DeleteTaskPushNotificationConfig",
  "params": {
    "taskId": "task-uuid",
    "id": "config-uuid"
  }
}
```

Both `taskId` and `id` are required.

**Response**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": "req-9",
  "result": null
}
```

### GetExtendedAgentCard

Returns the authenticated Agent Card.

**Request**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": "req-10",
  "method": "GetExtendedAgentCard",
  "params": {}
}
```

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

## Data Types

### Task

| Field       | Type   | Description                                |
| ----------- | ------ | ------------------------------------------ |
| `id`        | string | Task identifier                            |
| `contextId` | string | Conversation or session grouping key       |
| `status`    | object | Current task state, message, and timestamp |
| `artifacts` | array  | Output artifacts                           |
| `history`   | array  | Message history                            |
| `metadata`  | object | Optional metadata                          |

### Message

| Field       | Type   | Description                       |
| ----------- | ------ | --------------------------------- |
| `messageId` | string | Unique message identifier         |
| `role`      | string | `user`, `agent`, or `unspecified` |
| `parts`     | array  | Text or data parts                |
| `contextId` | string | Optional context ID               |
| `taskId`    | string | Optional task linkage             |

### Part

| Field      | Type   | Description             |
| ---------- | ------ | ----------------------- |
| `text`     | string | Plain text content      |
| `data`     | object | Structured JSON content |
| `metadata` | object | Optional metadata       |

### Artifact

| Field        | Type   | Description                         |
| ------------ | ------ | ----------------------------------- |
| `artifactId` | string | Unique artifact identifier          |
| `name`       | string | Artifact type such as `user-result` |
| `parts`      | array  | Output parts                        |

### TaskPushNotificationConfig

| Field            | Type   | Description                                                 |
| ---------------- | ------ | ----------------------------------------------------------- |
| `id`             | string | Config identifier                                           |
| `taskId`         | string | Associated task                                             |
| `url`            | string | Webhook destination                                         |
| `token`          | string | Optional token echoed back as `X-A2A-Token`                 |
| `authentication` | object | Optional `{ scheme, credentials }` used for `Authorization` |

## Task States

| State            | Type        | Description                           |
| ---------------- | ----------- | ------------------------------------- |
| `submitted`      | Initial     | Task was created and accepted         |
| `working`        | Active      | Task is running                       |
| `completed`      | Terminal    | Task completed successfully           |
| `failed`         | Terminal    | Task execution failed                 |
| `canceled`       | Terminal    | Task was canceled                     |
| `rejected`       | Terminal    | Task was refused                      |
| `input-required` | Interrupted | More input is required                |
| `auth-required`  | Interrupted | Additional authentication is required |

## Error Codes

### JSON-RPC Standard Errors

| Code     | Name             | Description                  |
| -------- | ---------------- | ---------------------------- |
| `-32700` | Parse Error      | Invalid JSON                 |
| `-32600` | Invalid Request  | Invalid JSON-RPC 2.0 payload |
| `-32601` | Method Not Found | Unknown method               |
| `-32602` | Invalid Params   | Missing or invalid params    |
| `-32603` | Internal Error   | Internal processing failure  |

### A2A-Specific Errors

| Code     | Name                            | Description                        |
| -------- | ------------------------------- | ---------------------------------- |
| `-32001` | Task Not Found                  | Unknown task ID                    |
| `-32002` | Task Not Cancelable             | Task is already terminal           |
| `-32003` | Push Notification Not Supported | Push notifications are unavailable |
| `-32004` | Unsupported Operation           | Unsupported method or flow         |
| `-32005` | Content Type Not Supported      | Unsupported `Content-Type`         |
| `-32006` | Invalid Agent Response          | Invalid agent response             |
| `-32007` | Skill Not Found                 | Unknown skill ID                   |

### Idempotency Conflicts

`SendMessage` uses idempotency. If the same idempotency key is already in progress, or if the same key is reused with a different request body, Clix responds with HTTP `409 Conflict` and a JSON-RPC error body using code `-32603`.

## Version Compatibility

For V0 method names, payload differences, and migration guidance, see [Version Compatibility](/a2a/version-compatibility).