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
}
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")
])