PolyApiIDE works with gRPC services through JSON transcoding: it imports .proto files, helps you build the request body and read the response — but it does not open a native gRPC channel from the browser.
The important part first, so nobody is misled: native gRPC means HTTP/2 with trailers and binary protobuf, and browser code cannot open that channel. The gRPC workspace in PolyApiIDE targets services that sit behind JSON transcoding, where a gateway accepts plain HTTP with JSON and turns the call into gRPC.
JSON transcoding is a standard pattern in the gRPC ecosystem. A method in .proto gets an HTTP annotation (google.api.http), and the gateway starts accepting a JSON body on a normal URL, converting it into a protobuf message. That layer is almost everywhere: the grpc_json_transcoder filter in Envoy, grpc-gateway for Go, built-in JSON transcoding in ASP.NET Core.
For a client this is simply an HTTP request with JSON, which means all the familiar machinery applies: headers, auth, environments, variable substitution, QA checks, scripts and scenarios. The .proto file is there so you do not have to guess field names and types — importing it gives you the method list and the message structure.
| Scenario | In the browser | Comment |
|---|---|---|
| Unary call through a JSON gateway | Yes | An ordinary HTTP request with a JSON body |
| .proto import | Yes | Methods and message structure, on the free plan |
| Native gRPC channel | No | Needs HTTP/2 trailers that browser code cannot reach |
| Server or client streaming | No | Use a server-side tool: grpcurl, ghz, a desktop client |
| gRPC-Web without a proxy | No | gRPC-Web also requires a proxy in front of the service |
| Server reflection | No | Structure comes from the .proto file instead |
If there is no JSON transcoding gateway in front of your service, a browser client is the wrong tool for it. That is a platform limit, and we do not pretend to work around it.
Ask the service team whether it accepts JSON over HTTP and get the gateway base URL. A good sign is HTTP annotations in the .proto file and an import of google/api/annotations.proto.
.proto import is part of the free plan. After it you can see the method list and message fields, so the request body follows the schema instead of your memory.
The method becomes a POST (occasionally a GET) to the annotated path, with a JSON body shaped like the request message:
POST {{gateway}}/v1/users/42:activate
Content-Type: application/json
{"reason": "manual"}
Keep the token in an environment and reference it in the header as {{token}}. The value hierarchy is the same as for REST: request → collection → workspace → environment, with empty values skipped.
The gateway maps the gRPC status onto an HTTP code and puts the detail in the JSON body. The mapping table below tells you whether the service refused the call or the call failed validation.
| gRPC status | HTTP | Typical cause |
|---|---|---|
| OK | 200 | The call went through |
| INVALID_ARGUMENT | 400 | Body does not match the message in .proto |
| UNAUTHENTICATED | 401 | Token missing or expired |
| PERMISSION_DENIED | 403 | Token present, rights insufficient |
| NOT_FOUND | 404 | No such object — or the method is not exposed by the gateway |
| RESOURCE_EXHAUSTED | 429 | A quota kicked in |
| UNIMPLEMENTED | 501 | Method not implemented or not routed through the gateway |
| UNAVAILABLE | 503 | The service behind the gateway is down |
| DEADLINE_EXCEEDED | 504 | The call ran out of time |
The 404 and 501 pair is the most useful hint: it usually means the method exists in .proto but has no HTTP annotation.
Not from a browser. Native gRPC requires control over HTTP/2 trailers, which page code has no access to. We state it outright instead of promising gRPC in the browser and leaving you to find out.
For the methods and the message structure. A transcoded JSON body mirrors the protobuf message exactly, so having the field list removes the guesswork about names and types.
Server and client streaming are not available in a browser client. Use grpcurl or ghz for those. If you need a live stream specifically from the browser, look at WebSocket or SSE — both are supported.
Not for .proto import or sending calls — that is Free. Paid plans add automation: scenarios, load profiles, PDF reports and collection patches, with a lifetime licence available as a one-time purchase.