Clix Documentation

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

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

Response

{
  "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:

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

Current built-in Clix skills emit statusUpdate events. They do not currently emit artifactUpdate events during streaming.

GetTask

Reads a task by ID. Request

{
  "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

{
  "jsonrpc": "2.0",
  "id": "req-3",
  "method": "ListTasks",
  "params": {
    "pageSize": 20,
    "contextId": "ctx-uuid"
  }
}

Response

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

On the first page, totalSize contains the total matching count. On later cursor requests, the current Clix implementation returns 0.

CancelTask

Cancels a non-terminal task. Request

{
  "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

{
  "jsonrpc": "2.0",
  "id": "req-5",
  "method": "SubscribeToTask",
  "params": {
    "id": "task-uuid"
  }
}

Response

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

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.

CreateTaskPushNotificationConfig

Registers a webhook for task events. Request

{
  "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

{
  "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

{
  "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

{
  "jsonrpc": "2.0",
  "id": "req-8",
  "method": "ListTaskPushNotificationConfigs",
  "params": {
    "taskId": "task-uuid"
  }
}

Response

{
  "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

{
  "jsonrpc": "2.0",
  "id": "req-9",
  "method": "DeleteTaskPushNotificationConfig",
  "params": {
    "taskId": "task-uuid",
    "id": "config-uuid"
  }
}

Both taskId and id are required. Response

{
  "jsonrpc": "2.0",
  "id": "req-9",
  "result": null
}

GetExtendedAgentCard

Returns the authenticated Agent Card. Request

{
  "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.

User Guide

Quick Start (Installation)

Essentials

Campaigns

Model Context Protocol

Agent Skills

Agent-to-Agent (A2A)

Integrations

API Reference

Troubleshooting

Security & Ops

API Reference

Endpoints

Headers

JSON-RPC Methods

SendMessage

SendStreamingMessage

GetTask

ListTasks

CancelTask

SubscribeToTask

CreateTaskPushNotificationConfig

GetTaskPushNotificationConfig

ListTaskPushNotificationConfigs

DeleteTaskPushNotificationConfig

GetExtendedAgentCard

Data Types

Task

Message

Part

Artifact

TaskPushNotificationConfig

Task States

Error Codes

JSON-RPC Standard Errors

A2A-Specific Errors

Idempotency Conflicts

Version Compatibility

​Endpoints

​Headers

​JSON-RPC Methods

​SendMessage

​SendStreamingMessage

​GetTask

​ListTasks

​CancelTask

​SubscribeToTask

​CreateTaskPushNotificationConfig

​GetTaskPushNotificationConfig

​ListTaskPushNotificationConfigs

​DeleteTaskPushNotificationConfig

​GetExtendedAgentCard

​Data Types

​Task

​Message

​Part

​Artifact

​TaskPushNotificationConfig

​Task States

​Error Codes

​JSON-RPC Standard Errors

​A2A-Specific Errors

​Idempotency Conflicts

​Version Compatibility

Endpoints

Headers

JSON-RPC Methods

SendMessage

SendStreamingMessage

GetTask

ListTasks

CancelTask

SubscribeToTask

CreateTaskPushNotificationConfig

GetTaskPushNotificationConfig

ListTaskPushNotificationConfigs

DeleteTaskPushNotificationConfig

GetExtendedAgentCard

Data Types

Task

Message

Part

Artifact

TaskPushNotificationConfig

Task States

Error Codes

JSON-RPC Standard Errors

A2A-Specific Errors

Idempotency Conflicts

Version Compatibility