Data plane wire protocols

These pages describe how a running data product accepts traffic at the protocol level: which operations exist on gRPC vs HTTP, how authentication and serialization work, and how streaming reads and writes behave.

Typical work does not need this material. Use the application integration guides (client libraries and MCP) for normal product integration. Return here when you are building a client in a language we do not ship yet, writing integration tests or debug tooling that must speak to the data plane directly, or need an exact account of request and response shapes for code generation and automation (including agent-driven workflows).

gRPC and REST in one sentence each

• gRPC (HTTP/2) — the full data plane: API calls, append streams, and outlet streams. The same host also supports gRPC-Web so browser-style clients can use a compatible stack without a separate binary-only endpoint.
• REST (HTTP/1.1 over TLS) — API operations only. There is no REST surface for append or outlet; those are gRPC (or gRPC-Web) only.

Prefer gRPC (or a client library on top of it) when you can. Use plain HTTP/REST when the caller cannot use gRPC (e.g. a minimal HTTP client, curl, or a host where you only want request/response without a gRPC stack).

What is available where

Surface	gRPC	REST
API operations (unary)	Yes	Yes (GET or POST per operation)
Ingest (append, packaged append, read-back)	Yes (streaming)	No
Outlet (read stream)	Yes (streaming)	No
OAuth protected-resource metadata (RFC 9728)	n/a	GET /.well-known/oauth-protected-resource
Model Context Protocol (MCP)	n/a	GET/POST under /mcp/* where configured

Shared behavior

• TLS — the data plane serves HTTPS. Optional client-certificate (mTLS) authentication is available when your deployment is configured for it.
• Authentication — short-lived JWTs as Bearer tokens. On gRPC, send authorization: Bearer <jwt> in metadata; on REST, send the same in the Authorization header. The same token issuers and validation rules apply to both.
• Identity — after validation, the service treats the subject as a Dataspine principal (for example the dataspine_uid claim) for authorization and audit. You normally do not parse this by hand if you use a client library.
• Payload encoding — request and response bodies use either the internal binary encoding (v0) or JSON (v0). The byte layout of the binary form is in Internal binary serialization (v1).

Deeper reference

• gRPC — services, request/response envelopes, status codes, long-lived stream reauthentication, chunking.
• REST — URL patterns, content negotiation, JSON vs binary, raw downloads.

For supported clients and MCP, see Application integration.