Chat API Reference

Following are the steps to use Test it feature.

• Replace the {{url}} with the deployed url.

• Get the api key from the GenAI Stack for authentication.

• Now you're ready to test the APIs.

Health

GET{{url}}/health

Response

200

Successful Response

Body

application/json

any

Request

JavaScriptCurlPython

const response = await fetch('{{url}}/health', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Get Stack App

Retrieve the stack app instance.

This endpoint fetches the stack app, including its associated chat sessions or text generations based on the interface type selected, using the provided token/api key.

Parameters:

• authorization: str - Provide your API key as a Bearer token in the Authorization header to authenticate requests.

Responses:

• 200 OK: Returns a detailed view of the stack app including chat sessions and text generations.
• 404 Not Found: If no stack app is found for the given criteria.

Exceptions:

• Raises a 404 HTTPException if no stack app is found.

GET{{url}}/api/v1/apps

Query parameters

Header parameters

Response

200422

Successful Response

Body

application/json

id*Id

data*Data

form_keys_data*Form Keys Data

stack_type*StackAppType

chattext_generation

chat_sessions*Chat Sessions

array of ChatSessionReadnull

text_generations*Text Generations

array of TextGenerationReadnull

Request

JavaScriptCurlPython

const response = await fetch('{{url}}/api/v1/apps', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200422

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "stack_type": "chat",
  "chat_sessions": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "title": "text",
      "data": [
        {
          "is_bot": true,
          "message": "text",
          "chatKey": "text",
          "type": "text",
          "intermediate_steps": "text",
          "files": []
        }
      ]
    }
  ],
  "text_generations": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "logs": "text",
      "status": "pending"
    }
  ]
}

Create Chat Session

Create a new chat session associated with a specific stack app.

Parameters:

• stack_app_id: UUID - Path parameter to specify the stack app ID the chat session will be associated with.
• title: Optional[str] - A custom title for the chat session. If not provided, a default title "New Chat" is used.
• authorization: str - Provide your API key as a Bearer token in the Authorization header to authenticate requests.

Responses:

• 200 OK: Returns the created chat session's details.
• 401 Unauthorized: If user authentication fails.
• 429 Too Many Requests: If the request is throttled based on rate limiting.

Exceptions:

• Raises 401 HTTPException for unauthorized access.
• Raises 429 HTTPException for exceeding rate limit, with retry information.
• Raises 404 HTTPException if stack app doesn't exist

POST{{url}}/api/v1/{stack_app_id}/chat-sessions

Path parameters

stack_app_id*Stack App Id

Query parameters

Header parameters

Body

application/json

titleTitle

stringnull

Response

200422

Successful Response

Body

application/json

id*Id

title*Title

data*Data

array of any ofnull

Request

JavaScriptCurlPython

const response = await fetch('{{url}}/api/v1/{stack_app_id}/chat-sessions', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200422

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "title": "text",
  "data": [
    {
      "is_bot": true,
      "message": "text",
      "chatKey": "text",
      "type": "text",
      "intermediate_steps": "text",
      "files": []
    }
  ]
}

Get Chat Session

Retrieve details of a specific chat session by its ID and associated stack app ID.

Parameters:

• stack_app_id: UUID - Path parameter to specify the stack app ID.
• chat_session_id: str - Path parameter to specify the chat session ID.
• authorization: str - Provide your API key as a Bearer token in the Authorization header to authenticate requests.

Responses:

• 200 OK: Successfully retrieves and returns the details of the chat session.
• 400 Bad Request: If the chat_session_id is not a valid UUID.
• 401 Unauthorized: If user authentication fails.
• 404 Not Found: If no chat session is found matching the criteria.

Exceptions:

• Raises 400 HTTPException if chat_session_id is invalid.
• Raises 401 HTTPException for unauthorized access.
• Raises 404 HTTPException if the chat session is not found.
• Raises 404 HTTPException if stack app doesn't exist

GET{{url}}/api/v1/{stack_app_id}/chat-sessions/{chat_session_id}

Path parameters

stack_app_id*Stack App Id

chat_session_id*Chat Session Id

Query parameters

Header parameters

Response

200422

Successful Response

Body

application/json

id*Id

title*Title

data*Data

array of any ofnull

data_pipelinesData Pipelines

array of DataPipelineReadnull

can_chatCan Chat

Request

JavaScriptCurlPython

const response = await fetch('{{url}}/api/v1/{stack_app_id}/chat-sessions/{chat_session_id}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200422

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "title": "text",
  "data": [
    {
      "is_bot": true,
      "message": "text",
      "chatKey": "text",
      "type": "text",
      "intermediate_steps": "text",
      "files": []
    }
  ],
  "data_pipelines": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "input_key": "text",
      "created_at": "2024-11-21T06:29:49.269Z",
      "files": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "file": "text",
          "url": "text",
          "text": "text",
          "created_at": "2024-11-21T06:29:49.269Z",
          "data_pipeline_status": "queued"
        }
      ]
    }
  ],
  "can_chat": true
}

Chat

Initiates or continues a chat session by sending a payload to the specified chat session.

This endpoint allows users to interact with a chat session by sending a payload. The payload will be processed according to the chat session's logic, and a response will be streamed back. This endpoint requires user authentication and is subject to rate limiting to ensure fair usage.

Parameters:

• stack_app_id: str - The unique identifier of the stack app associated with the chat session. It is a path parameter.
• chat_session_id: str - The unique identifier of the chat session to which the message is being sent. It is a path parameter.
• payload: dict - A JSON object containing the chatKey & inputs. The values of chatKey & inputs will be dynamic check the form_keys_data object in stack app data in which chatKey is key given in input_keys & inputs is object containing all the required inputs. When there are multiple input_keys chatKey can be the key which you want to make it primary.
• authorization: str - Provide your API key as a Bearer token in the Authorization header to authenticate requests.

Successful Response:

• Returns a streaming response, which streams the response from the chat session back to the client. The response is in the text/event-stream format.

Errors:

• HTTP 401 Unauthorized: Returned if the user cannot be authenticated or authorized, indicating either missing, invalid, or expired credentials.
• HTTP 429 Too Many Requests: Returned if the request is throttled based on rate limiting. The response includes a Retry-After header indicating how long the client should wait before retrying.
• HTTP 500 Internal Server Error: Returned if an unexpected error occurs during the processing of the chat message.
• Raises 404 HTTPException if stack app doesn't exist

Notes:

• The endpoint is designed for real-time chat interactions and uses Server-Sent Events (SSE) to stream responses back to the client.
• Clients must be prepared to handle streaming responses and display them to the user in real-time.
• The rate limiting mechanism is in place to ensure that all users have a smooth experience.

POST{{url}}/api/v1/{stack_app_id}/chat-sessions/{chat_session_id}

Path parameters

stack_app_id*Stack App Id

chat_session_id*Chat Session Id

Query parameters

Header parameters

Body

application/json

chatKey*Chatkey

inputs*Inputs

Response

200422

Successful Response

Body

application/json

Response Chat Api V1 Stack App Id Chat Sessions Chat Session Id Post

ChatResponseChatMessagePromptResponse

Request

JavaScriptCurlPython

const response = await fetch('{{url}}/api/v1/{stack_app_id}/chat-sessions/{chat_session_id}', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "chatKey": "text"
    }),
});
const data = await response.json();

Response

200422

{
  "is_bot": true,
  "message": "text",
  "chatKey": "text",
  "type": "text",
  "intermediate_steps": "text",
  "files": []
}

Update Chat Session

Update details of an existing chat session, such as its title.

Parameters:

• stack_app_id: UUID - Path parameter for the associated stack app.
• chat_session_id: UUID - Path parameter for the chat session to update.
• update_request: ChatSessionUpdate - The request body containing the update details.
• authorization: str - Provide your API key as a Bearer token in the Authorization header to authenticate requests.

Responses:

• 200 OK: Returns the updated chat session details.
• 401 Unauthorized: If user authentication fails.
• 404 Not Found: If no chat session is found matching the criteria.

Exceptions:

• Raises 401 HTTPException for unauthorized access.
• Raises 404 HTTPException if the chat session not found
• Raises 404 HTTPException if stack app doesn't exist

PATCH{{url}}/api/v1/{stack_app_id}/chat-sessions/{chat_session_id}

Path parameters

stack_app_id*Stack App Id

chat_session_id*Chat Session Id

Query parameters

Header parameters

Body

application/json

titleTitle

stringnull

Response

200422

Successful Response

Body

application/json

id*Id

title*Title

data*Data

array of any ofnull

data_pipelinesData Pipelines

array of DataPipelineReadnull

can_chatCan Chat

Request

JavaScriptCurlPython

const response = await fetch('{{url}}/api/v1/{stack_app_id}/chat-sessions/{chat_session_id}', {
    method: 'PATCH',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200422

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "title": "text",
  "data": [
    {
      "is_bot": true,
      "message": "text",
      "chatKey": "text",
      "type": "text",
      "intermediate_steps": "text",
      "files": []
    }
  ],
  "data_pipelines": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "input_key": "text",
      "created_at": "2024-11-21T06:29:49.269Z",
      "files": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "file": "text",
          "url": "text",
          "text": "text",
          "created_at": "2024-11-21T06:29:49.269Z",
          "data_pipeline_status": "queued"
        }
      ]
    }
  ],
  "can_chat": true
}

Data Pipeline List

This endpoint lists all files, URLs, or text snippets associated with a chat session, allowing for a comprehensive view of the resources related to a conversation.

Parameters:

• stack_app_id: str - The unique identifier of the stack app associated with the chat session.
• chat_session_id: str - The unique identifier of the chat session for which to list uploads.
• authorization: str - Provide your API key as a Bearer token in the Authorization header to authenticate requests.

Responses:

• 200 OK: Successfully returns a list of uploads for the chat session.
• 401 Unauthorized: User authentication failed.
• Raises 404 HTTPException if stack app doesn't exist

This endpoint provides an overview of all resources uploaded or linked in the context of a specific chat session.

GET{{url}}/api/v1/{stack_app_id}/chat-sessions/{chat_session_id}/uploads

Path parameters

stack_app_id*Stack App Id

chat_session_id*Chat Session Id

Query parameters

Header parameters

Response

200422

Successful Response

Body

application/json

id*Id

file*File

stringnull

url*Url

stringnull

text*Text

stringnull

chat_session_id*Chat Session Id

created_at*Created At

meta_data*Meta Data

objectnull

data_pipeline_status*DataPipelineStatus

queuedrunningfailedsuccess

data_pipeline*DataPipelineRead

Request

JavaScriptCurlPython

const response = await fetch('{{url}}/api/v1/{stack_app_id}/chat-sessions/{chat_session_id}/uploads', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200422

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "file": "text",
    "url": "text",
    "text": "text",
    "chat_session_id": "123e4567-e89b-12d3-a456-426614174000",
    "created_at": "2024-11-21T06:29:49.269Z",
    "data_pipeline_status": "queued",
    "data_pipeline": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "input_key": "text",
      "created_at": "2024-11-21T06:29:49.269Z"
    }
  }
]

Data Pipeline

Upload a file, or provide a URL or text to be associated with a chat session. This endpoint supports file uploads for further processing and inclusion in the chat session's context or data pipelines.

Parameters:

• stack_app_id: str - The unique identifier for the stack app associated with this chat session.
• chat_session_id: str - The unique identifier for the chat session where the file or text is to be uploaded.
• input_key: str - A key identifying the type of input or the specific pipeline this upload is associated with.
• url: str (optional) - A URL pointing to a resource to be associated with the chat session.
• file: UploadFile (optional) - The file to be uploaded. Files should be less than 50MB in size.
• text: str (optional) - Text content to be associated with the chat session.
• authorization: str - Provide your API key as a Bearer token in the Authorization header to authenticate requests.

Responses:

• 200 OK: Returns the details of the uploaded file or the provided URL/text including any metadata.
• 401 Unauthorized: User authentication failed.
• 400 Bad Request: Data pipeline for the provided input_key not found or the file size exceeds the limit.
• 429 Too Many Requests: The request is throttled based on rate limiting.
• Raises 404 HTTPException if stack app doesn't exist

Usage:

• To upload a file, include it in the request's form-data.
• To associate a URL or text with the chat session, provide them in the form-data without a file.

This endpoint is subject rate limiting to ensure smooth experience for all the users.

POST{{url}}/api/v1/{stack_app_id}/chat-sessions/{chat_session_id}/uploads

Path parameters

stack_app_id*Stack App Id

chat_session_id*Chat Session Id

Query parameters

Header parameters

Body

multipart/form-data

input_key*Input Key

urlUrl

stringnull

fileFile

string (binary)null

textText

stringnull

Response

200422

Successful Response

Body

application/json

id*Id

file*File

stringnull

url*Url

stringnull

text*Text

stringnull

chat_session_id*Chat Session Id

created_at*Created At

meta_data*Meta Data

objectnull

data_pipeline_status*DataPipelineStatus

queuedrunningfailedsuccess

data_pipeline*DataPipelineRead

Request

JavaScriptCurlPython

const response = await fetch('{{url}}/api/v1/{stack_app_id}/chat-sessions/{chat_session_id}/uploads', {
    method: 'POST',
    headers: {
      "Content-Type": "multipart/form-data"
    },
    body: JSON.stringify({
      "input_key": "text"
    }),
});
const data = await response.json();

Response

200422

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "file": "text",
  "url": "text",
  "text": "text",
  "chat_session_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2024-11-21T06:29:49.269Z",
  "data_pipeline_status": "queued",
  "data_pipeline": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "input_key": "text",
    "created_at": "2024-11-21T06:29:49.269Z"
  }
}

Get Data Pipeline

Retrieve the status and details of a specific file upload, URL, or text associated with a chat session. This allows for detailed tracking and management of resources within a chat context.

Parameters:

• stack_app_id: str - The unique identifier of the stack app associated with the chat session.
• upload_id: str - The unique identifier of the upload whose details are being retrieved.
• chat_session_id: str - The unique identifier of the chat session associated with the upload.
• authorization: str - Provide your API key as a Bearer token in the Authorization header to authenticate requests.

Responses:

• 200 OK: Successfully returns the details of the specified upload.
• 401 Unauthorized: User authentication failed.
• Raises 404 HTTPException if stack app doesn't exist

GET{{url}}/api/v1/{stack_app_id}/chat-sessions/{chat_session_id}/uploads/{upload_id}

Path parameters

stack_app_id*Stack App Id

upload_id*Upload Id

chat_session_id*Chat Session Id

Query parameters

Header parameters

Response

200422

Successful Response

Body

application/json

id*Id

file*File

stringnull

url*Url

stringnull

text*Text

stringnull

chat_session_id*Chat Session Id

created_at*Created At

meta_data*Meta Data

objectnull

data_pipeline_status*DataPipelineStatus

queuedrunningfailedsuccess

data_pipeline*DataPipelineRead

Request

JavaScriptCurlPython

const response = await fetch('{{url}}/api/v1/{stack_app_id}/chat-sessions/{chat_session_id}/uploads/{upload_id}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200422

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "file": "text",
  "url": "text",
  "text": "text",
  "chat_session_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2024-11-21T06:29:49.269Z",
  "data_pipeline_status": "queued",
  "data_pipeline": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "input_key": "text",
    "created_at": "2024-11-21T06:29:49.269Z"
  }
}