pikasTech-HWLAB/protocol/json-rpc.md

JSON-RPC Envelope

HWLAB command-style APIs use JSON-RPC 2.0 envelopes.

Request

{
  "jsonrpc": "2.0",
  "id": "req_01J00000000000000000000000",
  "method": "hardware.operation.request",
  "params": {
    "projectId": "prj_01J00000000000000000000000"
  },
  "meta": {
    "traceId": "trc_01J00000000000000000000000",
    "actorId": "usr_01J00000000000000000000000",
    "serviceId": "hwlab-cloud-api",
    "environment": "dev"
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": "req_01J00000000000000000000000",
  "result": {
    "accepted": true
  },
  "meta": {
    "traceId": "trc_01J00000000000000000000000",
    "serviceId": "hwlab-cloud-api",
    "environment": "dev"
  }
}

Error

{
  "jsonrpc": "2.0",
  "id": "req_01J00000000000000000000000",
  "error": {
    "code": -32020,
    "message": "Requested hardware capability is unavailable",
    "data": {
      "capabilityId": "cap_01J00000000000000000000000"
    }
  },
  "meta": {
    "traceId": "trc_01J00000000000000000000000",
    "serviceId": "hwlab-gateway",
    "environment": "dev"
  }
}

Envelope Rules

• jsonrpc is always 2.0.
• id is required for request/response flows and must be echoed unchanged.
• method names use dotted lower-case namespaces.
• params must be an object when present.
• A response contains exactly one of result or error.
• meta.traceId is required for all cross-service calls.
• meta.environment is dev for MVP.