API

The Temporal cluster exposes both a public API (consumed by user SDKs and the CLI) and a set of internal APIs (consumed by the cluster's own services). All of them are gRPC; some have HTTP/REST gateways.

API	Protos	Implementation	HTTP gateway?
WorkflowService — public	go.temporal.io/api → temporal.api.workflowservice.v1	service/frontend/workflow_handler.go	yes
OperatorService — public, cluster admin	temporal.api.operatorservice.v1	service/frontend/operator_handler.go	yes
AdminService — server-internal	proto/internal/temporal/server/api/adminservice/v1	service/frontend/admin_handler.go	no
HistoryService — server-internal	proto/internal/temporal/server/api/historyservice/v1	service/history/handler.go	no
MatchingService — server-internal	proto/internal/temporal/server/api/matchingservice/v1	service/matching/handler.go	no
Nexus inbound (HTTP)	n/a (HTTP)	service/frontend/nexus_handler.go	n/a (HTTP-only)

Public protos

The public protos live in go.temporal.io/api, an external repository pulled in via go.mod. To change them you submit a PR to that repo, then make update-go-api here. Public-facing services are:

• WorkflowService — every user-facing operation: start, signal, query, update, list, search.
• OperatorService — namespace, search-attribute, cluster, schedule administration.
• Nexus — public Nexus interfaces (registry, dispatch).

Internal protos

Server-internal protos live in proto/internal/. They are generated to Go under api/. To change them, edit the proto and run make proto.

Sub-tree	Purpose
historyservice/	Frontend → History.
matchingservice/	Frontend → Matching, History → Matching.
adminservice/	Cluster admin (DLQ, shard inspection, namespace replication).
replication/	History ↔ History across clusters.
cluster/, namespace/, enums/, errordetails/, health/, taskqueue/, …	Shared message types.

HTTP API

The Frontend service runs an HTTP/REST gateway on a separate port (default 7243). It is built with grpc-gateway and forwards each REST call to the corresponding gRPC handler over loopback. Implementation: service/frontend/http_api_server.go.

The OpenAPI spec is served at /api/v1/openapi.json (see service/frontend/openapi_http_handler.go). The Web UI uses this gateway.

Nexus has its own HTTP-only path because its semantics (HTTP callbacks, headers) are not naturally REST. See service/frontend/nexus_handler.go.

Generated wrappers

Inter-service clients in client/ are generated to wrap the raw gRPC stubs with retry, metric, rate-limit, and (in tests) fault-injection layers. The generator is cmd/tools/genrpcwrappers/; the corresponding server-side interceptor wiring is generated by cmd/tools/genrpcserverinterceptors/.

Where to read more

• Frontend service — public-API gateway implementation.
• How to contribute → Tooling — code generators.
• docs/architecture/ — hand-written deep dives on parts of the API surface (e.g. nexus.md, workflow-update.md).