Integration Introduction

The SipPulse AI platform has a REST API designed to be the central communication point with all its Artificial Intelligence resources. This API allows developers to programmatically interact and integrate services such as text generation models (LLMs), speech recognition (ASR), text-to-speech conversion (TTS), and intelligent agents directly into their applications.

To assist in API usage, we provide a Swagger UI and an OpenAPI.json file.

Requirements

To start integration, you'll need:

• API Key: Generate an API key in the API Keys section of your SipPulse AI account. Instructions for creating API Keys
• Programming knowledge: Familiarity with HTTP requests and JSON data manipulation.

Each section of this documentation will provide code examples in different programming languages to facilitate integration with our services.

Authentication

To use the SipPulse AI platform services, all requests must be authenticated using an API key. To generate an API key, follow the instructions in the API Keys section of the documentation.

Using the API Key

All requests to the SipPulse AI platform must include the API key in the request header. The header used is api-key. Below are examples of how to include the API key in requests using different programming languages.

cURL

curl -X 'GET' \
  'https://api.sippulse.ai/v1/llms/models' \
  -H 'Content-Type: application/json' \
  -H 'api-key: $SIPPULSE_API_KEY'

Python

import requests

url = "https://api.sippulse.ai/v1/llms/models"
headers = {
    "Content-Type": "application/json",
    "api-key": "SIPPULSE_API_KEY"
}

response = requests.get(url, headers=headers)
print(response.json())

JavaScript

const url = "https://api.sippulse.ai/v1/llms/models";
const headers = {
  "Content-Type": "application/json",
  "api-key": "SIPPULSE_API_KEY",
};

fetch(url, {
  method: "GET",
  headers: headers,
})
  .then((response) => response.json())
  .then((data) => console.log(data))
  .catch((error) => console.error("Error:", error));

API Key Security

• Confidentiality: Never share your API keys publicly. Avoid including them in browser or client code.
• Key Rotation: Periodically generate new API keys and replace old ones to improve security.
• Revocation: If an API key is compromised, revoke it immediately through the API Keys section.

---

Key Endpoints

The SipPulse AI API is organized into functional modules. Below are the main available endpoints:

Agents

Method	Endpoint	Description
GET	/agents	List all agents in the organization
POST	/agents	Create a new agent
GET	/agents/{id}	Get agent details
PATCH	/agents/{id}	Update an agent
DELETE	/agents/{id}	Delete an agent
POST	/agents/{id}/outbound-call	Initiate an outbound call

Conversations (Threads)

Method	Endpoint	Description
GET	/threads	List conversations (with filters)
POST	/threads	Create a new conversation
GET	/threads/{id}	Get a conversation's history
POST	/threads/{id}/messages	Send a message to a conversation
POST	/threads/{id}/close	Close a conversation

Language Models (LLM)

Method	Endpoint	Description
GET	/llms/models	List available LLM models
POST	/llms/completion	Generate a text response
POST	/llms/stream	Generate a streaming response

Speech Recognition (ASR)

Method	Endpoint	Description
GET	/asr/models	List available ASR models
POST	/asr/transcribe	Transcribe audio to text

Text-to-Speech (TTS)

Method	Endpoint	Description
GET	/tts/models	List available TTS models
POST	/tts/synthesize	Convert text to audio

Knowledge Base

Method	Endpoint	Description
GET	/knowledge	List knowledge tables
POST	/knowledge	Create a new table
POST	/knowledge/{name}/query	Semantic search on a table
POST	/knowledge/{name}/rows	Add rows to a table

Webhooks

Method	Endpoint	Description
GET	/webhooks	List configured webhooks
POST	/webhooks	Create a new webhook
PATCH	/webhooks/{id}	Update a webhook
DELETE	/webhooks/{id}	Delete a webhook

Interactive Documentation

For a complete reference with request/response schemas and the ability to test endpoints directly, visit the Swagger UI.

---

Rate Limits

The API enforces rate limits to ensure fair usage and service stability. Limits vary by endpoint type and plan.

Limit Types

Abbreviation	Description	Applies to
RPM	Requests per Minute	All endpoints
RPD	Requests per Day	All endpoints
TPM	Tokens per Minute	LLM endpoints
TPD	Tokens per Day	LLM endpoints
ASH	Audio Seconds per Hour	ASR/TTS endpoints
ASD	Audio Seconds per Day	ASR/TTS endpoints

Rate Limit Headers

When a request is made, the response headers include information about the current rate limit status:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1609459200

Behavior When Limits Are Exceeded

When you exceed a rate limit, the API returns:

• Status: 429 Too Many Requests
• Header: Retry-After with the number of seconds to wait before retrying

Error 429

If you receive a 429 error, implement exponential backoff and respect the Retry-After header before retrying.

Best Practices

1. Implement caching: Store responses that do not change frequently
2. Use streaming: For LLMs, prefer streaming endpoints for long responses
3. Batch requests: Group operations whenever possible
4. Monitor usage: Track your limits in the Usage Dashboard

---

Error Handling

The API uses standard HTTP status codes to indicate success or failure:

Code	Meaning
200	Success
201	Resource created
400	Bad request
401	Unauthenticated
403	Forbidden
404	Resource not found
429	Rate limit exceeded
500	Internal server error

Error Format

{
  "error": {
    "statusCode": 400,
    "name": "BadRequestError",
    "message": "Description of the error"
  }
}