English

Português

English

Português

Appearance

Agents and Threads ​

We recommend creating agents through the SipPulse AI platform interface, as it offers more intuitive and easy-to-manage features compared to creating via API. You can refer to here for more information on how to create and manage agents.

After creating an agent, it is necessary to create a thread through the POST /threads endpoint to start interacting with it. A thread functions as a chat with the agent, allowing the user to send requests without worrying about the message history, as it is automatically managed by the system.

After creating a thread, you can send messages to the agent through the POST /threads/{id}/run endpoint and receive real-time responses. Messages can be sent in any order, and the system automatically manages the conversation context.

Endpoints ​

POST /threads ​

This endpoint creates a new thread to interact with an agent.

Request Body ​

json
{
  "agent_id": "string", // ID of the agent to be used
  "additional_instructions": "string" // (optional) Additional instructions for the agent
}

Request Example ​

bash
curl -X 'POST' \
  'https://api.sippulse.ai/v1/threads' \
  -H 'Content-Type: application/json' \
  -H 'api-key: $SIPPULSE_API_KEY' \
  -d '{
  "agent_id": "agent_12345",
  "additional_instructions": "Please be concise in your responses."
}'
python
import requests
import json

url = "https://api.sippulse.ai/v1/threads"
headers = {
    "Content-Type": "application/json",
    "api-key": "SIPPULSE_API_KEY"
}
data = {
    "agent_id": "agent_12345",
    "additional_instructions": "Please be concise in your responses."
}

response = requests.post(url, headers=headers, data=json.dumps(data))
print(response.json())
javascript
const url = "https://api.sippulse.ai/v1/threads";
const headers = {
  "Content-Type": "application/json",
  "api-key": "SIPPULSE_API_KEY",
};
const data = {
  agent_id: "agent_12345",
  additional_instructions: "Please be concise in your responses.",
};

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

Response Example ​

json
{
  "id": "thread_67890",
  "organization_id": "org_12345",
  "user_id": "user_12345",
  "agent_id": "agent_12345",
  "checkpoint": null,
  "history": [],
  "deleted_at": null,
  "created_at": "2023-01-01T00:00:00Z",
  "updated_at": "2023-01-01T00:00:00Z"
}

POST /threads/{id}/run ​

This endpoint allows sending messages to the thread and receiving agent responses.

Path Parameters ​

  • id (required): The ID of the thread.

Request Body ​

json
{
  "role": "string", // The role of the message (e.g., user, assistant)
  "content": "string", // The content of the message
  "name": "string", // (optional) User's name
  "tool_call_id": "string" // Used only when the agent's last message is a tool_call
}

Request Example ​

bash
curl -X 'POST' \
  'https://api.sippulse.ai/v1/threads/thread_67890/run' \
  -H 'Content-Type: application/json' \
  -H 'api-key: $SIPPULSE_API_KEY' \
  -d '{
  "role": "user",
  "content": "Hello, how are you?"
}'
python
import requests
import json

url = "https://api.sippulse.ai/v1/threads/thread_67890/run"
headers = {
    "Content-Type": "application/json",
    "api-key": "SIPPULSE_API_KEY"
}
data = {
    "role": "user",
    "content": "Hello, how are you?"
}

response = requests.post(url, headers=headers, data=json.dumps(data))
print(response.json())
javascript
const url = "https://api.sippulse.ai/v1/threads/thread_67890/run";
const headers = {
  "Content-Type": "application/json",
  "api-key": "SIPPULSE_API_KEY",
};
const data = {
  role: "user",
  content: "Hello, how are you?",
};

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

Response Example ​

json
{
  "choices": [
    {
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "I'm doing well, thank you! How can I assist you today?"
      }
    }
  ],
  "created": 1672531200,
  "model": "gpt-4-turbo",
  "usage": {
    "input_tokens": 10,
    "output_tokens": 12
  },
  "execution_time": 1.234
}

POST /threads/{id}/clear ​

This endpoint resets the message history of the thread.

Path Parameters ​

  • id (required): The ID of the thread.

Request Example ​

bash
curl -X 'POST' \
  'https://api.sippulse.ai/v1/threads/thread_67890/clear' \
  -H 'api-key: $SIPPULSE_API_KEY'
python
import requests

url = "https://api.sippulse.ai/v1/threads/thread_67890/clear"
headers = {
    "api-key": "SIPPULSE_API_KEY"
}

response = requests.post(url, headers=headers)
print(response.status_code)
javascript
const url = "https://api.sippulse.ai/v1/threads/thread_67890/clear";
const headers = {
  "api-key": "SIPPULSE_API_KEY",
};

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

Response Example ​

Status: 204 No Content

GET /threads/{id} ​

This endpoint returns the information of a specific thread.

Path Parameters ​

  • id (required): The ID of the thread.

Request Example ​

bash
curl -X 'GET' \
  'https://api.sippulse.ai/v1/threads/thread_67890' \
  -H 'Content-Type: application/json' \
  -H 'api-key: $SIPPULSE_API_KEY'
python
import requests

url = "https://api.sippulse.ai/v1/threads/thread_67890"
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/threads/thread_67890";
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));

Response Example ​

json
{
  "id": "thread_67890",
  "organization_id": "org_12345",
  "user_id": "user_12345",
  "agent_id": "agent_12345",
  "checkpoint": null,
  "history": [],
  "deleted_at": null,
  "created_at": "2023-01-01T00:00:00Z",
  "updated_at": "2023-01-01T00:00:00Z"
}

DELETE /threads/{id} ​

This endpoint deletes a specific thread.

Path Parameters ​

  • id (required): The ID of the thread.

Request Example ​

bash
curl -X 'DELETE' \
  'https://api.sippulse.ai/v1/threads/thread_67890' \
  -H 'api-key: $SIPPULSE_API_KEY'
python
import requests

url = "https://api.sippulse.ai/v1/threads/thread_67890"
headers = {
    "api-key": "SIPPULSE_API_KEY"
}

response = requests.delete(url, headers=headers)
print(response.status_code)
javascript
const url = "https://api.sippulse.ai/v1/threads/thread_67890";
const headers = {
  "api-key": "SIPPULSE_API_KEY",
};

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

Response Example ​

Status: 204 No Content

Conclusion ​

The Thread endpoints in the SipPulse AI platform allow you to efficiently create, interact, clear, and manage agent threads. Use the provided information and examples to integrate these functionalities into your applications.