HTTP Requests & Responses

Scripts make authenticated HTTP requests via context.connection.request(). The connection handles authentication, session management, relative URL resolution, and retry logic automatically.

Making Requests

response = await context.connection.request(method, url, **kwargs)

Parameters

Parameter	Type	Required	Default	Description
method	str	Yes	—	HTTP method: "GET", "POST", "PUT", "PATCH", "DELETE".
url	str	Yes	—	URL path. Relative paths (e.g. "/api/table") are resolved against the connection's api_root. Absolute URLs are used as-is.
params	dict	No	None	Query string parameters.
data	dict | str | bytes	No	None	Request body. Dicts are sent as JSON. Strings and bytes are sent as raw content.
headers	dict	No	None	Additional headers. Merged with authentication headers (auth headers take precedence).
files	dict	No	None	Multipart file uploads. Format: {"field": (filename, bytes, mime_type)}.
timeout	int	No	Connection default	Override the request timeout in seconds.
raise_on_error	bool	No	True	If True, raises ScriptExecutionError on non-2xx status codes. Set to False to handle errors manually.

Notes

• Authentication is applied automatically before each request.
• Relative URLs are prepended with the connection's api_root (e.g. "/api/table" becomes "https://example.com/api/table").
• When data is a dict and files is not set, the body is sent as JSON with the appropriate Content-Type header.
• When both data and files are set, the request is sent as multipart form data.

HTTPResponse

The request() method returns an HTTPResponse object.

Properties

Property	Type	Description
ok	bool	True if the status code is 200–299.
status_code	int	The HTTP status code (e.g. 200, 404, 500).
text	str	The response body as a string.
content	bytes	The response body as raw bytes. Useful for binary data (e.g. file downloads).
headers	dict	Response headers.
url	str	The final URL (after any redirects).
links	dict | None	Parsed Link headers, if present.
request_url	str	The original request URL.
request_body	Any	The request body that was sent.
request_headers	dict	The request headers that were sent.
request_params	dict | None	The query parameters that were sent.
response_time_ms	int	Response time in milliseconds.

Methods

json()

data = response.json()  # -> dict | list | None

Returns the parsed JSON response body, or None if the response is not valid JSON.

Common Patterns

GET request with query parameters

response = await context.connection.request("GET",
    f"/api/table/{context.table_name}",
    params={"limit": context.limit, "offset": context.offset})
data = response.json()

POST request with JSON body

response = await context.connection.request("POST",
    f"/api/table/{context.table_name}",
    data={"name": "New Record", "status": "active"})
result = response.json()

PATCH request

response = await context.connection.request("PATCH",
    f"/api/table/{context.table_name}/{context.record_id}",
    data=context.record.data)

File upload (multipart)

file_data = context.attachment.decoded_data()
response = await context.connection.request("POST",
    f"/api/table/{context.table_name}/{context.record_id}/attachments",
    files={"file": (context.attachment.file_name, file_data, context.attachment.file_type)})

File download (binary)

response = await context.connection.request("GET", download_url, raise_on_error=True)
raw_bytes = response.content  # bytes

Handling errors manually

response = await context.connection.request("GET",
    f"/api/table/{context.table_name}/{context.record_id}",
    raise_on_error=False)

if not response.ok:
    context.logger.warning(f"Request failed: {response.status_code} {response.text}")
    return None

data = response.json()

Custom headers

response = await context.connection.request("GET",
    f"/api/table/{context.table_name}",
    headers={"Accept": "application/json", "X-Custom": "value"})