Mindview API

Learn how to use the Backstory API to create and manage character backstories, adding depth and personality to your NPCs.

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)

400: Bad Request

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

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

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.