> ## Documentation Index
> Fetch the complete documentation index at: https://composio-preview.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Execute proxy request within a tool router session

> Execute any native API call on a toolkit with authentication automatically injected from Composio. This endpoint proxies HTTP requests to third-party APIs using connected account credentials resolved from the session context. Provide the toolkit slug, API endpoint, and HTTP method — Composio handles authentication injection, abstracting away credential management. Supports all HTTP methods, custom headers/query parameters, and binary request/response bodies.



## OpenAPI

````yaml api-reference/openapi-v3.json POST /api/v3/tool_router/session/{session_id}/proxy_execute
openapi: 3.0.0
info:
  version: 3.0.0
  title: Composio Platform API
  description: >-
    Composio v3 API — legacy endpoints under /api/v3/. Use v3.1 for new
    integrations.
  contact:
    name: Composio Support
    url: https://composio.dev/support
    email: support@composio.dev
  license:
    name: Proprietary
    url: https://composio.dev/terms
servers:
  - url: https://backend.composio.dev
    description: Composio production API
security:
  - ApiKeyAuth: []
tags:
  - name: Authentication
    description: Authentication related endpoints
    x-group: Authentication
  - name: Auth Configs
    description: Authentication configuration management
    x-group: Auth Configs
  - name: Connected Accounts
    description: Connected account management
    x-group: Connected Accounts
  - name: Logs
    description: Logging and monitoring
    x-group: Logs
  - name: OpenAPI
    description: OpenAPI specification management
    x-group: OpenAPI
  - name: Organization
    description: Organization management
    x-group: Organization
  - name: API Keys
    description: API key management
    x-group: API Keys
  - name: Webhooks
    description: Webhook configuration
    x-group: Webhooks
  - name: Webhook Endpoints
    description: >-
      Per-OAuth-app webhook ingress endpoints. Inbound URLs the provider posts
      to, plus signing secret storage and verification.
    x-group: Webhook Endpoints
  - name: Webhook Subscriptions
    description: >-
      Webhook delivery subscriptions. Outbound URLs Composio posts trigger
      events to, plus signing secret rotation and event-type filters.
    x-group: Webhook Subscriptions
  - name: Team
    description: Team member management
    x-group: Team
  - name: Consumer Skills
    description: Organization-authored Skill management
    x-group: Consumer Skills
  - name: Toolkits
    description: Toolkit and tool management
    x-group: Toolkits
  - name: Tools
    description: Tool execution endpoints
    x-group: Tools
  - name: Triggers
    description: Trigger management and execution
    x-group: Triggers
  - name: Payments
    description: Payment and subscription management
    x-group: Payments
  - name: Billing
    description: Dashboard billing state — usage, subscription, contract (cookie-auth only)
    x-group: Billing
  - name: Compliance
    description: Organization compliance agreements and acceptance state
    x-group: Compliance
  - name: Files
    description: File management
    x-group: Files
  - name: MCP
    description: MCP server management
    x-group: MCP
  - name: MCP Partner
    description: MCP partner management
    x-group: MCP Partner
  - name: Stripe Projects
    description: Stripe Projects provisioning
    x-group: Stripe Projects
  - name: Tool Router
    description: (Labs) Tool router endpoints
    x-group: Sessions (Prev Tool Router)
  - name: Playground
    description: Dashboard playground chat
    x-group: Playground
  - name: Arena
    description: Arena conversations, messages and terms
    x-group: Arena
  - name: Organization Management
    description: Organization Management API endpoints.
    x-group: Organization Management
  - name: Projects
    description: Projects API endpoints.
    x-group: Projects
paths:
  /api/v3/tool_router/session/{session_id}/proxy_execute:
    post:
      tags:
        - Tool Router
      summary: Execute proxy request within a tool router session
      description: >-
        Execute any native API call on a toolkit with authentication
        automatically injected from Composio. This endpoint proxies HTTP
        requests to third-party APIs using connected account credentials
        resolved from the session context. Provide the toolkit slug, API
        endpoint, and HTTP method — Composio handles authentication injection,
        abstracting away credential management. Supports all HTTP methods,
        custom headers/query parameters, and binary request/response bodies.
      operationId: postToolRouterSessionBySessionIdProxyExecute
      parameters:
        - schema:
            type: string
            format: toolRouterSessionId
            description: >-
              The unique identifier of the tool router session. Required for
              public API endpoints, optional for internal endpoints where it is
              injected by middleware.
            example: trs_LX9uJKBinWWr
          required: true
          description: >-
            Tool router session ID (required for public API, optional for
            internal - injected by middleware)
          name: session_id
          in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                toolkit_slug:
                  type: string
                  description: The slug of the toolkit to use for the request
                  example: gmail
                endpoint:
                  type: string
                  description: >-
                    The API endpoint to call (absolute URL or path relative to
                    base URL of the connected account)
                  example: /api/v1/resources
                method:
                  type: string
                  enum:
                    - GET
                    - POST
                    - PUT
                    - DELETE
                    - PATCH
                    - HEAD
                  description: The HTTP method to use for the request
                  example: GET
                body:
                  nullable: true
                  description: The request body (for POST, PUT, and PATCH requests)
                  example:
                    name: New Resource
                    description: This is a new resource
                  type: object
                binary_body:
                  anyOf:
                    - type: object
                      properties:
                        url:
                          type: string
                          format: uri
                          description: URL to fetch binary content from
                        content_type:
                          type: string
                          description: Content-Type header to use for the request
                      required:
                        - url
                    - type: object
                      properties:
                        base64:
                          type: string
                          minLength: 1
                          description: Base64-encoded binary data
                        content_type:
                          type: string
                          description: Content-Type header to use for the request
                      required:
                        - base64
                  description: >-
                    Binary body to send. For binary upload via URL: use {url:
                    "https://...", content_type?: "..."}. For binary upload via
                    base64: use {base64: "...", content_type?: "..."}.
                parameters:
                  type: array
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                        description: Parameter name
                        example: x-api-key
                      value:
                        type: string
                        description: Parameter value
                        example: abc123def456
                      type:
                        type: string
                        enum:
                          - header
                          - query
                        description: Parameter type (header or query)
                        example: header
                    required:
                      - name
                      - value
                      - type
                  description: >-
                    Additional HTTP headers or query parameters to include in
                    the request
                  example:
                    - name: x-api-key
                      value: abc123def456
                      type: header
                    - name: filter
                      value: active
                      type: query
                custom_connection_data:
                  deprecated: true
                  type: object
                  properties:
                    authScheme:
                      type: string
                      enum:
                        - OAUTH2
                        - DCR_OAUTH
                        - API_KEY
                        - BASIC_WITH_JWT
                        - BASIC
                        - BEARER_TOKEN
                        - OAUTH1
                        - NO_AUTH
                        - SERVICE_ACCOUNT
                        - GOOGLE_SERVICE_ACCOUNT
                        - S2S_OAUTH2
                    toolkitSlug:
                      type: string
                    val:
                      type: object
                      properties:
                        subdomain:
                          type: string
                        your-domain:
                          type: string
                        region:
                          type: string
                        shop:
                          type: string
                        account_url:
                          type: string
                        COMPANYDOMAIN:
                          type: string
                        extension:
                          type: string
                        form_api_base_url:
                          type: string
                        instanceEndpoint:
                          type: string
                        api_url:
                          type: string
                        borneo_dashboard_url:
                          type: string
                        proxy_username:
                          type: string
                        proxy_password:
                          type: string
                        domain:
                          type: string
                        version:
                          type: string
                        dc:
                          type: string
                        site_name:
                          type: string
                        instanceName:
                          type: string
                        account_id:
                          type: string
                        your_server:
                          type: string
                        server_location:
                          type: string
                        base_url:
                          type: string
                        displayName:
                          type: string
                        state_prefix:
                          type: string
                          maxLength: 40
                          description: The oauth2 state prefix for the connection
                        long_redirect_url:
                          type: boolean
                          description: >-
                            Whether to return the redirect url without
                            shortening
                        access_token:
                          type: string
                        id_token:
                          type: string
                          nullable: true
                        token_type:
                          type: string
                        refresh_token:
                          type: string
                          nullable: true
                        expires_in:
                          anyOf:
                            - type: number
                            - type: string
                            - nullable: true
                              type: object
                        scope:
                          anyOf:
                            - type: string
                            - type: array
                              items:
                                type: string
                            - nullable: true
                              type: object
                        webhook_signature:
                          type: string
                        authed_user:
                          type: object
                          properties:
                            access_token:
                              type: string
                            scope:
                              type: string
                          description: for slack user scopes
                        extra_token_data:
                          type: object
                          additionalProperties: {}
                        client_id:
                          type: string
                          description: Dynamically registered client ID
                        client_secret:
                          type: string
                          description: Dynamically registered client secret
                        client_id_issued_at:
                          type: number
                        client_secret_expires_at:
                          type: number
                        generic_api_key:
                          type: string
                        api_key:
                          type: string
                        bearer_token:
                          type: string
                        basic_encoded:
                          type: string
                        username:
                          type: string
                        password:
                          type: string
                        token:
                          type: string
                        oauth_token:
                          type: string
                        oauth_token_secret:
                          type: string
                        oauth_verifier:
                          type: string
                        consumer_key:
                          type: string
                        redirectUrl:
                          type: string
                        callback_url:
                          type: string
                        application_id:
                          type: string
                        installation_id:
                          type: string
                        private_key:
                          type: string
                        credentials_json:
                          type: string
                        expires_at:
                          type: string
                      required:
                        - access_token
                      additionalProperties: {}
                  additionalProperties: true
                  required:
                    - authScheme
                    - toolkitSlug
                    - val
              required:
                - toolkit_slug
                - endpoint
                - method
      responses:
        '200':
          description: Successfully executed proxy request and received response
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ProxyExecuteCompleted'
                  - $ref: '#/components/schemas/ProxyExecuteBlocked'
                  - $ref: '#/components/schemas/ExecuteRequiresUserInput'
                discriminator:
                  propertyName: result_type
                  mapping:
                    completed: '#/components/schemas/ProxyExecuteCompleted'
                    blocked: '#/components/schemas/ProxyExecuteBlocked'
                    input_required: '#/components/schemas/ExecuteRequiresUserInput'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: Payment required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '410':
          description: Gone
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: Payload too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: Bad gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - ApiKeyAuth: []
        - UserApiKeyAuth: []
components:
  schemas:
    ProxyExecuteCompleted:
      type: object
      properties:
        result_type:
          type: string
          enum:
            - completed
          description: The request was sent and the proxied API responded
          x-experimental: true
        data:
          nullable: true
          description: The response data returned from the proxied API
          example:
            id: '123'
            name: Resource Name
            created_at: '2023-01-01T00:00:00Z'
          type: object
        binary_data:
          type: object
          properties:
            url:
              type: string
              description: URL to download binary content
            content_type:
              type: string
              description: Content-Type of the binary data
            size:
              type: number
              description: File size in bytes
            expires_at:
              type: string
              description: ISO 8601 timestamp when the URL expires
          required:
            - url
            - content_type
            - size
          description: >-
            Binary body response data. Present when the response is a binary
            file.
        status:
          type: number
          description: The HTTP status code returned from the proxied API
          example: 200
        headers:
          type: object
          additionalProperties:
            type: string
          description: The HTTP headers returned from the proxied API
          example:
            content-type: application/json
            cache-control: no-cache
        hook_results:
          type: array
          items:
            $ref: '#/components/schemas/HookResult'
          description: >-
            Every session hook that applied to this request. Omitted when none
            applied.
      required:
        - result_type
        - status
    ProxyExecuteBlocked:
      type: object
      properties:
        result_type:
          type: string
          enum:
            - blocked
          description: A session hook stopped the call
        reason:
          $ref: '#/components/schemas/BlockReason'
        message:
          type: string
          description: >-
            A message for the agent. It includes the hook's name, when it has
            one; the hook id is in `reason`.
          example: 'Blocked by session policy: No external email'
        hook_results:
          type: array
          items:
            $ref: '#/components/schemas/HookResult'
          description: >-
            Every session hook that applied to this call. Omitted when none
            applied.
      required:
        - result_type
        - reason
        - message
    ExecuteRequiresUserInput:
      type: object
      properties:
        result_type:
          type: string
          enum:
            - input_required
          description: The call needs the user's input before it runs
          x-experimental: true
        input_requests:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/UserInputRequest'
          description: Questions for the user, keyed by an ID the answers must reuse
          x-experimental: true
        request_state:
          type: string
          description: Send this back unchanged in `request_state` with the answers
          x-experimental: true
      required:
        - result_type
        - input_requests
      description: >-
        The call needs the user's input before it runs. Returned only when the
        session is configured to ask for user approval before tool execution.
        Show each question in `input_requests` to the user, then repeat the same
        call with their answers in `input_responses`, along with this
        `request_state` if present.
      x-experimental: true
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            code:
              type: number
            slug:
              type: string
            status:
              type: number
            request_id:
              type: string
            suggested_fix:
              type: string
            errors:
              type: array
              items:
                type: string
          required:
            - message
            - code
            - slug
            - status
      required:
        - error
    HookResult:
      oneOf:
        - type: object
          properties:
            id:
              type: string
              description: The hook id
            status:
              type: string
              enum:
                - evaluated
            outcome:
              type: string
              enum:
                - continue
                - block
              description: What the hook decided
          required:
            - id
            - status
            - outcome
        - type: object
          properties:
            id:
              type: string
              description: The hook id
            status:
              type: string
              enum:
                - unavailable
              description: The hook could not be evaluated
          required:
            - id
            - status
    BlockReason:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - request_blocked
              description: A before_execute hook stopped the call. The tool did not run.
            hook_id:
              type: string
          required:
            - type
            - hook_id
        - type: object
          properties:
            type:
              type: string
              enum:
                - response_blocked
              description: >-
                An after_execute hook stopped the call. The tool ran; its
                response was withheld.
            hook_id:
              type: string
          required:
            - type
            - hook_id
    UserInputRequest:
      type: object
      properties:
        type:
          type: string
          enum:
            - elicitation
          description: Always `elicitation`
        mode:
          type: string
          enum:
            - form
          description: >-
            Always `form`: collect the answer with a form built from
            `requested_schema`
        message:
          type: string
          description: Text to show the user
          example: |-
            Your agent wants to run the following tool:

            GITHUB_DELETE_A_REPOSITORY({"owner": "acme", "repo": "old-api"})
        requested_schema:
          type: object
          additionalProperties: {}
          description: >-
            JSON Schema for the answer. As in MCP form mode, it is a flat object
            whose fields are strings, numbers, booleans, or single- or
            multi-select enums.
      required:
        - type
        - mode
        - message
        - requested_schema
      description: >-
        A question for the user, in the shape of an MCP `elicitation/create`
        request in form mode
        (https://modelcontextprotocol.io/specification/2026-07-28/client/elicitation).
        Show `message` to the user and collect an answer that matches
        `requested_schema`.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Your Composio project API key. Create or copy it from the Composio
        dashboard.
      x-default: your-project-api-key
    UserApiKeyAuth:
      type: apiKey
      in: header
      name: x-user-api-key
      description: Your Composio user API key for user-scoped endpoints.
      x-default: your-user-api-key

````