---
title: "Provider proxy requests"
description: "Paths, authorization, parameters, bodies and access boundaries."
group: "Technical documentation"
order: 24
---

## Deployment addresses

- Documentation: https://ctx4.me/docs.md
- Agent index: https://ctx4.me/docs/agent-index.json
- Console and connections: https://console.ctx4.me/integrations
- MCP: https://ctx4.me/mcp
- HTTP API: https://ctx4.me/v1
- Composio base URL: https://ctx4.me/compat/context4/v1
- OpenAPI: https://ctx4.me/docs/openapi.json
- HTTP/MCP inventory: https://ctx4.me/docs/api-index.json
- Composio routes: https://ctx4.me/docs/compat-routes.json
- Connectors: https://ctx4.me/docs/connectors.json


# Provider proxy requests

## Choosing an interface

| Option | When to use it | Boundary |
| --- | --- | --- |
| Mirror `/v1/api/` | Call an HTTP method from the endpoint catalog | Published method and template only; JSON Schema is validated |
| Composio `tools/execute/proxy` | Raw call to a connected service API without a tool wrapper | Relative path within this connector's API; no tool schema |
| Session proxy | Raw call within an SDK session | Additionally session TTL, status, budget and pinned account |

Proxy requests let you call provider methods that have no separate tool. They do not provide arbitrary HTTP access to any address. The connection and connector configuration determine the provider, credentials and base address. For some connectors the origin comes from the connection and undergoes egress validation.

## Discovering a mirror endpoint

1. Retrieve `GET /v1/connectors/{connectorId}/endpoints` with `tools:read`. Filters: `q`, `group`, `include_removed`, `cursor`, `limit`.
2. Select an endpoint and request `GET /v1/connectors/{connectorId}/endpoint?method=GET&path=...`. `path` is the catalog template; encode it as a query value.
3. Read `input_schema`, `output_schema`, `risk`, `sensitive`, `idempotent`, `paging` and `descriptor_digest`. The input schema contains exact vendor fields; the format depends on the provider.
4. Fill in parameters and call its `call_url` with the described method.

[Complete discovery and mirror contract](https://ctx4.me/docs/api-endpoints.md). An endpoint ID consists of a method and path template. A removed entry may appear with `include_removed=true`, but cannot be executed. An endpoint does not automatically become an MCP tool.

## Mirror: request and response

```bash
curl "https://ctx4.me/v1/api/amocrm/api/v4/leads/7" \
  -H "Authorization: Bearer $CONTEXT4_API_KEY" \
  -H "Context4-Connection-Id: $CONTEXT4_CONNECTION_ID"
```

This is a GET request example applicable when the endpoint is in your catalog and the account can access the deal. Obtain the origin and keys from your environment. Bodyless methods have no body; for JSON writes, send vendor JSON directly. Mirror supports GET, POST, PUT, PATCH, DELETE; HEAD returns `405` and executes nothing.

The path mirrors the provider path after `/v1/api/{connectorId}/`. Send `/` literally or encode the entire vendorPath as one segment. A slash within a parameter value is `%2F`, or `%252F` when encoding the entire path. It is permitted only within a parameter of a known template; `.` and `..` parts are prohibited.

Query parameters and declared vendor headers are validated against the input schema. Arrays use repeated names or a delimiter according to the descriptor; unknown query parameters and repeated scalar parameters are rejected. Do not assume every incoming header is forwarded to the provider.

Calls require `executions:write`, including GET. `Context4-Connection-Id` is required; a different connector's connection or a revoked connection produces a platform conflict. An unknown endpoint returns `404` before an upstream request; invalid vendor parameters return `400` before execution creation.

The response preserves the provider's HTTP status and JSON body, and permitted `etag`/`retry-after` headers. `Context4-Origin: provider` distinguishes it from a platform error; `Context4-Execution-Id` associates the call with an execution. A platform error has `Context4-Origin: platform` and problem JSON. Do not treat every 403 as a policy error: check the origin.

The mirror catalog includes operations that accept and return JSON. Multipart, form bodies, arbitrary bytes and redirect-only downloads are not promised. An unavailable provider, timeout or non-JSON response can produce `503`. Each mirror call is a new request, even with a repeated Idempotency-Key.

## Raw Composio proxy

`POST /compat/context4/v1/api/v3.1/tools/execute/proxy` accepts:

```json
{
  "connected_account_id": "UUID of the selected connection",
  "endpoint": "/api/v4/leads",
  "method": "GET",
  "parameters": [
    { "name": "limit", "type": "query", "value": 10 }
  ]
}
```

Substitute a real UUID. `method`: GET, POST, PUT, DELETE, PATCH, HEAD. `endpoint` is a relative path from the connector's API base, starting with `/`. `parameters` is an array of objects with `name`, `type` (`header` or `query`) and string/numeric `value`; `in` is accepted instead of `type`. Optional `body` is JSON. Repeating a name in this legacy array replaces its previous value; for vendor arrays, prefer mirror with an explicit serialization schema.

The result is a JSON envelope `{status, data, headers}`. The compat request's own HTTP status differs from upstream `status`. Policy refusal returns 403, quota returns 429 and an unavailable account returns 404; permanent input/provider rejection maps to a validation error, transient failure to 503.

When `user_id` is supplied, the selected account is checked for usability by that principal. Optional `borrowers` narrows the owner set to the listed users and the principal; it does not remove the tenant boundary. With multiple accounts, choose `connected_account_id` explicitly. Session proxy uses its pinned account and session restrictions.

## Security and retry boundaries

Absolute URLs, `//host`, traversal, backslashes, raw fragments and control characters are prohibited. Raw proxy does not accept encoded slashes to bypass a template. Connected-service credentials are inserted by the server: do not send a provider token through proxy.

Caller headers `Authorization`, `Proxy-Authorization`, `Cookie`, `Cookie2`, `x-api-key` are prohibited. Transport control headers (`base-url-override`, `connection-id`, `provider-config-key`, `retries`, `retry-on`, `decompress`, `forward-headers-on-redirect`, `nango-*`) are also rejected. Hop-by-hop headers are removed. A Context4 bearer authenticates to Context4 and does not become a provider credential.

Raw proxy bypasses the tool wrapper schema while retaining tenant, policy, quota, rate limit and audit checks. This does not promise access to every endpoint regardless of connector and transport capabilities. Check the provider's documentation and operation availability. After a write timeout, verify the outcome: absence of a response does not prove absence of an effect.