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

# REST API Sources

> Connect Synti's agent to any HTTP service by configuring a base URL and authentication method.

A REST API source lets Synti's agent talk to any HTTP-based service—a SaaS product, an internal microservice, or a custom backend you built yourself. You define the API's base URL and how to authenticate, and Synti gives the agent a flexible HTTP tool that can call any endpoint under that base. Unlike an [MCP server](/sources/mcp-servers/overview), which publishes a fixed set of tools, an API source trades pre-built structure for reach: if the service exposes it over HTTP, the agent can request it.

## When to use an API source

Reach for a REST API source when there is no MCP server for a service, when you control the backend, or when you simply want the agent to hit specific endpoints with your credentials attached. For a comparison across all three source kinds, see [Sources](/sources/overview).

## Configuration

An API source is defined by a `config.json` with `type` set to `"api"` and an `api` block describing the connection.

```json config.json theme={null}
{
  "type": "api",
  "name": "Example Service",
  "slug": "example-service",
  "enabled": true,
  "tagline": "Internal reporting API",
  "icon": "📊",
  "api": {
    "baseUrl": "https://api.example.com/v1",
    "authType": "bearer",
    "testEndpoint": "/me"
  }
}
```

| Field              | Required | Purpose                                                              |
| ------------------ | -------- | -------------------------------------------------------------------- |
| `type`             | Yes      | Must be `"api"`                                                      |
| `name`             | Yes      | Display name for the source                                          |
| `api.baseUrl`      | Yes      | Root URL prepended to every request                                  |
| `api.authType`     | Yes      | How requests are authenticated (see below)                           |
| `tagline`          | No       | Short description shown in the sources list                          |
| `icon`             | No       | Emoji, local path, or URL                                            |
| `api.testEndpoint` | No       | A lightweight endpoint used to validate connectivity and credentials |

<Tip>
  Pick a `testEndpoint` that requires authentication, responds quickly, and never changes data—`/me`, `/user`, `/health`, or something like `/items?limit=1`. Avoid endpoints that create, update, or delete records.
</Tip>

## Authentication methods

Set `api.authType` to match how the service expects credentials. Synti supports:

| `authType`     | How it authenticates                                                        |
| -------------- | --------------------------------------------------------------------------- |
| `bearer`       | Sends `Authorization: Bearer {token}`                                       |
| `header`       | Sends the key in a custom header, e.g. `X-API-Key`                          |
| `query`        | Appends the key as a URL query parameter                                    |
| `basic`        | Base64-encoded `username:password`                                          |
| `oauth`        | Full OAuth 2.0 with PKCE (see below)                                        |
| `multi-header` | Several headers at once, for services that split identity and authorization |
| `none`         | No credentials, for public APIs                                             |

The token, key, or username/password you supply is encrypted on disk—never stored in `config.json`. See [MCP authentication](/sources/mcp-servers/authentication) for how Synti scopes and secures credentials across all source kinds.

### OAuth 2.0

Synti runs the full OAuth 2.0 authorization-code flow with PKCE in two modes:

* **Auto-discovery (recommended).** Synti reads the service's `WWW-Authenticate` response header, discovers the OAuth endpoints per RFC 9728, and registers a client automatically—no manual endpoint entry.
* **Explicit configuration.** Provide the authorization URL, token URL, client ID and secret, and the scopes you need.

In both modes, Synti refreshes tokens automatically and sends them as `Authorization: Bearer {token}`. Built-in provider presets for Google, Microsoft, and Slack pre-fill their OAuth endpoints and common scopes to save setup time.

### Renewing non-OAuth tokens

Some APIs issue a bearer token that expires but is refreshed through a plain endpoint rather than OAuth. For these, add a `renewEndpoint` to the `api` block specifying the renewal path, HTTP method, and the JSON fields that carry the new token and its expiry. Synti then refreshes the token on its own, so the agent keeps working without you re-authenticating.

## How the agent calls the API

Once the source is connected, the agent can call any endpoint under `baseUrl`. Through the HTTP tool it chooses the method (GET, POST, PUT, DELETE, PATCH), the path, query parameters, and a request body. Bodies are sent as JSON by default; the tool also supports raw bodies for plain text, XML, and other content types.

<Note>
  The agent works best when it knows the shape of the API. Add a `guide.md` next to `config.json` describing the key endpoints, or paste the service's documentation into the conversation. For concrete, copy-ready setups, see [cURL examples](/sources/apis/curl-examples).
</Note>

## Permissions

API calls that change state are gated by [Permissions](/core-concepts/permissions)—the agent asks before running them unless you've granted broader access. To constrain what an API source may do, add a `permissions.json` scoped to that source.