Puppeteer API Documentation

URL: https://api.getpuppeteer.ai/

POST: /chat

URL:  https://api.getpuppeteer.ai/chat

This endpoint is used to send a message to the AI and it returns a response. It can be configured to return both a streaming and non-streaming response.

Request Headers

• Authorization: API key for their Puppeteer organization OR JWT token for the thread_id

Request Body

• thread_id: (Required, String) Identifier for the thread.

• message: (Required, String) The actual message content sent by the user.

• streaming: (Boolean, Default: False) Flag to indicate if the response is to be streamed.

• puppeteer_mode_name: (Required, String) Identifier for the AI product.

• start_new_conversation: (Optional, Boolean) If true, ends the current conversation and sends the first message in a new one.

Default Response

message: (String) The generated reply from the AI.
Response contains the generated reply from Chat.
Example:
{
"message": "Hello there! How can I assist you?"
}

Streaming Response

If streaming is set to true, the response is sent as individual tokens progressively.
Example:
{"token": "Hello", "index": 0}
{"token": " ", "index": 1}
{"token": "there", "index": 2}
{"token": "!", "index": 3}
{"token": " How", "index": 4}
...
{"token": " you?", "index": n}

• token: (String) The word or character from the AI's response.

• index: (Integer) Position of the token in the full response.

Final Response:

The stream concludes with a final JSON containing the complete message.

{

"message": "Hello there! How can I assist you?"

}

Note: A single batch might contain more than one token.

POST: /create_thread

URL: https://api.getpuppeteer.ai/create_thread

This endpoint is used to generate a unique identifier for a new thread

Request Headers

• Authorization: API key for their Puppeteer organization.
  
  

Request Body

None required for this endpoint.

Response

• thread_id: (String) The generated unique identifier for the new thread.
  
  

Default Response

Response contains the unique thread id.

Example:

{

"thread_id": "550e8400-e29b-41d4-a716-446655440000 "

}

POST: /retrieve_conversations

URL: https://api.getpuppeteer.ai/retrieve_conversations

This endpoint is used to retrieve past messages exchanged in a specific thread. Messages are returned in chronological order and the response includes pagination.

Request Headers

• Authorization: API key for their Puppeteer organization.
  
  

Request Query Parameters

• thread_id: (Required, String) Identifier for the thread.

• page: (Optional, Integer) The page number to retrieve. Defaults to 1.

• limit: (Optional, Integer) Number of messages per page. Defaults to 25.
  
  

Response

The response includes one page of conversation history and the pagination details. The messages array includes:

• message_id: (String) A unique identifier for the message.

• role: (String) The role can be either 'user' or 'AI'.

• message: (String) The message content.

• conversation_id: (String) The conversation_id of the message

The pagination object includes:

• current_page: (Integer) The current page number.

• total_pages: (Integer) The total number of pages.

• total_items: (Integer) The total number of messages.
  
  

Default Response

Response contains one page of conversation history and pagination details.

Example:

{
"messages": [

{

"message_id": "msg1",

"role": "user",

"message": "Hello, how are you?"

"conversation_id": "12234234"

},

{

"message_id": "msg2",

"role": "AI",

"message": "I'm an AI, but I'm functioning as expected. How can I help you?"

"conversation_id": "12234234"

},

{

"message_id": "msg3",

"role": "user",

"message": "What's the weather today?"

"conversation_id": "12234234"

},

{

"message_id": "msg4",

"role": "AI",

"message": "I'm sorry, but as an AI, I don't have the ability to provide real-time weather updates."

"conversation_id": "12234234"

}

// More messages...

],

"pagination": {

"current_page": 1,

"total_pages": 20,

"total_items": 500

}

}

POST: /end_conversation

URL: https://api.getpuppeteer.ai/end_conversation

This endpoint is utilized to terminate an active conversation in a specific thread and start a new one.

Request Headers

• Authorization: API key for their Puppeteer organization.

Request Body

• thread_id: (Required, String) Identifier for the thread for whom a conversation is to be terminated.

Response

If successful:

• message: A success message confirming that the conversation was terminated.

• If there is an error:

If there was an error:

• Error: Error message describing the nature of the issue.

• HTTP Status: 400:
  
  

Example request

Response contains the unique thread id.

Example:

POST https://api.getpuppeteer.ai/end_conversation

Headers:

{

"Authorization": "Bearer YOUR_API_KEY"

}

Body:

{

"thread_id": "550e8400-e29b-41d4-a716-446655440000"

}

POST: /get_followup

This endpoint is used to receive a proactive message from the AI, without having sent a message.

Request Headers

• Authorization: API key for their Puppeteer organization

Request Body

• thread_id: (Required, String) Identifier for the thread.

• streaming: (Boolean, Default: False) Flag to indicate if the response is to be streamed.

• puppeteer_mode_name: (Required, String) Identifier for the AI product.

• start_new_conversation: (Optional, Boolean) If true, ends the current conversation and sends the first message in a new one.
  
  

Default Response

message: (String) The generated reply from the AI.

Response contains the generated reply from Chat.

Example:

{

"message": "Hello there! How can I assist you?"

}

Streaming Response

If streaming is set to true, the response is sent as individual tokens progressively.

Example:

{"token": "Hello", "index": 0}

{"token": " ", "index": 1}

{"token": "there", "index": 2}

{"token": "!", "index": 3}

{"token": " How", "index": 4}

...

{"token": " you?", "index": n}

• token: (String) The word or character from the AI's response.

• index: (Integer) Position of the token in the full response.

Final Response:

The stream concludes with a final JSON containing the complete message.

{

"message": "Hello there! How can I assist you?"

}

Note: A single batch might contain more than one token.

POST: /retrieve_conversation_summary

URL:  https://api.getpuppeteer.ai/retrieve_conversation_summary

This endpoint is used to retrieve a summary of the current conversation in a given thread.

Request Headers

Authorization: API key for their Puppeteer organization.

Request Body:

thread_id: (Required, String) Identifier for the user interacting with the AI.

Default Response

conversation_summary: (String) A summarized recap of the key points covered in the current conversation.

If there is an error:

error: (String) Error message describing the issue.

status_code: (Integer) HTTP status code.

Example Response:

{

"conversation_summary": "We just discussed the weather today."

}

POST: /generate-token/{thread_id}

This endpoint is used to generate a JSON Web Token (JWT) for the specified thread ID. The JWT can be used to authenticate subsequent requests to the API.

Request Headers

• Authorization: YOUR_API_KEY
  
  

Request Parameters

• thread_id: (Required, String) Identifier for the thread.
  
  

Response

• access_token: (String) The generated JWT.

Example Response:

{

"access_token": "YOUR_JWT"

}