> ## 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.

# REST API connections

> Connect an agent to an authenticated HTTP API without an MCP server.

REST API connections let an agent call a service's REST or GraphQL API using its
own account. Formation supplies authentication through a configured connection; the
agent refers to that connection's request tool and never supplies its token in
tool arguments.

## Connect an API

Open the agent's **Tools** page, choose **Add tool**, then **Custom REST API**.

1. Give the connection a recognizable name and its public HTTPS API base URL.
2. Enter a token for this agent's own service account.
3. Choose the authentication header and prefix. The defaults send
   `Authorization: Bearer <token>`. For an API using `X-API-Key: <token>`, set
   the header to `X-API-Key` and clear the prefix.
4. Add a description of the API's purpose and, optionally, a documentation URL.
5. Save the connection. It becomes available immediately; saving does not make
   an API request or prove that the service accepts the credential.

Each acting account belongs to one agent. Two agents may use the same API
endpoint through their own accounts. Infrastructure defaults and another
agent's credentials are never inherited by an API connection.

## What the agent sees

Each enabled connection contributes one authenticated request tool to normal
tool discovery. Its description identifies the connection, base URL, purpose,
and supplied documentation. The agent can search for it with `tool_search` and
send requests with a method, relative path, optional query parameters, headers,
and body. A GraphQL API uses the same tool with a POST body containing the query
and variables.

An arbitrary REST API does not advertise an MCP-style tool catalog. Formation does
not automatically discover endpoints, import OpenAPI schemas, or infer named
operations. Documentation and the connection description guide the agent's
requests. The documentation URL is a reference, not an instruction to fetch or
execute content during setup.

The connection's URL and configured authentication cannot be replaced by tool
arguments. Requests stay within its base path and use the token in its configured
header. A custom header/prefix supports API keys as well as bearer tokens;
OAuth refresh, request signing, query-string credentials, and cookie-based
authentication are outside this initial adapter.

## Credential and request boundaries

Tokens are encrypted in Formation's existing agent-owned secret store and covered by
master-key rotation. Operator reads return credential presence, never its value.
When editing, leaving the token blank preserves the saved value while the API
base URL is unchanged. Changing that destination requires entering the token
again. Disable a
connection to prevent subsequent requests, or delete it to remove the connection
and stored credential. Neither action revokes the token at the service.

A fixed HTTP worker executes each request in a separate process without the
installation master key, database credentials, or unrelated secrets. It receives
only the selected request and credential over a private input pipe. Tokens are
not delivered to workspaces or exposed as command arguments or environment
variables.

Only public HTTPS destinations on the default HTTPS port are supported. DNS is
checked immediately before dialing, environment proxies are ignored, and
redirects are not followed. Private-network APIs require a separately designed
trust policy. Request and response sizes and execution time are bounded.

Responses redact exact delivered credential values. This helps prevent
accidental reflection; it does not guarantee a remote service cannot encode a
credential into its response. The credential's service permissions determine
what the agent can do. A base URL restriction alone does not make an API read
only, and GraphQL queries and mutations can use the same POST endpoint.

All API requests are recorded as externally effectful and are not automatically
replayed after an uncertain outcome. They retain the triggering conversation's
source restrictions in the tool evidence ledger.

## Operator API

Use the existing [connection API](/runtime/connection-management.md). Create a
connection with `adapter: "http_api"` and `name`, `base_url`, `token`, optional
`auth_header`, `auth_prefix`, `description`, and `documentation_url`.

The managed connection has an `api` metadata object and supports `update`,
`enable`, `disable`, and `delete` actions. Updates require its current `version`.
An omitted prefix uses `Bearer` when creating a connection; an explicitly empty
prefix sends the raw token. A prefix containing words is separated from the
token by one space. API connections do not grant workspace credential delivery
or access to another agent's account.


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