> ## Documentation Index > Fetch the complete documentation index at: https://hyperbrowser.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Start a WebMCP invocation > Start once and return a handle without waiting for completion. See the [WebMCP guide](/docs/sessions/webmcp) for SDK examples and invocation lifecycle details. ## OpenAPI ````yaml openapi.json POST /api/session/{id}/webmcp/invocations openapi: 3.0.1 info: title: Hyperbrowser API version: 1.0.0 servers: - url: https://api.hyperbrowser.ai description: Production server security: [] paths: /api/session/{id}/webmcp/invocations: post: summary: Start a WebMCP invocation description: >- 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. operationId: startWebmcpInvocation parameters: - name: id in: path required: true schema: type: string format: uuid description: Session ID. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WebMCPStartParams' responses: '202': description: Invocation accepted content: application/json: schema: $ref: '#/components/schemas/WebMCPInvocation' '400': description: Invalid request or tool reference. content: application/json: schema: $ref: '#/components/schemas/WebMCPErrorResponse' '401': description: Authentication required. content: application/json: schema: $ref: '#/components/schemas/WebMCPErrorResponse' '403': description: Insufficient API key permission. content: application/json: schema: $ref: '#/components/schemas/WebMCPErrorResponse' '404': description: >- Session, tool, or invocation not found. Expired handles return invocation_not_found. content: application/json: schema: $ref: '#/components/schemas/WebMCPErrorResponse' '409': description: >- Session is stopped, unavailable, or was not created with WebMCP enabled. content: application/json: schema: $ref: '#/components/schemas/WebMCPErrorResponse' '413': description: Tool input exceeds 1 MiB (input_too_large). content: application/json: schema: $ref: '#/components/schemas/WebMCPErrorResponse' '429': description: >- Rate limit reached; too_many_invocations indicates 16 active invocations. content: application/json: schema: $ref: '#/components/schemas/WebMCPErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/WebMCPErrorResponse' '502': description: WebMCP service unavailable. content: application/json: schema: $ref: '#/components/schemas/WebMCPErrorResponse' '504': description: >- Request timed out. For invocation requests, outcome_unknown means the tool may have acted. content: application/json: schema: $ref: '#/components/schemas/WebMCPErrorResponse' security: - ApiKeyAuth: [] x-codeSamples: - lang: javascript label: Node.js source: |- import { Hyperbrowser } from "@hyperbrowser/sdk"; const client = new Hyperbrowser(); const result = await client.sessions.webmcp.start("session-id", { toolRef: "tool-ref-from-discovery", input: {}, // Match the selected tool inputSchema. timeoutSeconds: 300, }); - lang: python label: Python source: |- from hyperbrowser import Hyperbrowser client = Hyperbrowser() result = client.sessions.webmcp.start("session-id", { "tool_ref": "tool-ref-from-discovery", "input": {}, # Match the selected tool input_schema. "timeout_seconds": 300, }) components: schemas: WebMCPStartParams: type: object properties: toolRef: type: string minLength: 1 maxLength: 4096 input: type: object additionalProperties: true default: {} description: >- Arguments matching the tool inputSchema. At most 1 MiB when JSON encoded. Keys are passed through unchanged. timeoutSeconds: type: integer minimum: 1 maximum: 3600 default: 300 description: >- Tool execution budget in seconds. Expiration requests cancellation; it does not guarantee rollback. required: - toolRef additionalProperties: false WebMCPInvocation: type: object properties: invocationId: type: string pattern: ^[a-f0-9]{24}$ toolRef: type: string status: type: string enum: - running - awaiting_submission - completed - error - canceled - outcome_unknown cancellationRequested: type: boolean description: Whether cancellation was requested, regardless of the final outcome. createdAt: type: string format: date-time expiresAt: type: string description: Nominal terminal-result expiry. Results may be evicted earlier. format: date-time result: $ref: '#/components/schemas/WebMCPInvokeResult' error: $ref: '#/components/schemas/WebMCPInvocationError' required: - invocationId - toolRef - status - cancellationRequested - createdAt description: >- 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. WebMCPErrorResponse: type: object properties: message: type: string error: type: string code: type: string invocationId: type: string description: >- HTTP failure. Structured WebMCP errors include message and code; other session or validation errors may only include error or message. An outcome_unknown error may include an invocationId for later retrieval. WebMCPInvokeResult: type: object properties: invocationId: type: string description: Handle for subsequent result reads or cancellation, when provided. status: type: string enum: - completed - error - canceled - awaiting_submission output: description: >- Any JSON value returned by the page, including null. Absent if unavailable or withheld for exceeding the output limit. errorText: type: string outputBytes: type: integer minimum: 0 description: Byte length of the original JSON output. outputTruncated: type: boolean description: True when output exceeds 1 MiB. Full output is withheld. outputPreview: type: string description: >- At most 4096 UTF-8 bytes of the oversized output; may be incomplete JSON. untrustedContent: type: boolean durationMs: type: integer minimum: 0 required: - status - outputBytes - untrustedContent - durationMs WebMCPInvocationError: type: object properties: code: type: string message: type: string required: - code - message securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.