---
title: "Proxy-запросы к провайдеру"
description: "Пути, авторизация, параметры, тело и границы доступа."
group: "Техническая документация"
order: 24
---

## Адреса этого стенда

- Документация: https://context4.me/docs.md
- Индекс для агента: https://context4.me/docs/agent-index.json
- Консоль и подключения: https://console.context4.me/integrations
- MCP: https://context4.me/mcp
- HTTP API: https://context4.me/v1
- Composio base URL: https://context4.me/compat/context4/v1
- OpenAPI: https://context4.me/docs/openapi.json
- Каталог HTTP/MCP: https://context4.me/docs/api-index.json
- Маршруты Composio: https://context4.me/docs/compat-routes.json
- Коннекторы: https://context4.me/docs/connectors.json


# Proxy-запросы к провайдеру

## Выбор интерфейса

| Вариант | Когда использовать | Граница |
| --- | --- | --- |
| Mirror `/v1/api/` | Вызов HTTP-метода из каталога endpoint | Только опубликованные метод и шаблон; JSON Schema проверяется |
| Composio `tools/execute/proxy` | Raw-вызов API подключённого сервиса без tool wrapper | Относительный путь внутри API этого коннектора; без схемы инструмента |
| Session proxy | Raw-вызов внутри SDK-сессии | Дополнительно TTL, статус, budget и закреплённый аккаунт сессии |

Proxy позволяет обращаться к методам провайдера, для которых нет отдельного инструмента. Это не произвольный HTTP-доступ к любому адресу. Провайдер, credentials и базовый адрес определяются подключением и конфигурацией коннектора. Для некоторых коннекторов origin берётся из подключения и проходит egress-проверку.

## Обнаружение mirror endpoint

1. Получите `GET /v1/connectors/{connectorId}/endpoints` с `tools:read`. Фильтры: `q`, `group`, `include_removed`, `cursor`, `limit`.
2. Выберите endpoint и запросите `GET /v1/connectors/{connectorId}/endpoint?method=GET&path=...`. `path` — шаблон из каталога; кодируйте его как query value.
3. Прочитайте `input_schema`, `output_schema`, `risk`, `sensitive`, `idempotent`, `paging` и `descriptor_digest`. Входная схема содержит точные vendor-поля; формат зависит от провайдера.
4. Заполните параметры и вызовите его `call_url` методом из описания.

[Полный контракт discovery и mirror](https://context4.me/docs/api-endpoints.md). Endpoint ID имеет вид метода и шаблона пути. Удалённая запись может присутствовать в списке с `include_removed=true`; выполнить её нельзя. Endpoint не становится автоматически MCP-инструментом.

## Mirror: запрос и ответ

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

Это пример формы GET, который применим, если данный endpoint есть в вашем каталоге и аккаунт имеет доступ к сделке. Origin и ключи берутся из вашего окружения. Тело отсутствует у bodyless-метода; для JSON-записи передавайте vendor JSON напрямую. Mirror поддерживает GET, POST, PUT, PATCH, DELETE; HEAD даёт `405` и ничего не исполняет.

Путь зеркалирует путь провайдера после `/v1/api/{connectorId}/`. Можно передавать `/` буквально либо закодировать весь vendorPath одним сегментом. Slash внутри одного значения параметра передаётся как `%2F`, а при кодировании всего пути — `%252F`. Он допустим только в параметре известного шаблона; `.` и `..` части запрещены.

Query и объявленные vendor-заголовки проверяются входной схемой. Массивы передаются повторёнными именами или разделителем согласно descriptor; неизвестный query и повтор скалярного параметра отклоняются. Нельзя предполагать, что любой входящий заголовок будет отправлен провайдеру.

Вызов требует `executions:write`, включая GET. `Context4-Connection-Id` обязателен; чужой коннектор или отозванное подключение даёт platform conflict. Неизвестный endpoint даёт `404` до upstream-запроса, неверные vendor-параметры — `400` до создания execution.

Ответ сохраняет HTTP-статус и JSON-тело провайдера, допустимые `etag`/`retry-after`. `Context4-Origin: provider` отличает его от platform-ошибки, `Context4-Execution-Id` связывает вызов с выполнением. Ошибка платформы имеет `Context4-Origin: platform` и problem JSON. Не считайте любой 403 ошибкой политики: проверьте origin.

Каталог mirror включает операции, которые можно передать JSON в обе стороны. Multipart, form body, произвольные bytes и redirect-only download не обещаны. Недоступный provider, таймаут или не-JSON ответ могут дать `503`. Каждый mirror-вызов — новый запрос, даже с повторённым Idempotency-Key.

## Raw Composio proxy

`POST /compat/context4/v1/api/v3.1/tools/execute/proxy` принимает:

```json
{
  "connected_account_id": "UUID выбранного подключения",
  "endpoint": "/api/v4/leads",
  "method": "GET",
  "parameters": [
    { "name": "limit", "type": "query", "value": 10 }
  ]
}
```

Подставьте реальный UUID. `method`: GET, POST, PUT, DELETE, PATCH, HEAD. `endpoint` — относительный путь от API base коннектора с начальным `/`. `parameters` — массив объектов с `name`, `type` (`header` или `query`) и строковым/числовым `value`; `in` принимается вместо `type`. Необязательный `body` — JSON. Повтор имени в этом legacy массиве заменяет предыдущее значение; для vendor-массивов предпочтителен mirror с явной схемой сериализации.

Результат — JSON-конверт `{status, data, headers}`. HTTP-статус самого compat-запроса отличается от upstream `status`. Policy refusal даёт 403, quota — 429, недоступный аккаунт — 404; permanent input/provider rejection отображается как validation error, transient failure — 503.

Если передан `user_id`, выбранный аккаунт проверяется на возможность использования этим principal. Необязательный `borrowers` сужает набор владельцев до перечисленных и самого principal; он не отменяет tenant-границу. При нескольких аккаунтах выбирайте `connected_account_id` явно. Session proxy использует закреплённый аккаунт и ограничения сессии.

## Границы безопасности и повторов

Запрещены абсолютный URL, `//host`, traversal, обратный slash, raw fragment и управляющие символы. Raw proxy не принимает encoded slash как обход шаблона. Credentials подключённого сервиса подставляются сервером: не передавайте provider token через proxy.

Caller-заголовки `Authorization`, `Proxy-Authorization`, `Cookie`, `Cookie2`, `x-api-key` запрещены. Заголовки управления транспортом (`base-url-override`, `connection-id`, `provider-config-key`, `retries`, `retry-on`, `decompress`, `forward-headers-on-redirect`, `nango-*`) также отклоняются. Hop-by-hop заголовки удаляются. Context4 bearer используется для входа в Context4 и не становится credential провайдера.

Raw proxy обходит схему tool wrapper, сохраняя tenant, policy, quota, rate limit и audit. Это не обещание доступа к любому endpoint независимо от возможностей коннектора и его транспорта. Проверяйте документацию самого провайдера и доступность операции. После таймаута записи сверяйте исход: отсутствие ответа не доказывает отсутствие эффекта.