POpolytomic
Connections

Execute Connection Proxy

Changed on

Proxies an HTTP request to a connection's underlying API using the connection's stored credentials, subject to per-connection rate limits and size caps.

This endpoint is intended for controlled passthrough use, not as a general replacement for Polytomic's modeled endpoints. The request is executed with the connection's stored credentials and inherited base URL, headers, and query parameters.

Before building requests dynamically, call GET /api/connections/{id}/proxy/info to inspect the inherited base URL, blocked headers, accepted body types, and size and rate limits.

Important behavior

  • For connections that expose more than one API (listed in apis in the proxy info response), set request.api to the name of the API to call. Requests without request.api go to the default API. request.api is rejected for connections that expose a single API.
  • request.path must be relative and start with /.
  • Use either request.query or request.rawQuery, not both.
  • Caller-supplied headers are merged with inherited headers, but inherited auth headers cannot be overridden.
  • The proxy strips a fixed set of request and response headers for safety.
  • Response bodies larger than the configured maximum are truncated, and truncated is set to true.
  • A 429 means Polytomic's proxy rate limit was reached, or the connection's upstream quota, which the proxy shares with the connection's syncs, is exhausted.

To run a GET request asynchronously, set async to true. The initial response returns status: 202, jobId, jobStatus, and jobUrl. Poll GET /api/jobs/{type}/{id} with type=connectionproxy and the returned jobId until the job is complete. The completed job result includes the upstream status, sanitized headers, contentType, contentLength, latencyMs, and a short-lived bodyDownloadUrl for the upstream response body.

The response includes proxyCallId, which you can use to correlate the call with audit logs.

post/api/connections/{id}/proxy

Request

  • Base URL
    https://app.polytomic.com
  • Auth
    • HTTP bearer
    • or HTTP basic

Path parameters

idstring uuid required

Unique identifier of the connection to proxy the request through

Example:248df4b7-aa70-47b8-a036-33ac447e668d

Headers

X-Polytomic-Versionstring

Request body

asyncboolean

When true, submits a GET request for asynchronous execution and returns a job handle instead of a synchronous upstream response

Example request

{
  "request": {
    "api": "reports",
    "method": "GET",
    "path": "/v1/objects",
    "rawQuery": "ids=List(A,B,C)"
  }
}

Response

OK

Example response

{
  "data": {
    "contentType": "application/json",
    "jobId": "248df4b7-aa70-47b8-a036-33ac447e668d",
    "proxyCallId": "248df4b7-aa70-47b8-a036-33ac447e668d",
    "status": 200
  }
}

Changes

  • d80b0fdea14eRevision changes
    • breaking

      the response's property type changed from object to no type for status

    • warning

      removed the optional property / from the response with the status

    • warning

      removed the optional property / from the response with the status

    • warning

      removed the optional property / from the response with the status

    • warning

      removed the optional property / from the response with the status

    • warning

      removed the optional property / from the response with the status

    • warning

      removed the optional property / from the response with the status

    • warning

      removed the optional property / from the response with the status

    • warning

      removed the optional property / from the response with the status

    • warning

      removed the optional property / from the response with the status

    • warning

      removed the optional property / from the response with the status

    • info

      added to the response property allOf list for the response status

  • 61c2b96f65baRevision changes
    • breaking

      added to the request property allOf list

    • breaking

      the request property type changed from object to no type

    • breaking

      the / response's property type changed from string to no type for status

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • info

      added to the / response property allOf list for the response status

    • info

      removed the created enum value from the / response property for the response status

    • info

      removed the done enum value from the / response property for the response status

    • info

      removed the failed enum value from the / response property for the response status

    • info

      removed the running enum value from the / response property for the response status