Sources

REST API Connections

Connect any HTTP REST API to Agently. Define endpoints, authentication, and let your agent query or trigger actions on external services.

Overview

REST API sources let you describe an external HTTP API — its base URL, authentication method, and individual endpoints. Agently exposes each endpoint as a callable tool for the agent.

This is useful for services that don't have a native MCP server: internal APIs, custom webhooks, SaaS products with REST APIs, and more.

Authentication Methods

Bearer Token

Adds an Authorization: Bearer <token> header to every request. Common for JWTs and OAuth access tokens.

{
  "auth": {
    "type": "bearer",
    "token": "eyJhbGciOiJIUzI1NiIs..."
  }
}

API Key (Header)

Injects a custom header (e.g. X-API-Key) with your key.

{
  "auth": {
    "type": "api-key",
    "header": "X-API-Key",
    "key": "sk-abc123"
  }
}

API Key (Query Param)

Appends an API key as a URL query parameter.

{
  "auth": {
    "type": "query-param",
    "param": "api_key",
    "key": "abc123"
  }
}

Basic Auth

Standard HTTP Basic authentication with username and password.

{
  "auth": {
    "type": "basic",
    "username": "user",
    "password": "pass"
  }
}

Defining Endpoints

Each endpoint you define becomes a tool the agent can call. Provide a clear description so the agent knows when to use it.

{
  "name": "My API",
  "baseUrl": "https://api.example.com/v1",
  "auth": {
    "type": "bearer",
    "token": "YOUR_TOKEN"
  },
  "endpoints": [
    {
      "id": "list-items",
      "method": "GET",
      "path": "/items",
      "description": "List all items in the account",
      "params": {
        "query": {
          "limit": { "type": "number", "description": "Max items to return" },
          "offset": { "type": "number", "description": "Pagination offset" }
        }
      }
    },
    {
      "id": "create-item",
      "method": "POST",
      "path": "/items",
      "description": "Create a new item",
      "body": {
        "name": { "type": "string", "required": true },
        "tags": { "type": "array", "items": { "type": "string" } }
      }
    }
  ]
}

Security Considerations

API credentials are stored in the system keychain and are never transmitted to Agently's servers.

Use read-only API keys wherever possible
Use Ask to Edit permission mode to approve write operations before they execute
Rotate keys regularly and use scoped tokens when your provider supports it

Example: Connecting a Custom Webhook

Here's how to set up a simple webhook endpoint so your agent can trigger an action in your system (e.g., creating a task in a custom project management tool):

1.Go to Settings → Sources → Add Source → REST API.
2.Set Base URL to your webhook host, e.g. https://hooks.yourapp.com.
3.Add an endpoint with method POST and a clear description like "Create a task with title and priority".
4.Save and test the connection. The agent can now create tasks on your behalf when instructed.