Generate a completion

POST /v1/replicas/{replicaUUID}/chat/completions

Organization service token & User Organization service token

Ask for a completion and stores the prompt in the chat history.

Replica chat supports two response formats: streamed and JSON. To switch between these formats, use the 'Accept' header, specifying either 'text/event-stream' for streaming or 'application/json' for JSON. The streamed response honours the Stream Protocol, allowing the use of a number of SDKs, including Vercel AI SDK.

The streamed variant is not specified in the OpenAPI Schema because it is not an OpenAPI endpoint.

Headers

X-API-Version string

Default value is 2025-03-25.

Path parameters

replicaUUID string(uuid) Required

The replica unique identifier (UUID)

application/json

Body

content string Required

The prompt to generate completions for, encoded as a string.

Minimum length is 1, maximum length is 100000.
skip_chat_history boolean

When set to true, historical messages are not used in the context, and the message is not appended to the conversation history, thus it is excluded from all future chat context.

Default value is false.
source string

The place where the conversation is happening, which informs where the message should be saved in the chat history.

Values are discord, telegram, embed, web, or telegram_autopilot.
discord_data object

Discord information about the message

Additional properties are NOT allowed.
Hide discord_data attributes Show discord_data attributes object
- channel_id string Required
  
  Channel ID
- channel_name string Required
  
  Channel name
- author_id string Required
  
  Author ID
- author_name string Required
  
  Author name
- message_id string Required
  
  Message ID
- created_at string
  
  Message creation timestamp
- server_id string
  
  Server ID
- server_name string
  
  Server name

Responses

200

application/json

application/json text/event-stream

List of chat messages had with a replica by the current user, including the completion
Hide response attributes Show response attributes object
- success boolean Required
- content string Required
Hide response attributes Show response attributes object
- success boolean Required
- content string Required
400 application/json

Bad Request
Hide response attributes Show response attributes object
- success boolean Required
  
  Indicates the status of the request
- error string Required
  
  A text representation of the error
- fingerprint string
  
  A unique identifier of the event, useful for reporting
- request_id string Required
  
  A unique identifier of the request, useful for reporting
401 application/json

Unauthorized
Hide response attributes Show response attributes object
- success boolean Required
  
  Indicates the status of the request
- error string Required
  
  A text representation of the error
- fingerprint string
  
  A unique identifier of the event, useful for reporting
- request_id string Required
  
  A unique identifier of the request, useful for reporting
404 application/json

Not Found
Hide response attributes Show response attributes object
- success boolean Required
  
  Indicates the status of the request
- error string Required
  
  A text representation of the error
- request_id string Required
  
  A unique identifier of the request, useful for reporting
415 application/json

Unsupported Media Type
Hide response attributes Show response attributes object
- success boolean Required
  
  Indicates the status of the request
- error string Required
  
  A text representation of the error
- fingerprint string
  
  A unique identifier of the event, useful for reporting
- request_id string Required
  
  A unique identifier of the request, useful for reporting
500 application/json

Internal Server Error
Hide response attributes Show response attributes object
- success boolean Required
  
  Indicates the status of the request
- error string Required
  
  A text representation of the error
- fingerprint string
  
  A unique identifier of the event, useful for reporting
- request_id string Required
  
  A unique identifier of the request, useful for reporting
- inner_exception object
  
  The inner exception
  
  Hide inner_exception attributes Show inner_exception attributes object
  
  name string Required
  
  message string Required
  
  cause string
  
  stack string

POST /v1/replicas/{replicaUUID}/chat/completions

curl \
 --request POST 'https://api.sensay.io/v1/replicas/03db5651-cb61-4bdf-9ef0-89561f7c9c53/chat/completions' \
 --header "X-ORGANIZATION-SECRET: $API_KEY" \
 --header "X-USER-ID: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "X-API-Version: 2025-03-25" \
 --data '{"content":"How did you handle the immense pressure during the Civil War?","skip_chat_history":false,"source":"discord","discord_data":{"channel_id":"string","channel_name":"string","author_id":"string","author_name":"string","message_id":"string","created_at":"string","server_id":"string","server_name":"string"}}'

Request examples

# Headers
X-API-Version: 2025-03-25

# Payload
{
  "content": "How did you handle the immense pressure during the Civil War?",
  "skip_chat_history": false,
  "source": "discord",
  "discord_data": {
    "channel_id": "string",
    "channel_name": "string",
    "author_id": "string",
    "author_name": "string",
    "message_id": "string",
    "created_at": "string",
    "server_id": "string",
    "server_name": "string"
  }
}

Response examples (200)

{
  "content": "I handled the immense pressure during the Civil War by...",
  "success": true
}

Response examples (200)

{"content"=>"I handled the immense pressure during the Civil War by...", "success"=>true}

Response examples (400)

{
  "error": "A text representation of the error",
  "success": false,
  "request_id": "xyz1::reg1:reg1::ab3c4-1234567890123-0123456789ab",
  "fingerprint": "14fceadd84e74ec499afe9b0f7952d6b"
}

Response examples (401)

{
  "error": "A text representation of the error",
  "success": false,
  "request_id": "xyz1::reg1:reg1::ab3c4-1234567890123-0123456789ab",
  "fingerprint": "14fceadd84e74ec499afe9b0f7952d6b"
}

Response examples (404)

{
  "error": "A text representation of the error",
  "success": false,
  "request_id": "xyz1::reg1:reg1::ab3c4-1234567890123-0123456789ab"
}

Response examples (415)

{
  "error": "A text representation of the error",
  "success": false,
  "request_id": "xyz1::reg1:reg1::ab3c4-1234567890123-0123456789ab",
  "fingerprint": "14fceadd84e74ec499afe9b0f7952d6b"
}

Response examples (500)

{
  "error": "A text representation of the error",
  "success": false,
  "request_id": "xyz1::reg1:reg1::ab3c4-1234567890123-0123456789ab",
  "fingerprint": "14fceadd84e74ec499afe9b0f7952d6b",
  "inner_exception": {
    "name": "Server overheated",
    "cause": "Request too complicated",
    "stack": "Error: Server overheated due to an unexpected situation\n    at Object.eval (eval at <anonymous>...",
    "message": "The server overheated due to an unexpected situation"
  }
}