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

Path parameters

application/json

Body

  • content string Required

    Content of the message must be between 1 and 10000 characters.

    Minimum length is 1, maximum length is 10000.

  • 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

Responses

  • 200

    List of chat messages had with a replica by the current user, including the completion

    Hide response attributes Show response attributes object
    Hide response attributes Show response attributes object
  • 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
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) 
{
  "success": true,
  "error": "string",
  "fingerprint": "14fceadd84e74ec499afe9b0f7952d6b",
  "request_id": "xyz1::reg1:reg1::ab3c4-1234567890123-0123456789ab"
}
Response examples (401) 
{
  "success": true,
  "error": "string",
  "fingerprint": "14fceadd84e74ec499afe9b0f7952d6b",
  "request_id": "xyz1::reg1:reg1::ab3c4-1234567890123-0123456789ab"
}
Response examples (404) 
{
  "success": true,
  "error": "string",
  "request_id": "xyz1::reg1:reg1::ab3c4-1234567890123-0123456789ab"
}
Response examples (415) 
{
  "success": true,
  "error": "string",
  "fingerprint": "14fceadd84e74ec499afe9b0f7952d6b",
  "request_id": "xyz1::reg1:reg1::ab3c4-1234567890123-0123456789ab"
}
Response examples (500) 
{
  "success": true,
  "error": "string",
  "fingerprint": "14fceadd84e74ec499afe9b0f7952d6b",
  "request_id": "xyz1::reg1:reg1::ab3c4-1234567890123-0123456789ab",
  "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"
  }
}