Headers & Query Parameters

Headers and query parameters let you attach fixed or dynamic values to every connector request. Both support Jinja2 templates so you can inject user context, secrets, or other runtime values.

Headers

Add one or more header pairs using Header Key and Header Value. Use this for things like content type, API versioning, or auth headers.

Example values:

• Header Key: Content-Type → Header Value: application/json
• Header Key: Accept → Header Value: application/vnd.api+json;version=1

Reserved headers

The platform manages some headers itself, so a connector that sets one of them does not work. Names are matched regardless of capitalization and of leading or trailing spaces, so host and Host are blocked as well.

Host, Content-Length, Connection, Keep-Alive, TE, Trailer, Trailers, Transfer-Encoding, Upgrade, Proxy-Authorization, Proxy-Authenticate, Forwarded, X-Forwarded-For, X-Forwarded-Host, X-Forwarded-Proto

The platform may also add instrumentation headers to outgoing requests, so you cannot provide headers of that kind either.

This applies to every place a header name is set: a Header Key, the Key of API key authentication when In is Header, each step of a composite connector, and names that come from a template or an override. A query parameter with the same name is fine.

The fix: remove the header, or give it a different name if the target API accepts one, such as X-Correlation-Id. If you copied the headers from a browser, Postman, or cURL request, delete any tracing or instrumentation headers they contain. A request that fails with the failure scope "Configuration (runtime-owned header)" is caused by one of these headers. To find it, compare the header names in the X-Debug-Request header described in Testing & Debugging.

Query parameters

Add one or more parameter pairs using Query Key and Query Value. Use this for filters, search terms, pagination, or API keys.

Example values:

• Query Key: q → Query Value:

{{ user.email }}

• Query Key: limit → Query Value: 50

Values with spaces or special characters

If you put a value with spaces or special characters directly in the connector URL, the connector fails to save. The fix: move that value out of the URL and into a query parameter. The platform encodes query-parameter values automatically (spaces and characters like =, &, and quotes), so you never URL-encode them yourself. Auto-encoding applies to query-parameter values, not to the URL field itself.

For example, to send a search query such as select id from Account where Name = 'Acme Corp':

Approach	Result
Inline in the URL — https://api.example.com/query?q=select id from Account... (don't do this)	Rejected — the connector won't save
Query Key q → Query Value select id from Account where Name = 'Acme Corp'	Works — the value is encoded automatically

This applies wherever you configure query parameters, including the query_parameters array in Build a Composite Connector.

Overridable fields

Each header or query parameter has an Overridable checkbox. By default it is off, which means the value is always included in every request and cannot be changed at run time. Turn Overridable on when the caller should be able to change the value for a specific request.

When a field is marked as Overridable and no override is provided at run time, the configured value is used as the default. The field is still sent — it is never omitted just because no override was given.

Identity fields should not be overridable

If a query parameter or header carries user identity (such as a user ID or email), keep Overridable off and set the value to a server-side template variable like {{ user.id }}. This ensures the value is injected on the server and cannot be changed by browser code. See Passing User Context for details.

When to use path parameters instead

Query parameters live in the URL's query string (?key=value). For values that go in the URL path itself — for example, /users/{id}/posts where {id} varies per call — declare a path parameter instead. Each is configured in its own section of the connector; query-parameter entries are appended to the query string, while path-parameter values are substituted into {{ pathParams.X }} template references in the URL path.

See Dynamic URL Path Segments for the full pattern.

Next Steps

• Dynamic URL Path Segments — For values that belong in the URL path, not the query string
• Testing & Debugging — Verify headers and parameters are sent correctly
• Template Variables — Jinja2 syntax for dynamic values
• Authentication — Add auth credentials alongside headers