Skip to main content
POST
/
api
/
v1
/
sessions
/
{session_id}
/
messages
Add Message
curl --request POST \
  --url https://api.example.com/api/v1/sessions/{session_id}/messages \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <x-api-key>' \
  --data '
{
  "role": "<string>",
  "content": "<string>",
  "parts": [
    {
      "type": "<string>",
      "text": "<string>",
      "uri": "<string>",
      "context_type": "<string>",
      "abstract": "<string>",
      "tool_id": "<string>",
      "tool_name": "<string>",
      "skill_uri": "<string>",
      "tool_input": {},
      "tool_output": "<string>",
      "tool_status": "<string>"
    }
  ]
}
'
{
  "status": "<string>",
  "result": {
    "session_id": "<string>",
    "message_count": 123
  },
  "time": 123
}

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/volcengine/OpenViking/llms.txt

Use this file to discover all available pages before exploring further.

Add user or assistant messages to track conversation flow. Supports both simple text messages and structured messages with multiple parts (text, context references, tool calls).

​
Request

​
Path Parameters

​
session_id
string
required
The session ID to add the message to

​
Headers

​
X-API-Key
string
required
Your OpenViking API key for authentication
​
Content-Type
string
default:"application/json"
Must be application/json

​
Body Parameters

​
role
string
required
Message role: user or assistant
​
content
string
Simple text content (backward compatible mode). Mutually exclusive with parts.
​
parts
array
Array of message parts for structured messages (text, context, tool). If both content and parts are provided, parts takes precedence.
​
type
string
required
Part type: text, context, or tool
For text parts:
​
text
string
required
Text content
For context parts:
​
uri
string
required
Viking URI of the context (e.g., viking://resources/docs/auth/)
​
context_type
string
default:"memory"
Type of context: memory, resource, or skill
​
abstract
string
Brief description of the context
For tool parts:
​
tool_id
string
Unique tool call identifier
​
tool_name
string
Name of the tool being called
​
skill_uri
string
URI of the skill providing the tool
​
tool_input
object
Input parameters for the tool
​
tool_output
string
Tool execution output
​
tool_status
string
default:"pending"
Execution status: pending, running, completed, or error

​
Response

​
status
string
Response status (ok or error)
​
result
object
Add message result
​
session_id
string
The session ID
​
message_count
number
Total number of messages in the session
​
time
number
Request processing time in seconds

​
Examples

​
Simple Text Message

# Add user message
curl -X POST http://localhost:1933/api/v1/sessions/a1b2c3d4/messages \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "role": "user",
    "content": "How do I authenticate users?"
  }'

​
Message with Context Reference

curl -X POST http://localhost:1933/api/v1/sessions/a1b2c3d4/messages \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "role": "assistant",
    "parts": [
      {
        "type": "text",
        "text": "Based on the authentication guide..."
      },
      {
        "type": "context",
        "uri": "viking://resources/docs/auth/",
        "context_type": "resource",
        "abstract": "OAuth 2.0 implementation guide"
      }
    ]
  }'

​
Message with Tool Call

curl -X POST http://localhost:1933/api/v1/sessions/a1b2c3d4/messages \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "role": "assistant",
    "parts": [
      {
        "type": "text",
        "text": "Let me search for that information..."
      },
      {
        "type": "tool",
        "tool_id": "call_123",
        "tool_name": "search_web",
        "skill_uri": "viking://skills/search-web/",
        "tool_input": {"query": "OAuth best practices"},
        "tool_output": "Found 5 results...",
        "tool_status": "completed"
      }
    ]
  }'

​
Response Example

{
  "status": "ok",
  "result": {
    "session_id": "a1b2c3d4",
    "message_count": 3
  },
  "time": 0.1
}

​
Message Roles

  • user - Messages from the end user
  • assistant - Messages from the AI assistant

​
Part Types

​
Text Part

Simple text content: 
TextPart(text="Your message here")

​
Context Part

Reference to a resource, memory, or skill: 
ContextPart(
    uri="viking://resources/docs/auth/",
    context_type="resource",  # "resource", "memory", or "skill"
    abstract="Brief description"
)

​
Tool Part

Tool execution record: 
ToolPart(
    tool_id="call_123",
    tool_name="search_web",
    skill_uri="viking://skills/search-web/",
    tool_input={"query": "search term"},
    tool_output="Results...",
    tool_status="completed"  # "pending", "running", "completed", "error"
)

​
Best Practices

​
Always Track Context Usage

# Search for context
results = client.search(query, session=session)

# Add message with context
session.add_message("assistant", [
    TextPart(text="Based on the docs..."),
    ContextPart(uri=results.resources[0].uri, context_type="resource")
])

# Mark context as actually used
session.used(contexts=[results.resources[0].uri])

​
Structure Messages Properly

Use parts for rich messages instead of mixing everything into text: 
# Good: Structured with parts
session.add_message("assistant", [
    TextPart(text="Here's the solution:"),
    ContextPart(uri="viking://resources/solution.md", context_type="resource")
])

# Avoid: Mixing URIs in text
session.add_message("assistant", [
    TextPart(text="See viking://resources/solution.md for details")
])

Build docs developers (and LLMs) love

Get started for freeTalk to us