Skip to main content
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, 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.

​
Configuration

An API source is defined by a config.json with type set to "api" and an api block describing the connection.
config.json
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.

​
Authentication methods

Set api.authType to match how the service expects credentials. Synti supports: The token, key, or username/password you supply is encrypted on disk—never stored in config.json. See MCP 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.
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.

​
Permissions

API calls that change state are gated by 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.