​
Overview

Relvy supports REST API integration as a data source, allowing AI agents to query external APIs during issue investigation and analysis. This feature enables dynamic data retrieval from your existing services and third-party APIs to provide comprehensive context for troubleshooting.
Security Recommendation - It is recommended to integrate APIs that are read-only to prevent unintended modifications during AI-driven investigations. If you must configure write operations (POST endpoints), ensure proper authentication, rate limiting, and careful consideration of the potential impact of automated API calls.

​
Core Concepts

​
REST API Groups

A REST API Group is a collection of related REST API endpoints that share common configuration such as:
  • Base URL
  • Authentication settings
  • Default headers
  • Timeout and retry configurations
  • Group-level variables
Think of an API group as a logical container for all endpoints from a specific service or API provider.

​
REST API Resources (Endpoints)

A REST API Resource represents a specific API endpoint within a group. Each resource defines:
  • HTTP method (GET or POST)
  • Endpoint path
  • Parameters
  • Request body (for POST requests)
  • Endpoint-specific variables

​
Variables

Variables are dynamic values that AI agents can populate when making API calls. There are two types:
  1. Group Variables: Shared across all endpoints in the group (e.g., user_id, tenant_id)
  2. Endpoint Variables: Specific to individual endpoints (e.g., order_id for an order details endpoint)
Variables are referenced using {{variable_name}} syntax in paths, parameters, and request bodies.

​
Setting Up REST API Integration

​
Creating a REST API Group

  1. Navigate to the configuration page
  2. Find the “Connect REST API” section
  3. Click “Add REST API Group”
  4. Fill in the required information:

​
Basic Configuration

  • Group Name: Descriptive name for your API group
  • Description: Context for AI agents about what this API provides
  • Base URL: The root URL for all endpoints (e.g., https://api.example.com/v1)

​
Authentication

Choose from the following authentication methods: No Authentication
  • Use when the API doesn’t require authentication
  • Suitable for public APIs
Basic Authentication
  • Provide username and password
  • Used for APIs requiring HTTP Basic Auth
Bearer Token
  • Provide an API token
  • Token is sent in the Authorization: Bearer <token> header

​
Optional Configuration

Default Headers 
{
  "Content-Type": "application/json",
  "Accept": "application/json"
}
Timeout Settings
  • Request timeout in seconds (default: 30)
  • Number of retry attempts for failed requests (default: 3)

​
Group Variables

Define reusable variables that can be used across all endpoints in this group:
  • Name: Variable identifier (e.g., user_id)
  • Description: What this variable represents
  • Default Value: Optional default value
  • Example Value: Example for testing and AI understanding

​
Creating REST API Resources

After creating a group, add specific endpoints:
  1. Navigate to the “API Endpoints” section
  2. Click the + button to add a new endpoint
  3. Configure the endpoint details:

​
Endpoint Configuration

Basic Details
  • Endpoint Name: Descriptive name (e.g., “Get User Profile”)
  • HTTP Method: GET or POST
  • Endpoint Path: Path relative to base URL (e.g., /users/{{user_id}})
  • Description: What this endpoint does and what data it returns
Endpoint Variables (Optional) Define variables specific to this endpoint that aren’t covered by group variables. Parameters (Optional) For query parameters, headers, or other request parameters:
  • Name: Parameter name
  • Value: Static value or variable reference using {{variable_name}}
  • Default Value: Optional default
  • Example Value: For testing and documentation
Request Body (POST only) For POST requests, define the request body template: 
{
  "user_id": "{{user_id}}",
  "action": "update_profile",
  "data": {
    "name": "{{user_name}}",
    "email": "{{user_email}}"
  }
}

​
Supported HTTP Methods

​
GET Requests

GET requests are used for data retrieval. They support:
  • Path variables: /users/{{user_id}}/orders/{{order_id}}
  • Query parameters: ?status={{status}}&limit={{limit}}
  • Custom headers
Example GET endpoint: 
GET https://api.example.com/v1/users/{{user_id}}/orders

​
POST Requests

POST requests are used for data submission and actions. They support:
  • Path variables
  • Query parameters
  • Custom headers
  • JSON request body with variable substitution
Example POST endpoint: 
POST https://api.example.com/v1/users/{{user_id}}/orders
Content-Type: application/json

{
  "product_id": "{{product_id}}",
  "quantity": {{quantity}},
  "notes": "{{order_notes}}"
}

​
Variable System

​
Variable Usage

Variables can be used in: URL Paths 
/api/users/{{user_id}}/orders/{{order_id}}
Query Parameters 
?status={{order_status}}&created_after={{start_date}}
Request Body (POST) 
{
  "user_id": "{{user_id}}",
  "metadata": {{metadata_object}},
  "tags": {{tag_array}}
}

​
Testing REST API Endpoints

Each configured endpoint can be tested directly from the UI:
  1. Click the play button (▶) next to an endpoint
  2. Fill in values for any required variables
  3. Click “Test Endpoint”
  4. Review the response to ensure proper configuration
You will see the HTTP status code, Response headers, Response body or any errors that occurred

​
AI Integration

​
How AI Uses REST APIs

When investigating issues, AI agents can:
  1. Identify Relevant APIs: Based on context and configured descriptions
  2. Determine Variable Values: Extract values from logs, metrics, or user input
  3. Execute API Calls: Make requests with appropriate variable substitution
  4. Analyze Responses: Incorporate API data into investigation results

​
Best Practices for AI Integration

Descriptive Naming
  • Use clear, descriptive names for groups and endpoints
  • Include context about what data the API provides
Comprehensive Descriptions
  • Explain what each endpoint does
  • Describe the type of data returned
  • Include when this API should be used
Meaningful Variables
  • Use descriptive variable names (user_id vs id)
  • Provide clear descriptions for each variable
  • Include example values

​
Example Configuration

​
E-commerce API Group

Group Configuration: 
Name: E-commerce User API
Description: Retrieves user account and order information from our e-commerce platform
Base URL: https://api.shop.example.com/v2
Auth: Bearer Token
Variables:
  - user_id: string, "Unique user identifier"
  - tenant_id: string, "Organization tenant ID"
Endpoints:
  1. Get User Profile 
    GET /users/{{user_id}}
Description: Retrieves complete user profile including account status and preferences
  2. Get User Orders 
    GET /users/{{user_id}}/orders?status={{order_status}}
Description: Retrieves user's order history with optional status filtering
Variables:
  - order_status: string, "Order status filter (pending, completed, cancelled)"