API Documentation - RevRag.ai

Base URLs

Production: https://api.revrag.ai
Staging: https://staging-api.revrag.ai

Authentication

All API requests require an API key to be included in the request headers:

X-API-Key: YOUR_API_KEY

Single Trigger APIs

🚀 Quick Start: Want to test these APIs immediately? Check out our Postman Collection with all endpoints pre-configured and ready to import!

1. Get All Agents

GET /v1/campaigns/agents Get All Agents

Header Parameters

Parameter	Type	Required	Description
`X-API-Key`	string	Yes	API Key for authentication

Response

Success (200 OK)

[
  {
    "id": "agent_123e4567-e89b-12d3-a456-426614174000",
    "name": "customer-support-agent",
    "variables": [
      {
        "name": "customer_name",
        "type": "string",
        "default_value": null
      }
    ]
  }
]

cURL Example

curl -X GET "https://staging-api.revrag.ai/v1/campaigns/agents" \
  -H "X-API-Key: YOUR_API_KEY"

2. Trigger Single Call

POST /v1/campaigns/trigger/single Trigger a single AI call for testing purposes.

Header Parameters

Parameter	Type	Required	Description
`X-API-Key`	string	Yes	API Key for authentication

Request Body

{
  "agent_id": "agent_123e4567-e89b-12d3-a456-426614174000",
  "to_phone_number": "+1234567890",
  "variable_fields": {
    "first_name": "John",
    "company": "Acme Inc."
  },
  "custom_metadata": {
    "campaign_type": "follow_up",
    "source": "web_form",
    "priority": "high"
  }
}

Request Parameters

Parameter	Type	Required	Description
`agent_id`	string (uuid)	Yes	The ID of the agent
`to_phone_number`	string	Yes	Recipient phone number
`variable_fields`	object or null	No	Variable fields for the call
`custom_metadata`	object or null	No	Custom metadata fields for tracking and organization. This field is flexible and can accept any key-value pairs

Response

Success (200 OK)

{
  "success": true,
  "message": "Call triggered successfully",
  "to_phone_number": "+1234567890",
  "agent_id": "agent_123e4567-e89b-12d3-a456-426614174000",
  "call_id": "call_456e7890-f12c-34d5-b678-901234567890"
}

cURL Example

curl -X POST "https://staging-api.revrag.ai/v1/campaigns/trigger/single" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_123e4567-e89b-12d3-a456-426614174000",
    "to_phone_number": "+1234567890",
    "variable_fields": {
      "first_name": "John",
      "company": "Acme Inc."
    },
    "custom_metadata": {
      "campaign_type": "follow_up",
      "source": "web_form",
      "priority": "high"
    }
  }'

Validation Error (422)

{
  "detail": [
    {
      "loc": ["body", "to_phone_number"],
      "msg": "Invalid phone number format",
      "type": "value_error"
    }
  ]
}

3. Get Call Status

GET /v1/campaigns/trigger/status/{call_id} Get the status of a specific call by its call_id.

Path Parameters

Parameter	Type	Required	Description
`call_id`	string (uuid)	Yes	The ID of the call

Header Parameters

Parameter	Type	Required	Description
`X-API-Key`	string	Yes	API Key for authentication

Response

Success (200 OK)

{
  "call_status": "ENDED",
  "call_id": "call_123e4567-e89b-12d3-a456-426614174000",
  "agent_id": "agent_456e7890-f12c-34d5-b678-901234567890",
  "from_number": "+918045342561",
  "to_number": "+1234567890",
  "summary": "Customer inquired about pricing options for our services. Discussed various pricing tiers and provided information about premium features. Customer showed interest in upgrading their current plan.",
  "start_time": "2024-01-15T10:00:00.000000",
  "end_time": "2024-01-15T10:15:30.500000",
  "duration": 930.5,
  "disconnection_reason": "USER_HANGUP",
  "recording_url": "https://cdn.revrag.ai/voice/recordings/room_abc123def456/room_abc123def456_audio.mp4",
  "transcription": {
    "messages": [
      {
        "role": "assistant",
        "content": "Hello, this is Sarah from Customer Support. Am I speaking with John?",
        "timestamp": "2024-01-15T10:00:15.000000+00:00"
      },
      {
        "role": "user",
        "content": "Yes, this is John speaking.",
        "timestamp": "2024-01-15T10:00:25.000000+00:00"
      },
      {
        "role": "assistant",
        "content": "Great! I'm calling to follow up on your recent inquiry about our services.",
        "timestamp": "2024-01-15T10:00:35.000000+00:00"
      },
      {
        "role": "user",
        "content": "Yes, I was interested in learning more about the pricing options.",
        "timestamp": "2024-01-15T10:00:50.000000+00:00"
      }
    ]
  },
  "custom_variables": [
    {
      "key": "customer_tier",
      "description": "Customer subscription tier level",
      "value": "premium",
      "type": "string"
    },
    {
      "key": "account_balance",
      "description": "Current account balance in USD",
      "value": 1250.75,
      "type": "number"
    },
    {
      "key": "is_first_time_caller",
      "description": "Whether this is the customer's first call",
      "value": false,
      "type": "boolean"
    }
  ],
  "variable_fields": {
    "first_name": "John",
    "company": "Acme Inc."
  },
  "custom_metadata": {
    "campaign_type": "follow_up",
    "source": "web_form",
    "priority": "high"
  }
}

Response Parameters

Parameter	Type	Description
`call_status`	string	Current status of the call (QUEUED, RUNNING, or ENDED)
`call_id`	string (uuid)	Unique identifier for the call
`agent_id`	string (uuid)	ID of the agent used for this call
`from_number`	string	Phone number from which the call was made
`to_number`	string	Phone number to which the call was made
`summary`	string	AI-generated summary of the call conversation
`start_time`	string	ISO 8601 timestamp when the call started
`end_time`	string	ISO 8601 timestamp when the call ended
`duration`	number	Call duration in seconds
`disconnection_reason`	string	Reason why the call ended (see Disconnection Reason Values)
`recording_url`	string	URL to the call recording (MP4 format)
`transcription`	object	Full transcription of the call with messages and timestamps
`custom_variables`	array	AI-extracted variables from the conversation during the call
`variable_fields`	object or null	The original variable fields that were passed when triggering the call
`custom_metadata`	object or null	The original custom metadata that was passed when triggering the call

cURL Example

curl -X GET "https://staging-api.revrag.ai/v1/campaigns/trigger/status/call_123e4567-e89b-12d3-a456-426614174000" \
  -H "X-API-Key: YOUR_API_KEY"

4. Webhook Notifications (Optional)

Instead of polling the call status endpoint, you can configure a webhook URL to receive real-time call completion notifications. When a call ends, we’ll automatically send the same response body structure as the “Get Call Status” API to your webhook endpoint.

Webhook Configuration

Contact our support team at contact@revrag.ai to configure your webhook URL.

Webhook Payload

The webhook will receive a POST request with the same JSON structure as the call status response, including the original variable_fields and custom_metadata that were passed when the call was triggered:

{
  "call_status": "ENDED",
  "call_id": "call_123e4567-e89b-12d3-a456-426614174000",
  "agent_id": "agent_456e7890-f12c-34d5-b678-901234567890",
  "from_number": "+918045342561",
  "to_number": "+1234567890",
  "summary": "Customer inquired about pricing options for our services. Discussed various pricing tiers and provided information about premium features. Customer showed interest in upgrading their current plan.",
  "start_time": "2024-01-15T10:00:00.000000",
  "end_time": "2024-01-15T10:15:30.500000",
  "duration": 930.5,
  "disconnection_reason": "USER_HANGUP",
  "recording_url": "https://cdn.revrag.ai/voice/recordings/room_abc123def456/room_abc123def456_audio.mp4",
  "transcription": {
    "messages": [
      {
        "role": "assistant",
        "content": "Hello, this is Sarah from Customer Support. Am I speaking with John?",
        "timestamp": "2024-01-15T10:00:15.000000+00:00"
      },
      {
        "role": "user",
        "content": "Yes, this is John speaking.",
        "timestamp": "2024-01-15T10:00:25.000000+00:00"
      }
    ]
  },
  "custom_variables": [
    {
      "key": "customer_tier",
      "description": "Customer subscription tier level",
      "value": "premium",
      "type": "string"
    },
    {
      "key": "account_balance",
      "description": "Current account balance in USD",
      "value": 1250.75,
      "type": "number"
    },
    {
      "key": "is_first_time_caller",
      "description": "Whether this is the customer's first call",
      "value": false,
      "type": "boolean"
    }
  ],
  "variable_fields": {
    "first_name": "John",
    "company": "Acme Inc."
  },
  "custom_metadata": {
    "campaign_type": "follow_up",
    "source": "web_form",
    "priority": "high"
  }
}

Bulk Campaign Management APIs

5. Create Campaign

POST /v1/campaigns Creates a campaign linked to an AI agent.

Header Parameters

Parameter	Type	Required	Description
`X-API-Key`	string	Yes	API key issued to the client
`Content-Type`	string	Yes	Must be `application/json`

Request Body

{
  "agent_id": "agent_abc123def456",
  "campaign_name": "Q4_Onboarding_Dropouts",
  "description": "Re-engage users who dropped during onboarding.",
  "metadata": {
    "campaign_type": "winback",
    "target_audience": "onboarding_dropouts",
    "created_by": "ops@example.com"
  }
}

Request Parameters

Parameter	Type	Required	Description
`agent_id`	string	Yes	ID of the AI agent to associate with this campaign
`campaign_name`	string	Yes	Unique name for the campaign (unique per tenant)
`description`	string	No	Description of the campaign purpose
`metadata`	object	No	Free-form key/value metadata for the campaign

Response

Success (201 Created)

{
  "success": true,
  "campaign_id": "cmp_abc123def456",
  "campaign_name": "Q4_Onboarding_Dropouts",
  "agent_id": "agent_abc123def456",
  "status": "active",
  "created_at": "2024-01-15T10:30:00Z"
}

6. Get Campaign

GET /v1/campaigns/{campaign_id} Fetch metadata and current counters for a campaign.

Path Parameters

Parameter	Type	Required	Description
`campaign_id`	string	Yes	The campaign ID to retrieve

Header Parameters

Parameter	Type	Required	Description
`X-API-Key`	string	Yes	API key issued to the client

Response

Success (200 OK)

{
  "campaign_id": "cmp_abc123def456",
  "campaign_name": "Q4_Onboarding_Dropouts",
  "agent_id": "agent_abc123def456",
  "status": "active",
  "created_at": "2024-01-15T10:30:00Z",
  "metadata": {
    "campaign_type": "winback",
    "target_audience": "onboarding_dropouts",
    "created_by": "ops@example.com"
  },
  "stats": {
    "total_records": 500,
    "accepted_records": 480,
    "rejected_records": 20
  }
}

7. Ingest Records (Data Intake)

POST /v1/campaigns/{campaign_id}/ingress Ingest flat, uniform-schema records for AI calling. Records can be JSON array items or CSV rows. All records in a batch must share the same flat set of keys.

Path Parameters

Parameter	Type	Required	Description
`campaign_id`	string	Yes	The campaign ID to ingest data into

Header Parameters

Parameter	Type	Required	Description
`X-API-Key`	string	Yes	API key issued to the client
`Content-Type`	string	Yes	Either `application/json` or `text/csv`

Request Body (JSON Format)

An array of flat objects; keys must match across all objects. Values must be primitives (string, number, boolean, null).

[
  {
    "phone_number": "<Encrypted Phone Number>",
    "orgId": 12345,
    "encryptedAESKey": "<Encrypted AES Key>",
    "customer_name": "John Doe",
    "priority": 5
  },
  {
    "phone_number": "<Encrypted Phone Number>",
    "orgId": 12345,
    "encryptedAESKey": "<Encrypted AES Key>",
    "customer_name": "Jane Smith",
    "priority": 1
  }
]

Request Body (CSV Format)

First row defines the columns; each row must have the same number of columns.

phone_number,orgId,encryptedAESKey,customer_name,priority
<encrypted>,12345,<encrypted>,John Doe,5
<encrypted>,12345,<encrypted>,Jane Smith,1

Validation Rules

Flat only - Values must be primitives (string, number, boolean, null). Arrays/objects are rejected
Uniform keys - First object (or CSV header) defines the schema; all rows must match exactly
Consistent types - Each field’s type must be consistent across the batch
Limits (defaults; per-tenant configurable):
- Max rows per request: 10,000
- Max JSON payload: 20 MB
- Max CSV payload: 50 MB
Timestamps - If present, must be ISO-8601 (e.g., 2024-01-04T10:00:00Z)
Optional uniqueness - If enabled per tenant, fields like phone_number must be unique per day or campaign

Response

Success (201 Created) - All records accepted

{
  "status": "success",
  "message": "Records accepted.",
  "accepted_count": 2,
  "rejected_count": 0,
  "total_count": 502,
  "ingestion_id": "ing_5da3...",
  "request_id": "req_..."
}

Partial Success (207 Multi-Status)

{
  "status": "partial_success",
  "message": "Some records were rejected.",
  "accepted_count": 40,
  "rejected_count": 10,
  "errors": [
    {
      "row": 7,
      "code": "schema.mismatch_type",
      "field": "priority",
      "expected": "number",
      "actual": "string",
      "message": "Expected number for 'priority'"
    },
    {
      "row": 12,
      "code": "schema.unexpected_field",
      "field": "extra_col",
      "message": "Field not present in first object/header"
    },
    {
      "row": 21,
      "code": "uniqueness.violation",
      "field": "phone_number",
      "message": "Phone number must be unique in today's dataset"
    }
  ],
  "ingestion_id": "ing_...",
  "request_id": "req_..."
}

Error Response (400 Bad Request)

{
  "error": {
    "code": "schema.invalid",
    "message": "Records must share an identical, flat schema.",
    "details": [
      {
        "row": 1,
        "field": "customer_phone",
        "issue": "missing_field"
      },
      {
        "row": 3,
        "field": "address",
        "issue": "nested_object_not_allowed"
      }
    ]
  },
  "request_id": "req_..."
}

Call Status Values

Status	Description
`QUEUED`	Call is queued for execution
`RUNNING`	Call is currently in progress
`ENDED`	Call has ended

Disconnection Reason Values

When a call ends, the disconnection_reason field indicates why the call was terminated:

Reason	Description
`USER_HANGUP`	The callee hung up the call
`USER_REJECTED`	Callee rejected the call (busy)
`MAX_DURATION`	The set maximum call duration was reached
`VOICEMAIL_REACHED`	Voicemail was reached
`AGENT_HANGUP`	The agent ended the call as per prompt or upon detecting conversation completion
`SILENCE_TIMEOUT`	Callee was silent for longer than the configured silence timeout period
`CALL_NOT_PICKED`	Call was not picked up by the callee
`ERROR_OCCURRED`	An error occurred during the call
`CALL_NOT_CONNECTED`	Call was not connected due to Telephony Issue
`CALL_DROPPED`	Call was dropped in Between due to Network Issues

Support

If you encounter any issues or need assistance with the API, please contact our support team: Email: contact@revrag.ai Our team will respond to your inquiries and help resolve any technical issues you may experience while using the API.

Endpoints

Security

Testing Tools

Documentation Index

​Base URLs

​Authentication

​Single Trigger APIs

​1. Get All Agents

​Header Parameters

​Response

​cURL Example

​2. Trigger Single Call

​Header Parameters

​Request Body

​Request Parameters

​Response

​cURL Example

​3. Get Call Status

​Path Parameters

​Header Parameters

​Response

​Response Parameters

​cURL Example

​4. Webhook Notifications (Optional)

​Webhook Configuration

​Webhook Payload

​Bulk Campaign Management APIs

​5. Create Campaign

​Header Parameters

​Request Body

​Request Parameters

​Response

​6. Get Campaign

​Path Parameters

​Header Parameters

​Response

​7. Ingest Records (Data Intake)

​Path Parameters

​Header Parameters

​Request Body (JSON Format)

​Request Body (CSV Format)

​Validation Rules

​Response

​Call Status Values

​Disconnection Reason Values

​Support

Base URLs

Authentication

Single Trigger APIs

1. Get All Agents

Header Parameters

Response

cURL Example

2. Trigger Single Call

Header Parameters

Request Body

Request Parameters

Response

cURL Example

3. Get Call Status

Path Parameters

Header Parameters

Response

Response Parameters

cURL Example

4. Webhook Notifications (Optional)

Webhook Configuration

Webhook Payload

Bulk Campaign Management APIs

5. Create Campaign

Header Parameters

Request Body

Request Parameters

Response

6. Get Campaign

Path Parameters

Header Parameters

Response

7. Ingest Records (Data Intake)

Path Parameters

Header Parameters

Request Body (JSON Format)

Request Body (CSV Format)

Validation Rules

Response

Call Status Values

Disconnection Reason Values

Support