The Request & Response configuration defines an endpoint's contract — the inputs it accepts from callers and the response shapes it returns for each HTTP status code.
Overview
Every published endpoint has a contract: what the caller must send, and what they can expect back. Defining this contract precisely ensures callers know exactly how to use the endpoint, feeds the OpenAPI export, and lets the platform enforce validation before your backing automation ever runs. Both the request and the response are defined per endpoint, not inherited from the collection.
Defining the Request
An endpoint's incoming request is composed of typed parameters plus an optional body. Each parameter carries a name, a schema (type and validation), and a required flag.
Parameter Type | Where It Appears | Example |
|---|---|---|
Path parameters | Embedded in the URL path | {"{id}"} in /orders/{"{id}"} |
Query parameters | After the ? in the URL | ?status=open |
Request headers | HTTP headers the caller sends | X-Correlation-ID |
Cookies | Cookie values | Session token |
Request body | The JSON or XML payload | POST/PUT/PATCH payloads |
Parameters marked required form part of the contract callers must follow. They appear in the OpenAPI export so consumers know what is mandatory.
Defining Responses
You describe responses as a schema per HTTP status code — for example a 200 success shape, a 400 validation-error shape, and a 500 error shape. Each entry pairs a status code with the body schema and content type (such as application/json). Defining responses this way documents every outcome for callers, feeds the OpenAPI export, and makes the API self-describing. Define at least the success response (2xx) and the common error shapes (400, 500).
Enforcing Required Parameters
Parameters marked required form the endpoint's structural contract. To enforce them at the gateway level — rejecting malformed requests before the backing resource runs — attach a request validator policy to the endpoint or collection. A request missing a required parameter is then rejected with a clear error rather than passed through to the automation where the failure would be less obvious. Your backing automation can also perform its own validation for business-rule checks the structural validator cannot cover.
How the Request Reaches the Backing Resource
When the endpoint is backed by a Callable or Webhook automation, the platform maps the request — path variables, query parameters, headers, and body — into the automation's inputs before running it. For an External API endpoint, the request is forwarded to the upstream URL with your configured authentication and headers, and the upstream response is returned. For an LLM Model, the payload is passed to the model. The request and response schemas you define here are the outer contract callers see; how the inner resource maps its own inputs and outputs is configured when you set up the endpoint's resource.
Notes
Mark only the parameters your operation genuinely requires as required — optional parameters need not be listed as required just because they are commonly sent.
Define response schemas for error codes as carefully as for success codes — callers build error-handling logic from those shapes.
Export the OpenAPI spec after defining request and response schemas to give consumers an accurate, up-to-date contract.
Use a request validator policy to enforce structural rules at the gateway; use the backing automation for business logic validation.
For REST endpoints, the request body schema applies to POST, PUT, and PATCH methods; GET and DELETE typically use path or query parameters instead.