Proxy

POST/proxyV2

Universal execution endpoint. Single body shape for any tool, any upstream API.

Headers

Name

Type

Required

Description

Authorization

string

required

Bearer <api-key>

X-Cortex-Client-Id

string

required

Public client identifier

X-Cortex-User-Id

string

optional

End-user identifier for scoping

X-Cortex-App-Id

string

optional

Optional if toolId is composite (appId:::toolName)

Body

{
  toolId: string;       // 'appId:::toolName' or just 'toolName' if X-Cortex-App-Id is sent
  parameters: object;   // tool-specific JSON, validated against the OpenAPI spec
}

Example

curl -X POST https://us-central1-cortexconnectplatform.cloudfunctions.net/proxyV2 \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'X-Cortex-Client-Id: YOUR_CLIENT_ID' \
  -H 'X-Cortex-User-Id: your-end-user-id' \
  -H 'Content-Type: application/json' \
  -d '{
    "toolId": "your-app-id:::create_calendar_event",
    "parameters": {
      "summary": "Project sync",
      "start": "2026-05-06T10:00:00Z"
    }
  }'

Response

On success: 200 with normalized JSON envelope:

{
  "ok": true,
  "data": { ... },        // upstream response, JSON-serialized
  "meta": {
    "tool_id": "...",
    "duration_ms": 287,
    "provider": "google.calendar"
  }
}

On auth required: 401:

{
  "ok": false,
  "error": "auth_required",
  "auth_endpoint": "/initiateOAuth",
  "app_id": "..."
}

On RBAC denial: 403:

{ "ok": false, "error": "rbac_denied", "reason": "scope_missing", "scope": "calendar.write" }

On upstream failure: 502:

{ "ok": false, "error": "upstream_error", "upstream_status": 500, "upstream_body": "..." }

Idempotency

Send X-Cortex-Idempotency-Key (any string) to deduplicate retries. Responses are cached for 24 hours per (api-key, idempotency-key) pair.