Ondemand Chat API
The Chat API from Ondemand — 7 operation(s) for chat.
OpenAPI Specification
openapi: 3.0.3
info:
title: OnDemand AI Chat API
version: 1.0.0
description: OnDemand AI is a RAG-powered AI Platform-as-a-Service. This OpenAPI definition was assembled by the API Evangelist enrichment pipeline from the per-operation OpenAPI fragments published on the OnDemand AI ReadMe documentation (https://docs.on-demand.io/reference).
servers:
- url: https://api.on-demand.io
- url: https://api.on-demand.io/automation/api
- url: https://api.on-demand.io/services/v1/public/service
- url: https://gateway-dev.on-demand.io
security:
- apikey: []
tags:
- name: Chat
paths:
/chat/v1/sessions:
post:
summary: Create Chat Session
description: Create a new chat session
operationId: createChatSession
requestBody:
content:
application/json:
schema:
type: object
required:
- externalUserId
properties:
externalUserId:
type: string
description: An identifier of the external user creating this chat session. This user is external to OnDemand but internal to your own system which can be used for filtering sessions and auditing. If not managing chat users internally, use any unique string.
pluginIds:
type: array
description: A list of plugin IDs to be used in the chat session. A maximum of 20 plugins are allowed. This list can be empty. if set here and not overwriiten through `/query` endpoint, then these plugins will be used for all queries in this session.
maxItems: 20
items:
type: string
responses:
'200':
description: Success Response
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Chat session created successfully
description: Message indicating the status of operation
data:
$ref: '#/components/schemas/ChatSession'
4XX:
description: Client-side error
content:
application/json:
schema:
$ref: '#/components/schemas/ClientErrorResponse'
5XX:
description: Server-side Error
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
tags:
- Chat
get:
summary: Get Chat Sessions
description: Retrieve chat sessions
operationId: getChatSessions
parameters:
- name: externalUserId
in: query
description: Filter the chat sessions based on external user
schema:
type: string
- name: sort
in: query
description: Sort order of the sessions based on its creation time
schema:
type: string
enum:
- asc
- desc
default: desc
- name: cursor
in: query
description: It acts as a pagination key and used to retrieve next results. For first iteration, this parameter must not be set. For subsequent iterations, it must be set to `pagination.next` value from previous response.
schema:
type: string
- name: limit
in: query
description: Specifies the total number of results to retrieve. If the provided value is less than the minimum allowed limit, it will be reset to the default value. Conversely, if the provided value exceeds the maximum allowed limit, it will be reset to the maximum value.
schema:
type: integer
format: int32
minimum: 1
maximum: 50
default: 10
responses:
'200':
description: Success Response
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Chat session fetched successfully
description: Message indicating the status of operation
data:
type: array
items:
$ref: '#/components/schemas/ChatSession'
pagination:
$ref: '#/components/schemas/Pagination'
4XX:
description: Client-side error
content:
application/json:
schema:
$ref: '#/components/schemas/ClientErrorResponse'
5XX:
description: Server-side Error
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
tags:
- Chat
/chat/v1/sessions/{sessionId}/query:
post:
summary: Submit Query
description: Submit a query to a chat session for processing
operationId: submitQuery
parameters:
- name: sessionId
in: path
description: ID of the session linked to this query
schema:
type: string
required: true
requestBody:
content:
application/json:
schema:
type: object
required:
- query
- endpointId
- responseMode
properties:
query:
type: string
description: Actual query
endpointId:
type: string
example: predefined-openai-gpt4o
description: Endpoint ID of the fulfillment model selected to fulffil query. This can be a predefined, BYOI or BYOM model endpoint. You can get a list of all predefined models at [Fulfilllment Models](https://docs.on-demand.io/docs/fulfillment-models#predefined-models). To get a list of BYOI and BYOM models, please refer to [BYOI](https://app.on-demand.io/byoi-management) and [BYOM](https://app.on-demand.io/byom-management/endpoints) respectively.
responseMode:
type: string
description: Response mode to get the query answer
enum:
- sync
- stream
- webhook
pluginIds:
type: array
description: A list of plugin IDs to be made accessible to RAG to answer the query. A maximum of 20 plugins are allowed. This list can be empty. If specified, it will replace the plugin IDs set during session creation. If not specified or left empty, the plugin IDs set during session creation will be utilized. If not specified at any level, the system will bypass the RAG and proceed directly to execute the fulfillment.
maxItems: 20
items:
type: string
fulfillmentOnly:
type: boolean
description: If set to true, skips the RAG and only executes the fulfillment even if `pluginIds` parameter is set at any level. Skipping RAG will also skip the plugins execution so the RAG dependent queries will not be answered correctly.
default: false
modelConfigs:
type: object
description: Sets fulfillment model configuration. If not passed, default configuration will be used to configure the fulfillment model referenced by `endpointId` parameter.
properties:
fulfillmentPrompt:
type: string
description: Prompt providing instructions that guide the model's approach to fulfilling the user's query.
stopSequences:
type: array
description: Up to 4 sequences where the API will stop generating further tokens.
items:
type: string
temperature:
type: number
description: What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or topP but not both.
minimum: 0
maximum: 2
default: 0.7
format: float
topP:
type: number
description: An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with topP probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both.
minimum: 0
maximum: 1
default: 1
format: float
presencePenalty:
type: number
description: Number between 0.0 and 2.0. Higher values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics. Defaults to 0.
minimum: 0
maximum: 2
default: 0
format: float
frequencyPenalty:
type: number
description: Number between 0.0 and 2.0. Higher values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. Defaults to 0.
minimum: 0
maximum: 2
default: 0
format: float
responses:
'200':
description: Sync Mode Response
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Chat query submitted successfully
description: Message indicating the status of operation
data:
type: object
properties:
sessionId:
type: string
example: 668659ddf566ac1d5a44a4ea
description: ID of chat session
messageId:
type: string
example: 668659eaf566ac1d5a44a4eb
description: ID of the chat message
answer:
type: string
example: AI, or Artificial Intelligence, refers to the simulation of human intelligence in machines that are programmed to think and learn like humans. These systems can perform tasks that typically require human intelligence, such as visual perception, speech recognition, decision-making, and language translation. AI can be categorized into narrow AI, which is designed for a specific task, and general AI, which has the potential to perform any intellectual task that a human can do.
description: Answer to the query
status:
type: string
enum:
- processing
- completed
- failed
example: completed
description: Current status of the chat message
4XX:
description: Client-side error
content:
application/json:
schema:
$ref: '#/components/schemas/ClientErrorResponse'
5XX:
description: Server-side Error
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
tags:
- Chat
/chat/v1/sessions/{sessionId}:
get:
summary: Get Chat Session
description: Retrieve a specific chat session
operationId: getChatSession
parameters:
- name: sessionId
in: path
description: ID of the chat session to retrieve
schema:
type: string
required: true
responses:
'200':
description: Success Response
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Chat session fetched successfully
description: Message indicating the status of operation
data:
$ref: '#/components/schemas/ChatSession'
4XX:
description: Client-side error
content:
application/json:
schema:
$ref: '#/components/schemas/ClientErrorResponse'
5XX:
description: Server-side Error
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
tags:
- Chat
/chat/v1/sessions/{sessionId}/messages/{messageId}:
get:
summary: Get Chat Message
description: Retrieve a specific chat message
operationId: getChatMessage
parameters:
- name: sessionId
in: path
description: ID of the chat session linked to the chat message
schema:
type: string
required: true
- name: messageId
in: path
description: ID of the chat message to retrieve
schema:
type: string
required: true
responses:
'200':
description: Success Response
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Chat message fetched successfully
description: Message indicating the status of operation
data:
$ref: '#/components/schemas/ChatMessage'
4XX:
description: Client-side error
content:
application/json:
schema:
$ref: '#/components/schemas/ClientErrorResponse'
5XX:
description: Server-side Error
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
tags:
- Chat
/chat/v1/sessions/{sessionId}/messages:
get:
summary: Get Chat Messages
description: Retrieve messages of a specific chat session
operationId: getChatMessages
parameters:
- name: sessionId
in: path
description: ID of the chat session
schema:
type: string
required: true
- name: externalUserId
in: query
description: Filter the chat messages based on external user
schema:
type: string
- name: sort
in: query
description: Sort order of the messages based on its creation time
schema:
type: string
enum:
- asc
- desc
default: desc
- name: cursor
in: query
description: It acts as a pagination key and used to retrieve next results. For first iteration, this parameter must not be set. For subsequent iterations, it must be set to `pagination.next` value from previous response.
schema:
type: string
- name: limit
in: query
description: Specifies the total number of results to retrieve. If the provided value is less than the minimum allowed limit, it will be reset to the default value. Conversely, if the provided value exceeds the maximum allowed limit, it will be reset to the maximum value.
schema:
type: integer
format: int32
minimum: 1
maximum: 50
default: 10
responses:
'200':
description: Success Response
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Chat messages fetched successfully
description: Message indicating the status of operation
data:
type: array
items:
$ref: '#/components/schemas/ChatMessage'
pagination:
$ref: '#/components/schemas/Pagination'
4XX:
description: Client-side error
content:
application/json:
schema:
$ref: '#/components/schemas/ClientErrorResponse'
5XX:
description: Server-side Error
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
tags:
- Chat
/chat/v1/batches:
post:
summary: Create Chat Batch
description: Submit a batch of chat queries for asynchronous processing
operationId: createChatBatch
requestBody:
content:
multipart/form-data:
schema:
type: object
required:
- name
- file
properties:
name:
type: string
description: Label or name for this batch
file:
type: string
format: binary
description: JSONL file containing one chat query per line. See the [sample batch template file](https://devpoc-f8fbhndjezesfcax.a03.azurefd.net/templates/batch-template.jsonl). The maximum allowed file size is **50MB**. The batch must not contain more than **1000** queries.
responses:
'200':
description: Success Response
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Chat batch created and is being processed
description: Message indicating the status of operation
data:
type: object
properties:
batchId:
type: string
description: Unique identifier of the created batch
example: 67e3e0766643f7771e78686e
status:
type: string
description: Always “processing” on creation
example: processing
totalQueries:
type: integer
description: Number of queries in the batch
example: 2
4XX:
description: Client-side error
content:
application/json:
schema:
$ref: '#/components/schemas/ClientErrorResponse'
5XX:
description: Server-side Error
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
tags:
- Chat
get:
summary: Get Chat Batches
description: Retrieve chat batches
operationId: getChatBatches
parameters:
- name: status
in: query
description: Filter batches by status
schema:
type: string
enum:
- processing
- completed
- failed
- name: search
in: query
description: Filter batches by partial match on name (case-insensitive)
schema:
type: string
- name: sort
in: query
description: Sort order of the batches based on its creation time
schema:
type: string
enum:
- asc
- desc
default: desc
- name: cursor
in: query
description: It acts as a pagination key and used to retrieve next results. For first iteration, this parameter must not be set. For subsequent iterations, it must be set to `pagination.next` value from previous response.
schema:
type: string
- name: limit
in: query
description: Specifies the total number of results to retrieve. If the provided value is less than the minimum allowed limit, it will be reset to the default value. Conversely, if the provided value exceeds the maximum allowed limit, it will be reset to the maximum value.
schema:
type: integer
format: int32
minimum: 1
maximum: 50
default: 10
responses:
'200':
description: Success Response
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Chat batches fetched successfully
description: Message indicating the status of operation
data:
type: array
items:
$ref: '#/components/schemas/ChatBatch'
pagination:
$ref: '#/components/schemas/Pagination'
4XX:
description: Client-side error
content:
application/json:
schema:
$ref: '#/components/schemas/ClientErrorResponse'
5XX:
description: Server-side Error
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
tags:
- Chat
/chat/v1/batches/{batchId}:
get:
summary: Get Chat Batch
description: Retrieve a specific chat batch
operationId: getChatBatch
parameters:
- name: batchId
in: path
description: ID of the chat batch to retrieve
schema:
type: string
required: true
responses:
'200':
description: Success Response
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Chat batch deleted successfully
description: Message indicating the status of operation
data:
$ref: '#/components/schemas/ChatBatch'
4XX:
description: Client-side error
content:
application/json:
schema:
$ref: '#/components/schemas/ClientErrorResponse'
5XX:
description: Server-side Error
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
tags:
- Chat
delete:
summary: Delete Chat Batch
description: Delete a specific chat batch
operationId: deleteChatBatch
parameters:
- name: batchId
in: path
description: ID of the chat batch to delete
schema:
type: string
required: true
responses:
'200':
description: Success Response
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Chat batch deleted successfully
description: Message indicating the status of operation
4XX:
description: Client-side error
content:
application/json:
schema:
$ref: '#/components/schemas/ClientErrorResponse'
5XX:
description: Server-side Error
content:
application/json:
schema:
$ref: '#/components/schemas/ServerErrorResponse'
tags:
- Chat
components:
schemas:
ChatMessage:
type: object
properties:
id:
type: string
example: 662a54c06d0a0a1bd84ee19f
description: ID of chat message
sessionId:
type: string
example: 662a3f736d0a0a1bd84ee19a
description: ID of chat session
companyId:
type: string
example: 6629c6bb4733922ce5efc543
description: ID of the company linked to chat session
externalUserId:
type: string
example: 06931013-9ae4-449d-87e8-4224508ba0d0
description: ID of the external user
pluginIds:
type: array
items:
type: string
example: plugin-1813954526
description: ID of plugin
description: List of plugins associated with the chat message
endpointId:
type: string
example: predefined-openai-gpt4o
description: ID of the endpoint used to fulfill the query
responseMode:
type: string
enum:
- sync
- stream
- webhook
example: sync
description: Response mode used to retrieve the query answer
status:
type: string
enum:
- processing
- completed
- failed
example: completed
description: Current status of the chat message
type:
type: string
enum:
- text
- media
example: text
description: Type of the chat message
media:
type: object
description: Media content of the chat message. Only set when message type is media
example: {}
properties:
id:
type: string
example: 662a54c06d0a0a1bd84ee15f
description: ID of the media
name:
type: string
example: Summer Chats
description: Name of the media
source:
type: string
enum:
- document
- video
- audio
- youtube
- image
example: doucment
description: Source of the media
url:
type: string
example: https://example.com/media/summer-chat.docx
description: URL of the media content
context:
type: string
example: The conversation takes place between two individuals, John and Yumi. They are discussing the hot weather.
description: Context of the media
query:
type: string
example: What is CircleCI. Also share latest news about Afghanistan?
description: User Query. Only set when message type is text
answer:
type: string
example: 'CircleCI is a continuous integration and delivery platform that automates the build, test, and deploy process of software. It allows developers to rapidly release code by automating the build, test, and delivery process. It integrates with GitHub, Bitbucket, and other version control systems, allowing software teams to be more productive and focus on what matters: building great applications.
As for the latest news about Afghanistan, several significant events have occurred. Two powerful earthquakes of magnitude 6.3 followed by several strong aftershocks in western Afghanistan resulted in the death of more than 2,000 people. The ruling government, run by the Taliban, has performed a double public execution of two convicted men at a stadium in southeastern Afghanistan. There''s also the ongoing conflict with the Afghan resistance movement, which is struggling against the Taliban''s military might. In sports news, New Zealand recently had a significant victory over Afghanistan in the Cricket World Cup.'
description: Answer to the query. Only set when message type is text
createdBy:
type: string
example: 6629c6bb4733922ce5efc544
description: ID of the company user created the chat message
createdAt:
type: string
example: '2024-04-25T13:04:00.79Z'
description: Timestamp when the chat message was created
updatedAt:
type: string
example: '2024-04-25T13:04:17.097Z'
description: Timestamp when the chat message was last updated
ServerErrorResponse:
type: object
properties:
errorCode:
type: string
description: Application-specific error code
example: server_error
message:
type: string
description: Human-readable error message
example: Internal server error
ClientErrorResponse:
type: object
properties:
errorCode:
type: string
description: Application-specific error code
example: invalid_request
message:
type: string
description: Human-readable error message
example: Invalid request parameters
ChatSession:
type: object
properties:
id:
type: string
example: 662a0a7c4fe356d0a3aa60d3
description: ID of chat session
companyId:
type: string
example: 6629c6bb4733922ce5efc543
description: ID of the company linked to chat session
externalUserId:
type: string
example: 06931013-9ae4-449d-87e8-4224508ba0d0
description: ID of the external user
pluginIds:
type: array
items:
type: string
example: plugin-1813954526
description: ID of plugin
description: List of plugins associated with the chat session
title:
type: string
example: Latest news about Afghanistan
description: A short user-friendly title for the chat session. It is automatically generated by OnDemand when the first query is submitted in the session. If not generated yet, it will be empty
createdBy:
type: string
example: 6629c6bb4733922ce5efc544
description: ID of the company user created the chat session
createdAt:
type: string
example: '2024-04-25T07:47:08.201467423Z'
description: Timestamp when the chat session was created
updatedAt:
type: string
example: '2024-04-25T07:47:08.201467477Z'
description: Timestamp when the chat session was last updated
ChatBatch:
type: object
properties:
id:
type: string
example: 67e3e0766643f7771e78686e
description: ID of the chat batch
companyId:
type: string
example: 6629c6bb4733922ce5efc543
description: ID of the company linked to batch
name:
type: string
example: Sample Batch
description: Label or name for this batch
status:
type: string
enum:
- processing
- completed
- failed
example: completed
description: Current status of the batch
fileUrl:
type: string
format: uri
example: https://example.com/batch-queries-eab6juvuwq8exlqjjhtl.jsonl
description: URL to download the batch file containing queries
resultsFileUrl:
type: string
format: uri
example: https://example.com/batch-results-eab6juvuwq8exlqjjhtl.jsonl
description: URL to download the results file containing processed queries
processingAt:
type: string
format: date-time
example: '2025-03-26T11:20:12.915Z'
description: Timestamp when the batch processing started
completedAt:
type: string
format: date-time
example: '2025-03-26T11:30:12.915Z'
description: Timestamp when the batch processing completed. Only present if status is `completed`
failedAt:
type: string
format: date-time
nullable: true
description
# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ondemand/refs/heads/main/openapi/ondemand-chat-api-openapi.yml