Headers

Because the qibdo Cloud API is defined in gRPC and exposed over REST by a transcoding gateway (see API standards), requests and responses use a small, predictable set of HTTP headers. This page covers what you send and what you get back.

Request headers

What a client sends:

Header	When	Value
Authorization	Every request	Bearer $QIBDO_API_TOKEN. Identifies the caller; access is resolved by IAM. See the security baseline.
Content-Type	Requests with a body (POST, PATCH, and custom methods that take a body)	application/json.
Accept	Optional	application/json. JSON is the only representation the gateway produces, so this is effectively the default.

Notes:

• Reads carry no body. GET (Get, List) and DELETE requests need only Authorization; there is nothing to set Content-Type for. List parameters (page_size, page_token, filter, order_by) travel in the query string, not in headers (see API standards).
• Source address and client. The gateway records the caller’s source IP (from x-forwarded-for) and user-agent. You do not set these yourself, the gateway and any upstream proxy populate them, but they matter because an IAM policy can restrict access by source IP.

Response headers

On every response you receive:

Header	Value
Content-Type	application/json, for both success and error responses.
grpc-status	The numeric gRPC status code: 0 on success, non-zero on error (for example 5 for NOT_FOUND).

On an error response you also receive:

Header	Value
grpc-message	The error description, the [<code>] <message> text from the error envelope.
grpc-status-details-bin	Base64-encoded google.rpc.Status, the same structured error the gateway also writes into the JSON body.

Plus the HTTP status line, whose code is derived from grpc-status (for example NOT_FOUND becomes 404). The full mapping is on the Errors page.

These grpc-* headers appear because every service is gRPC underneath and the gateway surfaces the gRPC trailers on the HTTP response. They mirror the HTTP status code and the JSON body, so treat them as informational (useful mainly for debugging) and branch on the HTTP status code and read the JSON body as your contract.

The JSON body itself always follows the same conventions, fixed by the gateway’s transcoding options: field names are snake_case, enum values are their string names (not integers), and primitive fields are always present (zero values and empty collections are not omitted). The body shapes are documented in Standard responses.

How transcoding shapes the response

Under the hood every call is gRPC. The gateway translates between REST/JSON and gRPC in both directions (AIP-127), which is what produces the headers above.

• On success, the gRPC response message becomes the JSON body and the call returns 200.
• On error, gRPC reports the failure in its trailers: grpc-status, grpc-message, and a binary grpc-status-details-bin that carries the structured google.rpc.Status. The gateway converts that gRPC status into the HTTP response: it sets the matching HTTP status code and writes the google.rpc.Status as the JSON error body. It also surfaces the original grpc-* trailers as response headers (the ones listed above), so the same status is visible in both places.

As a REST client you do not need to parse the grpc-* headers. Branch on the HTTP status code and read the JSON body exactly as described on Standard responses (success) and Errors (failure). gRPC-native clients see the same status through the trailers directly.

See also

• Standard responses for the success, operation, and list body shapes.
• Errors for the error envelope and the gRPC to HTTP status mapping.
• Security baseline and IAM for obtaining and using the bearer token.