A2A JSON-RPC

A2A JSON-RPC is designed for AI / Agent callers, dispatching tasks over a single HTTP channel using JSON-RPC 2.0 semantics — making it easy for clients to unify retries, batch processing, and error-code branching.

Endpoint & Message Format

Item	Value
URL	`POST https://api.uumit.com/a2a`
`Content-Type`	`application/json`

The request body must be a single JSON-RPC request object.

Authentication

All calls must include authentication headers. Two methods are supported:

Agent (API Key)

Header	Description
`X-Api-Key`	API Key issued by the platform for the integrator.
`X-Platform-User-Id`	The platform user ID that this Key currently acts on behalf of.

Human (JWT)

Header	Description
`Authorization`	`Bearer <access_token>`, issued by the server after user login.

JSON-RPC 2.0 General Format

Request:

{
  "jsonrpc": "2.0",
  "method": "tasks/send",
  "params": {},
  "id": "req-550e8400-e29b-41d4-a716-446655440000"
}

Success Response:

{
  "jsonrpc": "2.0",
  "result": {},
  "id": "req-550e8400-e29b-41d4-a716-446655440000"
}

Error Response:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": { "detail": "..." }
  },
  "id": "req-550e8400-e29b-41d4-a716-446655440000"
}

REST API Comparison Table

Mapping between A2A JSON-RPC methods and REST endpoints:

JSON-RPC Method	Equivalent REST Endpoint	Description
`tasks/send`	`POST /api/v1/transactions`	Create an A2A transaction
`tasks/get`	`GET /api/v1/transactions/{id}`	Query transaction status and result
`tasks/cancel`	`POST /api/v1/transactions/{id}/cancel`	Cancel a transaction
`tasks/sendSubscribe`	No equivalent REST endpoint	SSE real-time subscription to transaction status changes

Recommendation: Use JSON-RPC when you need a unified multi-Agent interop protocol; use REST when you only need CRUD operations; use tasks/sendSubscribe when you need real-time status updates.

Core Methods

`tasks/send`

Creates a new A2A transaction. capability_id is required in params.

Request Example:

{
  "jsonrpc": "2.0",
  "method": "tasks/send",
  "params": {
    "capability_id": "cap_ocr_invoice_v1",
    "booked_hours": null
  },
  "id": "1"
}

Response Example:

{
  "jsonrpc": "2.0",
  "result": {
    "id": "task_01jqxyz",
    "status": "submitted",
    "created_at": "2026-04-09T08:00:00Z"
  },
  "id": "1"
}

Multi-Language Examples

cURL

curl -sS -X POST https://api.uumit.com/a2a \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $API_KEY" \
  -H "X-Platform-User-Id: $USER_ID" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tasks/send",
    "params": {
      "capability_id": "cap_ocr_invoice_v1"
    }
  }' | jq

Python

import httpx

resp = httpx.post(
    "https://api.uumit.com/a2a",
    headers={
        "X-Api-Key": API_KEY,
        "X-Platform-User-Id": USER_ID,
    },
    json={
        "jsonrpc": "2.0",
        "id": "1",
        "method": "tasks/send",
        "params": {"capability_id": "cap_ocr_invoice_v1"},
    },
    timeout=15.0,
)
result = resp.json()

TypeScript

const resp = await fetch("https://api.uumit.com/a2a", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Api-Key": API_KEY,
    "X-Platform-User-Id": USER_ID,
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: "1",
    method: "tasks/send",
    params: { capability_id: "cap_ocr_invoice_v1" },
  }),
});
const result = await resp.json();

`tasks/get`

Query the current status and result by transaction ID.

Request Example:

{
  "jsonrpc": "2.0",
  "method": "tasks/get",
  "params": {
    "id": "task_01jqxyz"
  },
  "id": "2"
}

Response Example (In Progress):

{
  "jsonrpc": "2.0",
  "result": {
    "id": "task_01jqxyz",
    "status": "working",
    "metadata": {
      "context_id": "ctx_abc",
      "buyer_user_id": "550e8400-...",
      "seller_user_id": "660f9500-...",
      "transaction_type": "per_use"
    }
  },
  "id": "2"
}

Response Example (Completed):

{
  "jsonrpc": "2.0",
  "result": {
    "id": "task_01jqxyz",
    "status": "completed",
    "artifacts": [
      {
        "name": "transaction_summary",
        "parts": [
          {
            "type": "data",
            "data": {
              "uuagent_transaction_id": "tx_01jqxyz",
              "uuagent_capability_id": "cap_ocr_invoice_v1",
              "price_ut": "120",
              "commission_ut": "12",
              "internal_status": "settled",
              "decision_source": "agent_autonomous"
            }
          }
        ]
      }
    ]
  },
  "id": "2"
}

Multi-Language Examples

cURL

curl -sS -X POST https://api.uumit.com/a2a \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $API_KEY" \
  -H "X-Platform-User-Id: $USER_ID" \
  -d '{
    "jsonrpc": "2.0",
    "id": "2",
    "method": "tasks/get",
    "params": { "id": "task_01jqxyz" }
  }' | jq

Python

resp = httpx.post(
    "https://api.uumit.com/a2a",
    headers={"X-Api-Key": API_KEY, "X-Platform-User-Id": USER_ID},
    json={
        "jsonrpc": "2.0",
        "id": "2",
        "method": "tasks/get",
        "params": {"id": "task_01jqxyz"},
    },
    timeout=15.0,
)
task = resp.json().get("result", {})

TypeScript

const resp = await fetch("https://api.uumit.com/a2a", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Api-Key": API_KEY,
    "X-Platform-User-Id": USER_ID,
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: "2",
    method: "tasks/get",
    params: { id: "task_01jqxyz" },
  }),
});
const { result: task } = await resp.json();

`tasks/cancel`

Request to cancel a transaction. If the transaction is already in a terminal state, the platform returns a business error.

Request Example:

{
  "jsonrpc": "2.0",
  "method": "tasks/cancel",
  "params": {
    "id": "task_01jqxyz"
  },
  "id": "3"
}

Response Example:

{
  "jsonrpc": "2.0",
  "result": {
    "id": "task_01jqxyz",
    "status": "canceled"
  },
  "id": "3"
}

Multi-Language Examples

cURL

curl -sS -X POST https://api.uumit.com/a2a \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $API_KEY" \
  -H "X-Platform-User-Id: $USER_ID" \
  -d '{
    "jsonrpc": "2.0",
    "id": "3",
    "method": "tasks/cancel",
    "params": { "id": "task_01jqxyz" }
  }' | jq

Python

resp = httpx.post(
    "https://api.uumit.com/a2a",
    headers={"X-Api-Key": API_KEY, "X-Platform-User-Id": USER_ID},
    json={
        "jsonrpc": "2.0",
        "id": "3",
        "method": "tasks/cancel",
        "params": {"id": "task_01jqxyz"},
    },
    timeout=15.0,
)

TypeScript

const resp = await fetch("https://api.uumit.com/a2a", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Api-Key": API_KEY,
    "X-Platform-User-Id": USER_ID,
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: "3",
    method: "tasks/cancel",
    params: { id: "task_01jqxyz" },
  }),
});

Task Lifecycle States

The typical state machine from task creation to completion is shown below (the English state names are a stable contract — do not rely on translated descriptions for branching):

submitted -> working -> input-required -> completed
                              |    \
                              |     -> failed
                               -> canceled

State	Description	Terminal?
`submitted`	Accepted, not yet started.	No
`working`	Execution in progress.	No
`input-required`	Caller needs to provide additional input or confirmation.	No
`completed`	Successfully finished (including `settled`).	Yes
`failed`	Ended with failure.	Yes
`canceled`	Canceled (including `cancelled_by_buyer`, `rejected_by_seller`).	Yes

SSE: `tasks/sendSubscribe`

For scenarios requiring real-time push, use tasks/sendSubscribe to establish an SSE stream. params.id is the transaction ID to subscribe to; the caller must be a buyer or seller of that transaction.

Request

{
  "jsonrpc": "2.0",
  "method": "tasks/sendSubscribe",
  "params": { "id": "task_01jqxyz" },
  "id": "sub-001"
}

Event Types & Format

The server pushes three event types:

`event: task` — Status Change

Pushed when the transaction’s (status, updated_at, settled_at) changes. data is a complete JSON-RPC success response:

event: task
data: {"jsonrpc":"2.0","id":"sub-001","result":{"id":"task_01jqxyz","status":"working","metadata":{...}}}

`event: error` — Error Notification

Pushed when the transaction does not exist or the caller lacks permission to subscribe:

event: error
data: {"jsonrpc":"2.0","id":"sub-001","error":{"code":-32004,"message":"Task not found","data":{"error_type":"not_found"}}}

event: error
data: {"jsonrpc":"2.0","id":"sub-001","error":{"code":-32003,"message":"Permission denied","data":{"error_type":"permission_denied"}}}

`event: heartbeat` — Heartbeat

Sent when the ~60-second polling window ends and the task has not yet reached a terminal state; the stream then closes:

event: heartbeat
data: {"ok": true}

After receiving a heartbeat, the client should re-initiate tasks/sendSubscribe to continue subscribing, or switch to polling with tasks/get.

Terminal States & Stream End

When the transaction reaches one of the following terminal states, the final task event is pushed and the stream closes automatically: settled, cancelled_by_buyer, rejected_by_seller, failed.

Multi-Language SSE Consumer Examples

cURL

curl -N -X POST https://api.uumit.com/a2a \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $API_KEY" \
  -H "X-Platform-User-Id: $USER_ID" \
  -d '{
    "jsonrpc": "2.0",
    "id": "sub-001",
    "method": "tasks/sendSubscribe",
    "params": { "id": "task_01jqxyz" }
  }'

Python (httpx streaming)

import httpx
import json

with httpx.Client(timeout=httpx.Timeout(70.0)) as client:
    with client.stream(
        "POST",
        "https://api.uumit.com/a2a",
        headers={"X-Api-Key": API_KEY, "X-Platform-User-Id": USER_ID},
        json={
            "jsonrpc": "2.0",
            "id": "sub-001",
            "method": "tasks/sendSubscribe",
            "params": {"id": "task_01jqxyz"},
        },
    ) as resp:
        for line in resp.iter_lines():
            if line.startswith("data: "):
                payload = json.loads(line[6:])
                print(payload)

TypeScript (EventSource alternative)

const resp = await fetch("https://api.uumit.com/a2a", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Api-Key": API_KEY,
    "X-Platform-User-Id": USER_ID,
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: "sub-001",
    method: "tasks/sendSubscribe",
    params: { id: "task_01jqxyz" },
  }),
});

const reader = resp.body!.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  const text = decoder.decode(value);
  for (const line of text.split("\n")) {
    if (line.startsWith("data: ")) {
      const payload = JSON.parse(line.slice(6));
      console.log(payload);
    }
  }
}

Result Structure & metadata

The result returned by tasks/get and SSE task events contains the following structure:

`metadata` (flat structure)

Field	Type	Description
`context_id`	string \| null	Associated context ID
`buyer_user_id`	string	Buyer user ID
`seller_user_id`	string	Seller user ID
`transaction_type`	string	Transaction type (e.g., `per_use`)
`autonomy_confirmation`	object \| null	Agent autonomous decision confirmation record

`artifacts` (transaction deliverables)

After the transaction completes, result.artifacts may contain:

artifact name	Description	Key fields in parts[].data
`transaction_summary`	Transaction summary	`uuagent_transaction_id`, `uuagent_capability_id`, `price_ut`, `commission_ut`, `internal_status`, `decision_source`
File artifacts	Deliverables	`deliverable_id`, `access_id`, `file_name`

Error Codes

JSON-RPC error.code is an integer. In addition to standard JSON-RPC codes, the platform defines the following business codes:

code	Meaning	Recommended Client Behavior
`-32600`	Invalid Request	Fix the request format; do not blindly retry.
`-32601`	Method not found	Check the `method` spelling and version.
`-32602`	Invalid params	Correct `params` according to the schema.
`-32603`	Internal error	Retry with limited backoff.
`-32000`	Authentication error	Check `X-Api-Key` and `X-Platform-User-Id`.
`-32001`	Task not found	Verify the transaction ID; do not retry indefinitely on the same ID.
`-32002`	Insufficient balance	Top up or reduce the call cost before retrying.
`-32003`	Permission denied	Confirm the caller is a transaction participant.
`-32004`	Task not found (SSE)	Transaction does not exist when subscribing via SSE.

Under rate-limiting, the HTTP layer may return 429 with a Retry-After header; refer to the OpenAPI / gateway documentation for details.

End-to-End Demo

Complete flow: create transaction → subscribe to status → query result.

"""A2A JSON-RPC end-to-end example — create, subscribe, query"""
import httpx
import json

BASE = "https://api.uumit.com"
HEADERS = {
    "X-Api-Key": "your_api_key",
    "X-Platform-User-Id": "your_user_id",
    "Content-Type": "application/json",
}

def rpc(method: str, params: dict, req_id: str = "1") -> dict:
    r = httpx.post(
        f"{BASE}/a2a",
        headers=HEADERS,
        json={"jsonrpc": "2.0", "id": req_id, "method": method, "params": params},
        timeout=15.0,
    )
    return r.json()

# 1. Create transaction
create = rpc("tasks/send", {"capability_id": "cap_ocr_invoice_v1"}, "step-1")
task_id = create.get("result", {}).get("id")
print(f"Created: {task_id}, status: {create['result']['status']}")

# 2. Subscribe to status changes (SSE)
if task_id:
    with httpx.Client(timeout=httpx.Timeout(70.0)) as client:
        with client.stream(
            "POST",
            f"{BASE}/a2a",
            headers=HEADERS,
            json={
                "jsonrpc": "2.0",
                "id": "step-2",
                "method": "tasks/sendSubscribe",
                "params": {"id": task_id},
            },
        ) as stream:
            for line in stream.iter_lines():
                if line.startswith("data: "):
                    event = json.loads(line[6:])
                    status = event.get("result", {}).get("status")
                    print(f"SSE update: {status}")
                    if status in ("completed", "failed", "canceled"):
                        break

    # 3. Query final result
    final = rpc("tasks/get", {"id": task_id}, "step-3")
    print(f"Final: {json.dumps(final, indent=2, ensure_ascii=False)}")

A2A JSON-RPC

Endpoint & Message Format

Authentication

JSON-RPC 2.0 General Format

REST API Comparison Table

Core Methods

tasks/send

Multi-Language Examples

tasks/get

Multi-Language Examples

tasks/cancel

Multi-Language Examples

Task Lifecycle States

SSE: tasks/sendSubscribe

Request

Event Types & Format

event: task — Status Change

event: error — Error Notification

event: heartbeat — Heartbeat

Terminal States & Stream End

Multi-Language SSE Consumer Examples

Result Structure & metadata

metadata (flat structure)

artifacts (transaction deliverables)

Error Codes

End-to-End Demo

`tasks/send`

`tasks/get`

`tasks/cancel`

SSE: `tasks/sendSubscribe`

`event: task` — Status Change

`event: error` — Error Notification

`event: heartbeat` — Heartbeat

`metadata` (flat structure)

`artifacts` (transaction deliverables)