Add Message

Add a message to a session conversation

POST /api/v1/sessions/{session_id}/messages

Add Message

cURL

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

200

{
  "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

cURL

# 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

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

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

Related Endpoints

• Create Session - Create a new session
• Get Session - Retrieve session and messages
• Commit Session - Archive messages and extract memories