Mindview API

Fetches the conversation context used to build responses, either from a stored session or from the current character setup.

This API is available only on the Professional Plan and above.

Get Prompt For Mindview

POST https://api.convai.com/character/chatHistory/get_prompt

Fetches prompt data for MindView in one of two ways:

1. Session mode (session_id): reads prompt data from stored interaction records.
2. Character mode (character_id only): generates static prompt data from current character configuration.

Headers

Name	Type	Description
CONVAI-API-KEY*	String	The unique api-key provided for every user. Found under the Key icon when logged into your Convai account.

Request Body

Name	Type	Description
session_id	String	Session identifier. If provided, API runs in session mode.
character_id	String	Character identifier. Used when session_id is not provided.
offset	Integer	Optional. Used only with session_id. Default -1 returns latest prompt record.

At least one of session_id or character_id is required.

200: OK (Session mode response)

{
  "prompt_id": "f2f8a75e-...",
  "prompt": "[{\"role\":\"system\",\"content\":\"...\"}]",
  "model": "gpt-4o-mini",
  "temperature": 0.7,
  "max_tokens": 512,
  "top_p": 1.0,
  "frequency_penalty": 0.0,
  "presence_penalty": 0.0,
  "stop": null,
  "session_id": "sess_123",
  "mindview": "{\"static_prompt\": {...}, \"dynamic_prompt\": {...}}"
}

200: OK (Character mode response)

{
  "mindview": "{\"static_prompt\": {...}, \"dynamic_prompt\": {...}}",
  "model": "gpt-4o-mini"
}

400: Bad Request

{
  "ERROR": "Either session_id or character_id is required",
  "Reference ID": "<transaction_id>"
}

{
  "ERROR": "offset must be a valid integer",
  "Reference ID": "<transaction_id>"
}

{
  "ERROR": "Offset is greater than the number of records",
  "Reference ID": "<transaction_id>"
}

Here are some sample codes to demonstrate the request format for the endpoint -->

Session Mode (session_id)

Python

import json
import requests

url = "https://api.convai.com/character/chatHistory/get_prompt"

headers = {
    "CONVAI-API-KEY": "<Your-API-Key>",
    "Content-Type": "application/json"
}

payload = {
    "session_id": "<Your-Session-ID>",
    "offset": -1
}

response = requests.post(url, headers=headers, data=json.dumps(payload))
print(response.text)

cURL

curl -X POST "https://api.convai.com/character/chatHistory/get_prompt" \
  -H "CONVAI-API-KEY: <Your-API-Key>" \
  -H "Content-Type: application/json" \
  -d '{"session_id":"<Your-Session-ID>","offset":-1}'

Character Mode (character_id)

Python

import json
import requests

url = "https://api.convai.com/character/chatHistory/get_prompt"

headers = {
    "CONVAI-API-KEY": "<Your-API-Key>",
    "Content-Type": "application/json"
}

payload = {
    "character_id": "<Your-Character-ID>"
}

response = requests.post(url, headers=headers, data=json.dumps(payload))
print(response.text)

cURL

curl -X POST "https://api.convai.com/character/chatHistory/get_prompt" \
  -H "CONVAI-API-KEY: <Your-API-Key>" \
  -H "Content-Type: application/json" \
  -d '{"character_id":"<Your-Character-ID>"}'

Implementation notes:

• If both session_id and character_id are provided, session mode is used.
• In current implementation, mindview and prompt fields are serialized JSON strings.