HTTP API Integration

The SipPulse AI REST API allows any backend or external system to create conversations, send messages and receive responses from an Agent, offering complete control over the interaction. This page presents a complete guide to integrate your systems with an Agent.

1. Authentication

All API requests must include an API key in the header. You can generate and manage your keys in Settings → API Keys.

http

api-key: <YOUR_API_KEY>
Content-Type: application/json

2. Fundamental Concepts

Term	Description
Agent	The AI entity you create and configure on the SipPulse AI platform. Each Agent has a unique `agent_id`.
Thread	Represents a continuous conversation session between an end user and an Agent. It stores message history and conversation context.

3. Essential Conversation Flow

The lifecycle of an API interaction generally follows these steps:

Create a Thread: Start a new conversation for an Agent.
Send Messages: Interact with the Agent within the created Thread.
Query Thread: Access conversation history and data.
Close Thread: End the conversation in a controlled manner.

3.1. Create a Conversation (Thread)

To start a conversation, send a POST request to the /threads endpoint. This creates an isolated space for interaction, which will maintain history and context.

Endpoint: POST /threads

bash

curl -X POST https://api.sippulse.ai/threads \
 -H "api-key: <YOUR_API_KEY>" \
 -d '{
  "agent_id": "agt_0123456789abcdef",
  "uid": "user-session-xyz-123",
  "vars": {
    "user_name": "Pedro",
    "plan_type": "Premium"
  },
  "additional_instructions": "The user is on the checkout page. Be brief and direct."
}'

Body Parameters:

Field	Required	Description
`agent_id`	Yes	The ID of the Agent that will conduct the conversation. You can copy this ID from the Agent listing screen on the SipPulse AI platform.
`uid`	No	A unique identifier defined by you. Case: If you need to start an interaction without first waiting for the thread creation response, you can define your own ID. Then, in `/run` or `/stream` calls, you can use this `uid` instead of the SipPulse-generated `id` (`thr_...`). Attention: The `uid` must be globally unique. Trying to create a thread with an existing `uid` will result in a `409 Conflict` error.
`vars`	No	An object (dictionary) to fill dynamic variables in your Agent's instructions. Useful for personalizing interaction with user data.
`additional_instructions`	No	Text instructions that are added to the system prompt only for this specific thread, without changing the Agent's global instructions.

Response:

json

{
  "id": "thr_01HZYB2B9XFT1TD...", // ID generated by SipPulse AI
  "agent_id": "agt_0123456789abcdef",
  "uid": "user-session-xyz-123",
  "status": "active",
  // ... other fields
}

3.2. Send Messages

After creating the thread, you can send messages using the thread id (or the uid you defined).

Synchronous Mode (`/run`)

Ideal for backend scenarios where you wait for the Agent's complete response before continuing. In this mode, all internal processes (tool calls, RAG, etc.) are hidden, and you receive only the final response.

Endpoint: POST /threads/{thread_id}/run

bash

curl -X POST https://api.sippulse.ai/threads/thr_01HZYB2B9XFT1TD.../run \
 -H "api-key: <YOUR_API_KEY>" \
 -d '{
   "role": "user",
   "content": "Hello, how are you?"
}'

The response follows OpenAI's standard ChatCompletion format, including the assistant message and token usage.

Stream Mode (`/stream`)

Ideal for real-time UIs (like a chat), sending the Agent's response in chunks (tokens) as they are generated. The connection uses SSE (Server-Sent Events). Unlike /run mode, stream allows you to see all internal steps the Agent is taking.

Endpoint: POST /threads/{thread_id}/stream

bash

curl -N -X POST https://api.sippulse.ai/threads/thr_01HZYB2B9XFT1TD.../stream \
 -H "api-key: <YOUR_API_KEY>" \
 -d '{"role": "user", "content": "Explain the theory of relativity in 20 words."}'

Stream Events:

Each stream line contains data: <json> with different event types that reveal the Agent's internal process:

Event	Description	Main Fields
`tool_call_request`	The Agent requested a tool call.	`id`, `name`
`tool_call_initiated`	A tool was called automatically.	`id`, `tool_calls`, `name`
`tool_call_complete`	A tool finished executing.	`tool_call_name`, `tool_call_id`, `result`
`message_chunk`	Fragment of message being generated in real time.	`id`, `content`
`message_complete`	The message was finalized.	`id`, `content`
`message_report`	Final report with execution metrics.	`id`, `usage`, `execution_time`
`abort`	Something interrupted processing.	`reason`

Example event flow:

data: {"id":"msg_123","event":"tool_call_initiated","tool_calls":[...],"name":"search_order"}
data: {"event":"tool_call_complete","tool_call_name":"search_order","tool_call_id":"call_456"}
data: {"id":"msg_123","event":"message_chunk","content":"Your order"}
data: {"id":"msg_123","event":"message_chunk","content":" #12345"}
data: {"id":"msg_123","event":"message_complete","content":"Your order #12345 was shipped today."}
data: {"event":"message_report","id":"msg_123","usage":{"total_tokens":45},"execution_time":1250}
data: [DONE]

3.3. Query a Thread

Get detailed information about a thread, including message history, post-analyses (when available) and metadata.

Endpoint: GET /threads/{thread_id}

bash

curl -X GET https://api.sippulse.ai/threads/thr_01HZYB2B9XFT1TD... \
 -H "api-key: <YOUR_API_KEY>"

Response (example):

json

{
  "id": "thr_01HZYB2B9XFT1TD...",
  "agent_id": "agt_0123456789abcdef",
  "status": "closed",
  "created_at": "2024-03-15T10:30:00Z",
  "closed_at": "2024-03-15T10:45:00Z",
  "messages": [
    {
      "id": "msg_001",
      "role": "user",
      "content": "Hello, what's the status of my order?",
      "timestamp": "2024-03-15T10:30:15Z"
    },
    {
      "id": "msg_002", 
      "role": "assistant",
      "content": "Sure! Your order #12345 was shipped today at 09:00.",
      "timestamp": "2024-03-15T10:30:18Z"
    }
  ],
  "post_analysis": {
    "summary": "Customer inquired about order status. Service resolved.",
    "sentiment": "neutral",
    "tags": ["order", "status", "logistics"]
  },
  "text_history": "User: Hello, what's the status of my order?\nAssistant: Sure! Your order #12345 was shipped today at 09:00.",
  "vars": {
    "user_name": "Pedro",
    "plan_type": "Premium"  
  }
}

This endpoint is especially useful for:

Retrieving complete conversation history
Accessing post-analyses generated by the Agent after closure
Synchronizing data between different systems
Audits and reports

3.4. Close the Conversation (`/close`)

This is the recommended way to finalize a thread. This action changes status to closed, triggers configured webhooks (e.g., thread.closed) and executes the Agent's Post-Analyses. The thread can still be queried, but can no longer receive new messages.

Endpoint: POST /threads/{thread_id}/close

3.5. Delete the Conversation (`/delete`)

Destructive Action

Use this endpoint with extreme care. It permanently removes the thread and all its message history. In most cases, closing (/close) is the better option, as it preserves data for future analysis.

Endpoint: DELETE /threads/{thread_id}

4. Message Format and History

4.1. Message Structure

The message object format follows the market standard established by major LLMs (OpenAI, Anthropic, Google), ensuring familiarity and ease of integration.

json

{
  "role": "user",
  "content": "What is the status of my order #12345?",
  "name": "optional_tool_name",
  "tool_call_id": "optional_tool_call_id"
}

`role`	Description
`user`	Represents a message sent by the end user. This is the role you'll use most of the time to interact with the Agent.
`assistant`	Represents a message generated by the Agent. If you send a message with this role, it will only be added to the conversation history, and the Agent will not generate a response. Useful for manually building conversation history.
`tool`	Used to provide the result of a manual tool call. The message must contain the tool execution result and the corresponding `tool_call_id`.

4.2. History Management

You have two options for managing message history:

Automatic Management (Recommended)

By default, SipPulse AI manages the entire conversation history for you. Simply send a single message object in each request. The system appends your message to existing history and generates the Agent's response based on the entire thread context.

Example:

json

// Send only the new message object
{
  "role": "user",
  "content": "Thank you for the help!"
}

Manual Management (Advanced)

If you need complete control over context, you can manage history yourself. To do this, instead of an object, send an array of message objects.

History Overwrite

When you send an array, the thread's message history is completely replaced by the content you sent. SipPulse AI will not use any previous thread history to generate the response. You become solely responsible for maintaining and sending complete context on each call.

Example:

json

// Send complete history on each call
[
  { "role": "user", "content": "Hello, what's the status of my order?" },
  { "role": "assistant", "content": "Sure, what's the order number?" },
  { "role": "user", "content": "It's #12345." }
]

5. Practical Examples

5.1. Customer Service Chat Bot

javascript

// 1. Create thread with customer data
const thread = await fetch('/threads', {
  method: 'POST',
  headers: { 'api-key': API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    agent_id: 'agt_support_123',
    uid: `customer-${customerId}-${Date.now()}`,
    vars: {
      customer_name: 'Maria Silva',
      customer_tier: 'Gold',
      last_purchase: '2024-03-10'
    }
  })
}).then(r => r.json());

// 2. Interact via stream for real-time UI
const response = await fetch(`/threads/${thread.id}/stream`, {
  method: 'POST',
  headers: { 'api-key': API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    role: 'user',
    content: 'I need to cancel my order'
  })
});

// 3. Process stream events
const reader = response.body.getReader();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  
  const lines = new TextDecoder().decode(value).split('\n');
  for (const line of lines) {
    if (line.startsWith('data: ')) {
      const data = JSON.parse(line.slice(6));
      if (data.event === 'message_chunk') {
        updateUI(data.content); // Update interface in real time
      }
    }
  }
}

5.2. Batch Processing (Backend)

python

import requests

# Process multiple queries synchronously
def process_customer_queries(queries):
    results = []
    
    for query in queries:
        # Create thread
        thread = requests.post('/threads', 
            headers={'api-key': API_KEY},
            json={
                'agent_id': 'agt_support_456',
                'vars': {'priority': 'high'}
            }).json()
        
        # Send message (synchronous mode)
        response = requests.post(f'/threads/{thread["id"]}/run',
            headers={'api-key': API_KEY},
            json={'role': 'user', 'content': query}).json()
        
        # Close thread
        requests.post(f'/threads/{thread["id"]}/close',
            headers={'api-key': API_KEY})
        
        results.append(response['choices'][0]['message']['content'])
    
    return results

6. Useful Webhooks

To monitor thread events asynchronously, configure Webhooks in Integrations → Webhooks.

Event	When it occurs	Key payload
`thread.created`	After successful thread creation.	`id`, `agent_id`, `uid`, `vars`
`thread.closed`	After a thread is closed (via API or inactivity in other channels).	`id`, `post_analysis`, `text_history`

7. Limits and Costs

Rate Limits: The API reflects the requests per second (RPS) limits of the language model chosen in your Agent. Exceeding the limit will return a 429 Too Many Requests error. Current limit details are returned in x-rate-limit-* headers to help monitor if the model still has available requests.
Costs: Costs are calculated based on the chosen LLM model cost + the Agent's output token cost. See the pricing page for details.

Agents

Deploying Agents

Settings

HTTP API Integration

1. Authentication

2. Fundamental Concepts

3. Essential Conversation Flow

3.1. Create a Conversation (Thread)

3.2. Send Messages

Synchronous Mode (`/run`)

Stream Mode (`/stream`)

3.3. Query a Thread

3.4. Close the Conversation (`/close`)

3.5. Delete the Conversation (`/delete`)

4. Message Format and History

4.1. Message Structure

4.2. History Management

Automatic Management (Recommended)

Manual Management (Advanced)

5. Practical Examples

5.1. Customer Service Chat Bot

5.2. Batch Processing (Backend)

6. Useful Webhooks

7. Limits and Costs

Deploying Agents

HTTP API Integration ​

1. Authentication ​

2. Fundamental Concepts ​

3. Essential Conversation Flow ​

3.1. Create a Conversation (Thread) ​

3.2. Send Messages ​

Synchronous Mode (/run) ​

Stream Mode (/stream) ​

3.3. Query a Thread ​

3.4. Close the Conversation (/close) ​

3.5. Delete the Conversation (/delete) ​

4. Message Format and History ​

4.1. Message Structure ​

4.2. History Management ​

Automatic Management (Recommended) ​

Manual Management (Advanced) ​

5. Practical Examples ​

5.1. Customer Service Chat Bot ​

5.2. Batch Processing (Backend) ​

6. Useful Webhooks ​

7. Limits and Costs ​

HTTP API Integration

1. Authentication

2. Fundamental Concepts

3. Essential Conversation Flow

3.1. Create a Conversation (Thread)

3.2. Send Messages

Synchronous Mode (`/run`)

Stream Mode (`/stream`)

3.3. Query a Thread

3.4. Close the Conversation (`/close`)

3.5. Delete the Conversation (`/delete`)

4. Message Format and History

4.1. Message Structure

4.2. History Management

Automatic Management (Recommended)

Manual Management (Advanced)

5. Practical Examples

5.1. Customer Service Chat Bot

5.2. Batch Processing (Backend)

6. Useful Webhooks

7. Limits and Costs