gRPC

Endpoint

• Service: argand.agent_api.v1.AgentApi
• Port: 50100
• TLS: required for production deployments. Local dev runs plaintext.
• Proto file: proto/agent_api.proto in the source tree.

argand.org's hosted gateway leaves :50100 closed by default — REST is the canonical public surface. gRPC is the stable contract for self-hosters and large-fleet integrators who set PUBLIC_GRPC_ENABLED=true on the gateway.

Service contract

service AgentApi {
  rpc Search(SearchRequest) returns (SearchResponse);
  rpc Fetch(FetchRequest) returns (FetchResponse);
  rpc Cite(CiteRequest) returns (CiteResponse);
  rpc HealthCheck(HealthCheckRequest) returns (HealthCheckResponse);
}

Stability: bumping major implies a new package (v2, v3) shipped alongside; never an in-place breaking edit. Field numbers are reserved on removal and never reused. Optional fields are preferred so agent fleets tolerate version skew.

Search RPC

Mirrors the MCP search tool — same response shape including optional risk_signals on registry-scoped hits. Fields: query (required), limit, vertical, freshness, locale, min_weekly_downloads.

grpcurl \
  -H 'x-argand-key: your-argand-api-key' \
  -d '{"query":"rust async runtime","limit":5}' \
  argand.example.org:50100 \
  argand.agent_api.v1.AgentApi/Search

Fetch & Cite

Fetch takes a URL Argand vouches for (came back from a Search response) and returns the cached/canonicalized snapshot. Cite returns a citation block with archive timestamp + content hash. Both mirror the MCP tools of the same names.

HealthCheck RPC

For load balancers and sidecar probes:

grpcurl argand.example.org:50100 \
  argand.agent_api.v1.AgentApi/HealthCheck

Auth

Set the x-argand-key metadata entry to your opaque API key. Same anonymous-tier semantics as REST: no key works at the lower quota tier. The same opaque-string-only contract — no DID coupling.