Overview

Connect to any REST API with flexible HTTP tools

Just ask your agent. The easiest way to connect APIs is to tell your agent what you need:

• “Connect to the JSONPlaceholder API”
• “Add access to my company’s internal API”
• “Set up the weather API with my API key”

The agent handles configuration, credentials, and validation automatically.

API sources provide a flexible HTTP tool that lets your agents connect to virtually any REST API. If a service has an API, your agent can use it - no MCP server required.

How It Works#

When you configure an API source, xiantong:

1. Creates a flexible HTTP tool for making requests
2. Handles auth by securely storing and injecting credentials
3. Validates the connection using the test endpoint
4. Enables the agent to make any request to the API’s base URL

The result: your agent can call any endpoint on the configured API.

Configuration#

API sources are configured with a JSON file:

{
"type": "api",
"name": "My API",
"tagline": "Description of the API",
"icon": "https://example.com/icon.png",
"api": {
"baseUrl": "https://api.example.com/",
"testEndpoint": {
"method": "GET",
"path": "health"
},
"authType": "bearer"
}
}

Configuration Fields#

Authentication Types#

API sources support six authentication methods:

Bearer Token#

{
"api": {
"baseUrl": "https://api.example.com",
"authType": "bearer"
}
}

Sends credentials as Authorization: Bearer {token}.

Header Authentication#

{
"api": {
"baseUrl": "https://api.example.com",
"authType": "header",
"headerName": "X-API-Key"
}
}

Sends credentials in a custom header: X-API-Key: {token}.

Query Parameter Authentication#

{
"api": {
"baseUrl": "https://api.example.com",
"authType": "query",
"queryParam": "api_key"
}
}

Appends credentials as a query parameter: ?api_key={token}.

OAuth 2.0#

Two modes: auto-discovery (simplest) and explicit config (for providers without standard metadata).

Auto-discovery (recommended)

If the API supports RFC 9728 (OAuth Protected Resource Metadata), just set authType — endpoints and client registration are handled automatically:

{
"api": {
"baseUrl": "https://api.example.com/v1/",
"authType": "oauth"
}
}

xiantong will hit the base URL, read the WWW-Authenticate header, discover OAuth metadata, dynamically register a client, and start the authorization flow. No oauth config block needed.

Explicit config

For providers that don’t expose standard OAuth metadata (e.g. GitHub, Linear), provide the endpoints manually:

{
"api": {
"baseUrl": "https://api.github.com/",
"authType": "oauth",
"oauth": {
"authorizationUrl": "https://github.com/login/oauth/authorize",
"tokenUrl": "https://github.com/login/oauth/access_token",
"clientId": "your_client_id",
"clientSecret": "your_client_secret",
"scopes": ["repo", "read:user"]
}
}
}

Full OAuth 2.0 flow with PKCE in both modes. Tokens are automatically refreshed and sent as Authorization: Bearer {token}.

For Google, Microsoft, and Slack APIs, xiantong has built-in OAuth support with predefined scopes — you don’t need to configure the oauth block manually. Just set the appropriate provider field.

No Authentication#

{
"api": {
"baseUrl": "https://api.example.com",
"authType": "none"
}
}

For public APIs that don’t require authentication.

Basic Authentication#

{
"api": {
"baseUrl": "https://api.example.com",
"authType": "basic"
}
}

Sends credentials as Authorization: Basic {base64(username:password)}.

Multi-Header Authentication#

{
"api": {
"baseUrl": "https://api.example.com",
"authType": "header",
"headerNames": ["X-API-KEY", "X-APP-KEY"]
}
}

Sends multiple credentials as separate headers. Each header name in the array gets its own input field during authentication. All headers are included in every API request.

Use multi-header authentication when an API requires two or more authentication headers simultaneously. This is common for services that separate identity from authorization, or require both an API key and an application secret.

Common use cases:

• Datadog: DD-API-KEY + DD-APPLICATION-KEY
• APIs with identity + signing keys: Separate API key and secret
• Services with app + user credentials: Application key plus user token

Test Endpoint#

The testEndpoint field specifies an endpoint used to verify the connection works. When you test a source, xiantong makes a request to this endpoint to confirm:

• The base URL is reachable
• Authentication credentials are valid
• The API responds correctly

Common test endpoints:

Choose a lightweight endpoint that requires authentication. This validates both connectivity and credentials in one request.

Why Use API Sources?#

• Universal Compatibility

Any service with a REST API can be integrated.

• Simple Configuration

Just provide the base URL and auth details.

• Flexible Requests

The HTTP tool can make any request to the API.

• Secure Credentials

API keys are stored encrypted, not in config files.

Comparison: MCP vs API Sources#

Use MCP sources when available for richer integration with predefined tools. Use API sources for services without MCP support or when you need flexible HTTP access.

Need Google, Microsoft, or Slack? xiantong has built-in OAuth support for these services with predefined scopes. Just ask your agent to “connect Google Calendar” or “add Slack” and it will walk you through the OAuth flow.Need any other OAuth provider? Use authType: "oauth" with the oauth config block to connect GitHub, Linear, Notion, Spotify, or any other OAuth 2.0 service.

Next Steps#

Practical Examples#

Real-world examples of API source configurations.