---
title: "Start a WebMCP invocation"
method: POST
path: "/api/session/{id}/webmcp/invocations"
---

# Start a WebMCP invocation

`POST /api/session/{id}/webmcp/invocations`

## Request

- Base URL: `https://api.hyperbrowser.ai`
- URL: `https://api.hyperbrowser.ai/api/session/{id}/webmcp/invocations`
- Auth: API key in header `x-api-key`
- TypeScript: <https://skmtc.dev/hyperbrowser/apis/hyperbrowser-api/docs/api/session/:id/webmcp/invocations/post.ts> (a function with typed inputs; its response is checked against the schema)

Start once and return a handle without waiting for completion. Acceptance does not guarantee success; inspect the handle later. A lost response may mean losing the handle to a tool that already acted. Do not blindly retry. Requires an active session created with enableWebMcp: true and an API key with browser.sessions.update permission.

## Path parameters

- `id` string, uuid, required

## Request body

- WebMCPStartParams
  - `toolRef` string, required
  - `input` object: Arguments matching the tool inputSchema. At most 1 MiB when JSON encoded. Keys are passed through unchanged.
  - `timeoutSeconds` integer: Tool execution budget in seconds. Expiration requests cancellation; it does not guarantee rollback.

## Response `202`

Invocation accepted

- WebMCPInvocation: Ephemeral, session-local handle. Pending states have no result or error. A terminal handle may contain a result or an error. Lost on receiver restart, session rebind, or browser shutdown. At most 16 active and 64 retained; terminal results expire after 10 minutes and may be evicted sooner.
  - `invocationId` string, required
  - `toolRef` string, required
  - `status` 'running' | 'awaiting_submission' | 'completed' | 'error' | 'canceled' | 'outcome_unknown', required
  - `cancellationRequested` boolean, required: Whether cancellation was requested, regardless of the final outcome.
  - `createdAt` string, date-time, required
  - `expiresAt` string, date-time: Nominal terminal-result expiry. Results may be evicted earlier.
  - `result` WebMCPInvokeResult
    - `invocationId` string: Handle for subsequent result reads or cancellation, when provided.
    - `status` 'completed' | 'error' | 'canceled' | 'awaiting_submission', required
    - `output` unknown
    - `errorText` string
    - `outputBytes` integer, required: Byte length of the original JSON output.
    - `outputTruncated` boolean: True when output exceeds 1 MiB. Full output is withheld.
    - `outputPreview` string: At most 4096 UTF-8 bytes of the oversized output; may be incomplete JSON.
    - `untrustedContent` boolean, required
    - `durationMs` integer, required
  - `error` WebMCPInvocationError
    - `code` string, required
    - `message` string, required

## Other responses

- `400`: Invalid request or tool reference.
- `401`: Authentication required.
- `403`: Insufficient API key permission.
- `404`: Session, tool, or invocation not found. Expired handles return invocation_not_found.
- `409`: Session is stopped, unavailable, or was not created with WebMCP enabled.
- `413`: Tool input exceeds 1 MiB (input_too_large).
- `429`: Rate limit reached; too_many_invocations indicates 16 active invocations.
- `500`: Internal server error.
- `502`: WebMCP service unavailable.
- `504`: Request timed out. For invocation requests, outcome_unknown means the tool may have acted.

## Changes

- **2026-10-11** `6bf1269eede9`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/hyperbrowser/apis/hyperbrowser-api/changes/api/session/:id/webmcp/invocations/post.md)

---

[API](https://skmtc.dev/hyperbrowser/apis/hyperbrowser-api.md) - [All operations](https://skmtc.dev/hyperbrowser/apis/hyperbrowser-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hyperbrowser/apis/hyperbrowser-api/revisions/ef089024c533?raw)