Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

7.2 KB
Raw Blame

VikingBot API

When OpenViking Server starts with --with-bot, it proxies VikingBot's core interaction endpoints below /bot/v1. These endpoints return 503 when Bot is not enabled.

Code entry points:

  • openviking/server/routers/bot.py - OpenViking Server proxy and identity forwarding
  • bot/vikingbot/channels/openapi.py - VikingBot Gateway routes
  • bot/vikingbot/channels/openapi_models.py - request, response, and SSE event models

API Reference

health()

Check whether the Bot Gateway is available.

HTTP API

curl http://localhost:1933/bot/v1/health

Response Example

{
  "status": "healthy",
  "version": "0.1.0",
  "timestamp": "2026-07-24T09:00:00"
}

chat()

Send text and/or images and wait for the complete reply. Omit session_id to create a new session.

Field Type Required Default Description
message string Conditional "" User text; required when images is empty
images array Conditional [] Up to four OpenAI-style image_url parts; required when message is empty
session_id string No Generated Existing session to continue
context array No null Additional messages containing role and content
need_reply boolean No true Whether the Bot should reply
disabled_tools string[] No [] Tool names disabled for this request
channel_id string No null Multi-channel routing identifier

HTTP API

curl -X POST http://localhost:1933/bot/v1/chat \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{"message":"Summarize my project progress","session_id":"optional-session-id"}'

Images may use an accessible HTTPS URL or an inline Base64 data URL:

curl -X POST http://localhost:1933/bot/v1/chat \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{
    "message": "Describe this image",
    "images": [{
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/photo.png"
      }
    }]
  }'

Inline Base64 images support JPEG, PNG, GIF, and WebP. Each decoded inline image is limited to 10 MiB; inline SVG and mismatched MIME signatures are rejected. For HTTPS URLs, the Gateway validates the URL structure but does not fetch or inspect the remote resource, so remote format support and related errors are provider-specific. Local filesystem paths are rejected. The optional detail field accepts auto, low, or high; omit it for maximum provider compatibility.

CLI

ov chat streams by default through /chat/stream.

ov chat -m "Summarize my project progress"

Response Example

{
  "session_id": "session-id",
  "response_id": "response-id",
  "message": "Here is the current project summary…",
  "events": null,
  "relevant_memories": null,
  "token_usage": {
    "prompt_tokens": 120,
    "completion_tokens": 42,
    "total_tokens": 162
  },
  "timestamp": "2026-07-24T09:00:00"
}

chat_stream()

Return reasoning, tool calls, content deltas, and the final response as Server-Sent Events. The request fields are the same as chat(); the Gateway enables streaming automatically.

HTTP API

curl -N -X POST http://localhost:1933/bot/v1/chat/stream \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{"message":"Analyze the current knowledge base"}'

CLI

ov chat -m "Analyze the current knowledge base"

SSE Response Example

Each message uses data: <json> format. The X-VikingBot-Session-ID response header contains the session ID.

data: {"event":"reasoning_delta","data":"Inspecting the knowledge base…","timestamp":"2026-07-24T09:00:00"}

data: {"event":"content_delta","data":"The knowledge base contains","timestamp":"2026-07-24T09:00:01"}

data: {"event":"response","data":{"content":"The knowledge base contains…","response_id":"response-id"},"timestamp":"2026-07-24T09:00:02"}

event can be reasoning, reasoning_delta, tool_call, tool_result, content_delta, iteration, or response.

feedback()

Submit explicit feedback for an existing assistant response.

Field Type Required Description
session_id string Yes Session containing the target response
response_id string Yes Target assistant response ID
feedback_type string Yes thumb_up, thumb_down, or rating
feedback_score number Conditional Required when feedback_type=rating
feedback_reason string No Feedback reason label
feedback_text string No Free-form feedback
channel_id string No Multi-channel routing identifier

HTTP API

curl -X POST http://localhost:1933/bot/v1/feedback \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{
    "session_id":"session-id",
    "response_id":"response-id",
    "feedback_type":"thumb_up"
  }'

Response Example

{
  "accepted": true,
  "response_id": "response-id",
  "session_id": "session-id",
  "feedback_type": "thumb_up",
  "feedback_delay_sec": 8.42,
  "timestamp": "2026-07-24T09:00:08"
}

A missing target response returns 404. Rating feedback without feedback_score returns a request validation error.

interrupt_session()

Interrupt an active or queued Bot session. OpenViking forwards the authenticated Account and User identity to the local VikingBot Gateway.

POST /bot/v1/sessions/{session_id}/interrupt

HTTP API

curl -X POST http://localhost:1933/bot/v1/sessions/session-id/interrupt \
  -H "X-API-Key: your-key"

Response Example

The response body is forwarded from VikingBot. A typical response is:

{
  "interrupted": true
}

steer_session()

Append user input to an active streaming Bot session. OpenViking strips any client-supplied openviking_connection and attaches the authenticated OpenViking connection before forwarding the request.

POST /bot/v1/sessions/{session_id}/steer
Content-Type: application/json
Field Type Required Description
message string Yes Additional user input for the active session
openviking_connection object No Ignored when supplied by the client; OpenViking attaches the authenticated connection

HTTP API

curl -X POST http://localhost:1933/bot/v1/sessions/session-id/steer \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{"message":"Continue with the next step"}'

Response Example

The response body is forwarded from VikingBot. A typical response is:

{
  "accepted": true
}

Client Scope

The standard OpenViking Python, TypeScript, and Go SDKs do not currently wrap the Bot proxy. Chat is available through the ov CLI and HTTP. The VikingBot Gateway also exposes Session and Channel APIs; see the VikingBot documentation.

Related Documentation