Complete API Documentation

{
  "issuer": "https://registry.symphonix.health",
  "registry_id": "gharra://GB/registries/nhs-spine",
  "tier": "sovereign",
  "jurisdiction": "GB",
  "api_base_url": "https://registry.symphonix.health/v1",
  "jwks_uri": "https://registry.symphonix.health/.well-known/jwks.json",
  "registration_endpoint": "/v1/agents",
  "discovery_endpoint": "/v1/discover",
  "routing_endpoint": "/v1/route",
  "events_endpoint": "/v1/events/stream",
  "trust_anchors_endpoint": "/v1/trust/anchors",
  "supported_auth_methods": ["jwt", "mtls", "dpop"],
  "signed_metadata": "eyJhbGciOi..."
}

{
  "agents": [{ /* AgentRecord */ }],
  "next_cursor": "eyJ...",
  "total_count": 142
}

curl -X POST https://registry.symphonix.health/v1/agents \
  -H "Authorization: Bearer <token>" \
  -H "X-Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Radiology Summariser",
    "jurisdiction": "GB",
    "endpoints": [{
      "url": "https://rad.nhs.example/a2a",
      "protocol": "nexus-a2a-jsonrpc",
      "priority": 1
    }],
    "capabilities": {
      "protocols": ["nexus-a2a-jsonrpc"],
      "fhir_r4": true,
      "consent_support": true
    },
    "trust": { "certificates": ["..."] }
  }'

{ "reason": "Agent decommissioned per compliance audit" }

import httpx

resp = httpx.get(
    "https://registry.symphonix.health/v1/discover",
    params={
        "capability": "fhir-r4-patient-search",
        "jurisdiction": "GB",
        "purpose_of_use": "treatment",
    },
    headers={"Authorization": f"Bearer {token}"},
)
agents = resp.json()["results"]

{
  "query": { "capability": "fhir-r4-patient-search", "jurisdiction": "GB" },
  "results": [{ /* AgentRecord */ }],
  "result_count": 7,
  "signed_response": "eyJhbGciOi..."
}

{
  "target": "gharra://GB/agents/01HXR...",
  "required_features": ["stream_resume"],
  "residency": {
    "allowed_zones": ["eu-west-1", "eu-west-2"],
    "deny_cross_zone": true
  },
  "workload": {
    "token_binding": "mtls_cnf_x5t_s256",
    "priority": "high"
  },
  "purpose": { "purpose_of_use": "treatment" }
}

{
  "resolved_target": "gharra://GB/agents/01HXR...",
  "selected": {
    "endpoint": "https://rad.nhs.example/a2a",
    "protocol": "nexus-a2a-jsonrpc",
    "region": "eu-west-2"
  },
  "alternatives": [{ "endpoint": "...", "priority": 2 }],
  "trust_bundle": { /* TrustBundle */ },
  "constraints": {
    "phi_allowed": true,
    "max_concurrency_hint": 50,
    "rate_limit_rps_hint": 100
  },
  "evidence": {
    "registry_id": "gharra://GB/registries/nhs-spine",
    "record_version": "3",
    "delegation_chain": ["gharra://root", "gharra://GB"]
  }
}

{
  "anchors": [{
    "key_id": "gharra-root-2025",
    "alg": "ES256",
    "jwks_uri": "https://registry.symphonix.health/.well-known/jwks.json",
    "thumbprint_sha256": "abc123...",
    "role": "root",
    "not_before": "2025-01-01T00:00:00Z",
    "not_after": "2027-01-01T00:00:00Z"
  }]
}

curl -N -H "Authorization: Bearer <token>" \
  "https://registry.symphonix.health/v1/events/stream?cursor=seq_42"

{
  "key_id": "gharra_key_01HXR...",
  "raw_key": "gharra_sk_live_abc123...",
  "org_id": "my-org",
  "display_name": "Production Key",
  "tier": "team",
  "scopes": ["gharra:read", "gharra:write"],
  "created_at": "2026-03-29T10:00:00Z"
}

{
  "jsonrpc": "2.0",
  "method": "tasks/send",
  "params": {
    "sender": "did:web:hospital.org:agents:triage",
    "recipient": "did:web:lab.org:agents:pathology",
    "message": {
      "kind": "message",
      "role": "user",
      "parts": [{
        "kind": "text",
        "text": "Analyze this blood sample for Malaria."
      }]
    }
  },
  "id": "req-12345"
}

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

{
  "jsonrpc": "2.0",
  "method": "tasks/get",
  "params": { "task_id": "550e8400-..." },
  "id": "req-12346"
}

curl -X POST http://localhost:8100/rpc/triage_agent \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tasks/send","params":{"message":{"kind":"message","role":"user","parts":[{"kind":"text","text":"Patient presents with chest pain"}]}},"id":1}'

{
  "jsonrpc": "2.0",
  "method": "avatar/start_session",
  "params": {
    "patient_case": {
      "chief_complaint": "Chest tightness with exertion",
      "age": 54,
      "gender": "male",
      "urgency": "high"
    },
    "persona": {
      "name": "Dr. Alex",
      "role": "cardiologist"
    }
  },
  "id": 1
}

{
  "jsonrpc": "2.0",
  "method": "avatar/patient_message",
  "params": {
    "session_id": "avatar-xxxxx",
    "message": "I get chest tightness when climbing stairs."
  },
  "id": 2
}

{ "text": "How long have you had this tightness?", "voice": "alloy" }

{
  "method": "tools/call",
  "params": {
    "name": "discover_agents",
    "arguments": {
      "capability": "fhir-r4-patient-search",
      "jurisdiction": "GB",
      "purpose_of_use": "treatment"
    }
  }
}

{
  "content": [{
    "type": "text",
    "text": "Found 3 agents matching fhir-r4-patient-search in GB:\n1. NHS Spine PDS Agent (gharra://GB/agents/01HXR...)\n2. ..."
  }]
}

{
  "method": "tools/call",
  "params": {
    "name": "route",
    "arguments": {
      "target_agent_id": "gharra://GB/agents/01HXR...",
      "purpose_of_use": "treatment"
    }
  }
}

{
  "method": "tools/call",
  "params": {
    "name": "register",
    "arguments": {
      "display_name": "Radiology Summariser",
      "jurisdiction": "GB",
      "endpoint_url": "https://rad.nhs.example/a2a",
      "capabilities": ["radiology.summarise", "fhir-r4-diagnosticreport"]
    }
  }
}

from gharra import RegistryClient

# Initialise with API key or JWT
client = RegistryClient(
    base_url="https://registry.symphonix.health",
    api_key="sk-..."   # or token="eyJ..."
)

# Discover agents
agents = client.discover(
    capability="fhir-r4-patient-search",
    jurisdiction="GB"
)

# Route to the best endpoint
route = client.route(agents[0].agent_id)
print(route.selected.url)  # https://spine.nhs.uk/a2a

# Send a task via Nexus A2A
result = client.send_task(
    endpoint=route.selected.url,
    method="tasks/send",
    params={"query": "Find patient by MRN 00412"}
)

from gharra.nexus import NexusClient

nexus = NexusClient(
    endpoint="https://rad.nhs.example/a2a",
    token="eyJ..."
)

# Streaming response via SSE
async for event in nexus.stream_task(
    method="tasks/sendSubscribe",
    params={"query": "Summarise latest chest X-ray for MRN 00412"}
):
    print(event.status, event.message)