> ## Documentation Index
> Fetch the complete documentation index at: https://docs.formation.texturehq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Web broker protocol

> A provider-neutral boundary for scoped web access without upstream credentials.

# Web broker protocol v1

A configured web broker supplies search, page reading and dedicated browser
sessions. The runtime receives a broker credential, never an upstream provider
credential. This contract is independent of any hosting operator or control plane.
Operators can also configure supported upstream providers directly.

## Trust and ownership

The broker authenticates its caller and derives its scope from the credential's
server-side record. Organization, instance, allowance and upstream account fields
supplied by a client cannot change that scope. Credentials are individually
revocable and can have a server-enforced expiry. Resource ownership survives credential rotation.

Every paid POST includes `X-Agent-Id`, a runtime agent UUID, and
`Idempotency-Key`, the persisted tool-call UUID. Browser reconnect and release
also require the matching agent ID; authenticated capability probes need neither. These are attribution within an
authenticated deployment, not authority to select a different deployment.
Browser sessions belong to that deployment and agent. Sessions cannot be listed
globally or attached by another agent. Website cookies, logins and profiles remain
agent-owned; a shared payer connection grants no website acting identity.

The broker reserves its maximum admitted usage before contacting a provider.
Reservations and concurrency accounting survive process replacement and cannot
be reset by changing credentials. Denied work makes no provider call. Browser
lifetimes are enforced independently of the runtime and its WebSocket connection.
Expired or revoked credentials cannot start or continue work. Cleanup continues
when admission is disabled. Uncertain provider outcomes are not replayed blindly.

## Transport

The configured endpoint is an HTTPS origin without credentials, query or fragment.
Clients never follow redirects carrying a credential. All HTTP responses use
`Cache-Control: no-store`. Errors contain a stable machine code and request ID;
upstream errors, credentials, account IDs and connection URLs are not returned.
Runtime notices to people are composed by a model from verified facts.

Requests use `Authorization: Bearer <broker credential>`. JSON bodies are bounded
and validated; unknown fields are rejected. The same idempotency key with a
different request is a conflict, including after a timeout. Provider responses
are normalized and bounded before returning them. Content, cookies, CDP messages
and credentials must not enter operational logs.

## Operations

| Method and path | Request | Response |
| - | - | - |
| `GET /v1/capabilities` | Authentication | Enabled `operations` (`search`, `read`, `browser`) and `max_lifetime_seconds`; no upstream identifiers. |
| `POST /v1/search` | `query`, `limit` | `results` containing `title`, public `url`, `excerpt`, optional `date`. |
| `POST /v1/read` | public `url`, `max_bytes` | `requested_url`, `title`, `content`, `retrieved_at`, `truncated`. |
| `POST /v1/browser/sessions` | `allowed_domains`, `lifetime_seconds` | Opaque UUID `id`, `expires_at`. |
| `GET /v1/browser/sessions/{id}/cdp` | Authenticated WebSocket upgrade, matching `X-Agent-Id` | CDP for this dedicated browser only. |
| `DELETE /v1/browser/sessions/{id}` | Authentication, matching `X-Agent-Id` | Idempotent release of the owned session. |

The runtime constructs the WebSocket URL from its configured origin and the
returned opaque ID. The broker can shorten the requested lifetime to its limit;
the runtime persists that earlier expiry. A broker response cannot redirect browser credentials.
Provider session identifiers or capability URLs are not part of the protocol.
Provider-specific account/session management commands must not be reachable
through CDP. A session is a dedicated browser, not an unfiltered connection to a
browser containing other agents' contexts. Every reconnect rechecks ownership,
credential state and expiry. Disconnects do not renew the admitted lifetime.
After credential rotation, the runtime can reconnect to its owned session using
the current credential at the same configured origin. It never sends that new
credential to a session's previous origin when the configured service changes.

## Availability and operator configuration

A missing credential, unknown stop state, unavailable reservation store or
exhausted allowance fails closed. A capability probe must authenticate without
launching a browser or making a paid search. BYO provider connections remain
available independently of a broker. Runtime limits are additional protections;
the broker must enforce its own limits against an untrusted client.

Configure an origin and its scoped credential with `MESH_WEB_BROKER_URL` and
`MESH_WEB_BROKER_TOKEN`, or save a `broker` vendor connection in settings. In
automatic mode, stored operator accounts take precedence over environment
fallbacks. An agent can inherit the payer connection while retaining its own
website profile. Probes call only `/v1/capabilities` and incur no upstream usage.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.