Skip to main content
Bridge does not expose a public HTTP API today. The primary interface is the bridge CLI, which returns structured JSON on stdout and structured errors on stderr.

​
What counts as the Bridge API today

Bridge is programmable, but the integration surface is local and CLI-first. The Bridge API is best understood as:
  1. A CLI command surface
  2. A JSON output contract
  3. A provider model defined in bridge.yaml
This page gives you the mental model. The deeper reference lives in the pages it links to.

​
Command surface at a glance

Bridge currently exposes these user-facing commands:
CommandPurpose
bridge initCreate a bridge.yaml file
bridge connect <target> --as <name> [--type <provider>]Add a provider connection
bridge remove <name>Remove a provider
bridge statusShow health for configured providers
bridge ls --from <name>List files, directories, tables, or other entries
bridge read <path> --from <name> [--limit <n>]Read structured context from a provider. For whole-table Postgres reads, --limit controls the row cap and falls back to 100 when omitted.
See Commands for syntax, flags, examples, exit behavior, and command-specific caveats.

​
Output contract

Bridge is designed for agents, so successful commands return JSON on stdout and failures return JSON on stderr.

​
Successful output

The most important response shape in Bridge is the result of bridge read. It returns a ContextValue object with:
  • data
  • metadata
{
  "data": {
    "type": "text",
    "content": "# Hello\n\nFile contents here."
  },
  "metadata": {
    "source": "filesystem",
    "path": "README.md",
    "content_type": "text/markdown",
    "size": 28
  }
}
The data.type field is one of:
  • text
  • json
  • binary
Binary data is returned as base64-encoded content.

​
Other successful responses

  • bridge ls returns an array of entries
  • bridge status returns a providers map keyed by provider name
  • bridge init, bridge connect, and bridge remove return small JSON status objects
See Commands for examples of each command’s output.

​
Errors

Bridge uses a consistent error envelope: 
{
  "error": {
    "code": "config_not_found",
    "message": "bridge.yaml not found. Run `bridge init` to create one."
  }
}
Common error codes include:
  • config_not_found
  • provider_not_found
  • provider_error
  • invalid_uri
  • env_var_not_set
  • timeout
See Security and errors for the full error catalog, exit-code behavior, and current safety model.

​
Provider model

Bridge resolves data through named providers in bridge.yaml. At a high level:
  1. you define a provider in bridge.yaml
  2. you choose a short name such as files or db
  3. you pass that name to --from
  4. Bridge routes the command to the right backend
Today, Bridge ships with:
  • a filesystem provider
  • a Postgres provider
The long-term design is provider-oriented, so new backends can be added without changing the agent-facing command model. See Configuration for the full bridge.yaml model, and Providers for the exact runtime behavior of each backend.

​
Authentication and access

Bridge does not have a global bearer-token authentication layer today because it is a local CLI, not a hosted API service. Access is currently controlled by the underlying provider:
  • filesystem access comes from the local machine and configured root path
  • database access comes from the connection URI and credentials you provide
  • secrets can be loaded through environment variables such as ${DATABASE_URL}
For safer setups, bridge connect DATABASE_URL --type postgres --as db writes ${DATABASE_URL} into bridge.yaml, and Bridge resolves the real value at runtime from the process environment.

​
How to use this section

If you are trying to:

​
What comes next

Bridge Cloud is the future hosted layer. The long-term direction is to let you publish permissioned context slices and grant access across agents, teams, and organizations without moving your underlying data into a separate storage system. Until that ships, the Bridge API is the CLI itself.

Commands

See the full CLI reference, including flags, examples, errors, and shell completions.

Configuration

Learn how provider names, URIs, and environment variable expansion work in bridge.yaml.

Providers

See what filesystem and postgres return for ls, read, and status.

Security and errors

Understand Bridge’s current guardrails, timeout behavior, and machine-readable failure model.

Bridge, MCP, and A2A

See where Bridge fits in the broader agent stack and how it complements MCP and A2A.