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

​
Endpoints

PathMethodAuthDescription
/.well-known/agent-card.jsonGETNonePublic Agent Card
/a2aPOSTX-API-KeyAuthenticated JSON-RPC methods
Base URL: https://api.clix.so

​
Headers

HeaderDirectionRequiredDescription
A2A-VersionRequestRecommendedUse 1.0. Omitting it defaults to V0 (0.3).
Content-TypeRequestFor /a2aMust be application/json.
X-API-KeyRequestFor /a2aSecret API Key with the clix_sk_ prefix.
X-Clix-Idempotency-KeyRequestOptionalExplicit idempotency key for SendMessage. Falls back to message.messageId.
X-Request-IDResponseAlwaysCorrelation 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:
ParamTypeDescription
contextIdstringFilter tasks by context
statusstringFilter by protocol state value such as completed or failed
pageSizeintegerPage size. The current default is 50.
pageTokenstringCursor 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

FieldTypeDescription
idstringTask identifier
contextIdstringConversation or session grouping key
statusobjectCurrent task state, message, and timestamp
artifactsarrayOutput artifacts
historyarrayMessage history
metadataobjectOptional metadata

​
Message

FieldTypeDescription
messageIdstringUnique message identifier
rolestringuser, agent, or unspecified
partsarrayText or data parts
contextIdstringOptional context ID
taskIdstringOptional task linkage

​
Part

FieldTypeDescription
textstringPlain text content
dataobjectStructured JSON content
metadataobjectOptional metadata

​
Artifact

FieldTypeDescription
artifactIdstringUnique artifact identifier
namestringArtifact type such as user-result
partsarrayOutput parts

​
TaskPushNotificationConfig

FieldTypeDescription
idstringConfig identifier
taskIdstringAssociated task
urlstringWebhook destination
tokenstringOptional token echoed back as X-A2A-Token
authenticationobjectOptional { scheme, credentials } used for Authorization

​
Task States

StateTypeDescription
submittedInitialTask was created and accepted
workingActiveTask is running
completedTerminalTask completed successfully
failedTerminalTask execution failed
canceledTerminalTask was canceled
rejectedTerminalTask was refused
input-requiredInterruptedMore input is required
auth-requiredInterruptedAdditional authentication is required

​
Error Codes

​
JSON-RPC Standard Errors

CodeNameDescription
-32700Parse ErrorInvalid JSON
-32600Invalid RequestInvalid JSON-RPC 2.0 payload
-32601Method Not FoundUnknown method
-32602Invalid ParamsMissing or invalid params
-32603Internal ErrorInternal processing failure

​
A2A-Specific Errors

CodeNameDescription
-32001Task Not FoundUnknown task ID
-32002Task Not CancelableTask is already terminal
-32003Push Notification Not SupportedPush notifications are unavailable
-32004Unsupported OperationUnsupported method or flow
-32005Content Type Not SupportedUnsupported Content-Type
-32006Invalid Agent ResponseInvalid agent response
-32007Skill Not FoundUnknown 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.