API Reference

Hyperleap REST API

Build custom AI workflows with our RESTful API. Create agents, manage conversations, upload knowledge, and integrate with your existing systems.

Get API KeyView Endpoints
99.9%

API Uptime

<50ms

Avg Response Time

40+

API Endpoints

TLS 1.3

Encryption Standard

Authentication

Hyperleap uses API keys to authenticate requests. Include your API key in the Authorization header of every request.

Get Your API Key
Navigate to Settings → API Keys in your dashboard
Keep Keys Secret
Never expose API keys in client-side code or public repositories
Rotate Regularly
Rotate API keys every 90 days for enhanced security
Security Best Practice
Always use environment variables to store API keys. Never hardcode them in your application.
cURL
curl https://api.hyperleap.ai/v1/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

# Response:
{
  "data": [
    {
      "id": "agent_abc123",
      "name": "Support Bot",
      "model": "gemini-pro",
      "status": "active",
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 1,
    "page": 1,
    "per_page": 20
  }
}

API Endpoints

Complete reference for all available endpoints. Base URL: https://api.hyperleap.ai

Agents

GET/v1/agentsList all agents
POST/v1/agentsCreate a new agent
GET/v1/agents/{id}Get agent details
PATCH/v1/agents/{id}Update an agent
DELETE/v1/agents/{id}Delete an agent

Conversations

POST/v1/conversationsStart a new conversation
POST/v1/conversations/{id}/messagesSend a message
GET/v1/conversations/{id}Get conversation history
GET/v1/conversationsList all conversations

Knowledge Sources

POST/v1/sourcesUpload a knowledge source
GET/v1/sourcesList knowledge sources
GET/v1/sources/{id}Get source details
DELETE/v1/sources/{id}Delete a source

Webhooks

POST/v1/webhooksCreate a webhook
GET/v1/webhooksList webhooks
DELETE/v1/webhooks/{id}Delete a webhook
POST/v1/webhooks/{id}/testTest webhook delivery

Analytics

GET/v1/analytics/conversationsConversation metrics
GET/v1/analytics/agents/{id}Agent performance stats
GET/v1/analytics/usageAPI usage statistics
View Complete API Reference

Rate Limits

Rate limits are applied per API key and vary by subscription tier. Monitor your usage via the X-RateLimit-* response headers.

Plan TierHourly LimitBurst Limit
Free100/hour10/minute
Plus1,000/hour50/minute
Pro5,000/hour100/minute
Max20,000/hour500/minute
EnterpriseCustomCustom

Rate Limit Headers

X-RateLimit-Limit:Maximum requests per hour
X-RateLimit-Remaining:Requests remaining in current window
X-RateLimit-Reset:Unix timestamp when limit resets

Webhooks

Receive real-time notifications when events occur in your Hyperleap account. Perfect for triggering workflows, sending notifications, or logging activity.

Available Events

conversation.created
New conversation started
conversation.message
Message sent or received
conversation.completed
Conversation ended
agent.updated
Agent configuration changed
lead.captured
Lead information collected
booking.created
Appointment booked via agent
Webhook Security
All webhook payloads include an HMAC signature in the X-Hyperleap-Signature header for verification.
Webhook Payload
// POST to your endpoint
{
  "event": "conversation.message",
  "timestamp": "2025-01-15T14:30:00Z",
  "data": {
    "conversation_id": "conv_xyz789",
    "message_id": "msg_abc123",
    "sender": "user",
    "content": "What are your hours?",
    "agent_id": "agent_def456",
    "metadata": {
      "channel": "whatsapp",
      "phone": "+1234567890"
    }
  }
}

// Verify signature:
const signature = req.headers[
  'x-hyperleap-signature'
];
const payload = req.body;
const secret = process.env.WEBHOOK_SECRET;

const computed = crypto
  .createHmac('sha256', secret)
  .update(JSON.stringify(payload))
  .digest('hex');

if (computed === signature) {
  // Verified! Process webhook
}

Code Examples

Quick start examples in popular languages

Node.js
const Hyperleap = require('@hyperleap/sdk');

const client = new Hyperleap({
  apiKey: process.env.HYPERLEAP_API_KEY
});

// Create an agent
const agent = await client.agents.create({
  name: 'Support Bot',
  model: 'gemini-pro',
  prompt: 'You are a helpful assistant',
  sources: ['doc_abc123']
});

console.log('Agent created:', agent.id);
Python
from hyperleap import Hyperleap

client = Hyperleap(
    api_key=os.environ.get("HYPERLEAP_API_KEY")
)

# Create an agent
agent = client.agents.create(
    name="Support Bot",
    model="gemini-pro",
    prompt="You are a helpful assistant",
    sources=["doc_abc123"]
)

print(f"Agent created: {agent.id}")
cURL
curl https://api.hyperleap.ai/v1/agents \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Bot",
    "model": "gemini-pro",
    "prompt": "You are a helpful assistant",
    "sources": ["doc_abc123"]
  }'
Go
package main

import (
    "github.com/hyperleap/hyperleap-go"
)

func main() {
    client := hyperleap.NewClient(
        os.Getenv("HYPERLEAP_API_KEY"),
    )

    agent, _ := client.Agents.Create(&hyperleap.AgentCreateParams{
        Name: "Support Bot",
        Model: "gemini-pro",
        Prompt: "You are a helpful assistant",
    })
}
Explore All SDKs

Error Handling

Hyperleap uses conventional HTTP response codes and returns detailed error messages in JSON format.

200 - OKSuccess

Request succeeded

400 - Bad RequestClient Error

Invalid parameters or malformed request

401 - UnauthorizedAuth Error

Invalid or missing API key

429 - Too Many RequestsRate Limit

Rate limit exceeded, retry after specified time

500 - Server ErrorServer Error

Something went wrong on our end

Need API Support?

Our engineering team is here to help you integrate with Hyperleap API.

View Code ExamplesGet Technical Support