ContextQMD
Back to Openviking

Privacy Configs

docs/en/api/10-privacy.md

0.3.148.1 KB
Original Source

Privacy Configs

Privacy configs manage sensitive values by category + target_key (for example, a skill's api_key and base_url).

Each update creates a version snapshot. You can query history and switch the active version.

Endpoint Summary

MethodPathDescription
GET/api/v1/privacy-configsList privacy config categories
GET/api/v1/privacy-configs/{category}List targets under a category
GET/api/v1/privacy-configs/{category}/{target_key}Get active config (meta + current)
POST/api/v1/privacy-configs/{category}/{target_key}Upsert and activate a new/current version
GET/api/v1/privacy-configs/{category}/{target_key}/versionsList version numbers
GET/api/v1/privacy-configs/{category}/{target_key}/versions/{version}Get a specific version snapshot
POST/api/v1/privacy-configs/{category}/{target_key}/activateActivate a specific version

Detailed sections are below.

Common Use Cases

  • Store sensitive settings for a skill
  • Rotate keys by writing a new version
  • Roll back to an old version
  • Restore placeholders in skill content at read time

Data Structures

current (active version snapshot)

json
{
  "version": 3,
  "category": "skill",
  "target_key": "byted-viking-search-knowledgebase",
  "values": {
    "api_key": "***",
    "base_url": "https://example.com"
  },
  "created_at": "2026-04-27T10:00:00+08:00",
  "created_by": "alice",
  "change_reason": "rotate key"
}

meta

json
{
  "category": "skill",
  "target_key": "byted-viking-search-knowledgebase",
  "active_version": 3,
  "latest_version": 5,
  "created_at": "2026-04-21T10:00:00+08:00",
  "updated_at": "2026-04-27T10:00:00+08:00",
  "updated_by": "alice",
  "last_accessed_at": "2026-04-27T10:00:00+08:00",
  "labels": {
    "env": "prod"
  }
}

API Reference

list_privacy_categories()

List categories that have privacy configs for the current user.

HTTP API

GET /api/v1/privacy-configs
bash
curl -X GET http://localhost:1933/api/v1/privacy-configs \
  -H "X-API-Key: your-key" \
  -H "X-OpenViking-Account: default" \
  -H "X-OpenViking-User: alice"

Response

json
{
  "status": "ok",
  "result": ["skill"],
  "time": 0.01
}

list_privacy_targets()

List target keys under a category.

HTTP API

GET /api/v1/privacy-configs/{category}
bash
curl -X GET http://localhost:1933/api/v1/privacy-configs/skill \
  -H "X-API-Key: your-key" \
  -H "X-OpenViking-Account: default" \
  -H "X-OpenViking-User: alice"

Response

json
{
  "status": "ok",
  "result": ["byted-viking-search-knowledgebase"],
  "time": 0.01
}

get_privacy_current()

Get active config for a target (meta + current).

HTTP API

GET /api/v1/privacy-configs/{category}/{target_key}
bash
curl -X GET "http://localhost:1933/api/v1/privacy-configs/skill/byted-viking-search-knowledgebase" \
  -H "X-API-Key: your-key" \
  -H "X-OpenViking-Account: default" \
  -H "X-OpenViking-User: alice"

Response

json
{
  "status": "ok",
  "result": {
    "meta": {
      "category": "skill",
      "target_key": "byted-viking-search-knowledgebase",
      "active_version": 3,
      "latest_version": 5
    },
    "current": {
      "version": 3,
      "category": "skill",
      "target_key": "byted-viking-search-knowledgebase",
      "values": {
        "api_key": "***",
        "base_url": "https://example.com"
      }
    }
  },
  "time": 0.01
}

Returns NOT_FOUND if the target does not exist.

upsert_privacy_config()

Write a new version and set it as active.

Behavior

  • values is written as a full snapshot for that version
  • New keys are allowed and persisted
  • If values is identical to the current version, no new version is created

HTTP API

POST /api/v1/privacy-configs/{category}/{target_key}

Request Body

FieldTypeRequiredDefaultDescription
valuesobjectYes-Privacy key-value pairs
change_reasonstringNo""Reason for change
labelsobjectNonullLabels stored in meta
bash
curl -X POST "http://localhost:1933/api/v1/privacy-configs/skill/byted-viking-search-knowledgebase" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -H "X-OpenViking-Account: default" \
  -H "X-OpenViking-User: alice" \
  -d '{
    "values": {
      "api_key": "secret-2",
      "base_url": "https://example.com",
      "region": "cn"
    },
    "change_reason": "rotate key",
    "labels": {
      "env": "prod"
    }
  }'

Response

json
{
  "status": "ok",
  "result": {
    "version": 4,
    "category": "skill",
    "target_key": "byted-viking-search-knowledgebase",
    "values": {
      "api_key": "secret-2",
      "base_url": "https://example.com",
      "region": "cn"
    },
    "change_reason": "rotate key"
  },
  "time": 0.02
}

list_privacy_versions()

List all version numbers for a target.

HTTP API

GET /api/v1/privacy-configs/{category}/{target_key}/versions
bash
curl -X GET "http://localhost:1933/api/v1/privacy-configs/skill/byted-viking-search-knowledgebase/versions" \
  -H "X-API-Key: your-key" \
  -H "X-OpenViking-Account: default" \
  -H "X-OpenViking-User: alice"

Response

json
{
  "status": "ok",
  "result": [1, 2, 3, 4],
  "time": 0.01
}

Returns NOT_FOUND if the target does not exist.

get_privacy_version()

Get one version snapshot.

HTTP API

GET /api/v1/privacy-configs/{category}/{target_key}/versions/{version}
bash
curl -X GET "http://localhost:1933/api/v1/privacy-configs/skill/byted-viking-search-knowledgebase/versions/2" \
  -H "X-API-Key: your-key" \
  -H "X-OpenViking-Account: default" \
  -H "X-OpenViking-User: alice"

Response

json
{
  "status": "ok",
  "result": {
    "version": 2,
    "category": "skill",
    "target_key": "byted-viking-search-knowledgebase",
    "values": {
      "api_key": "secret-1",
      "base_url": "https://example.com"
    }
  },
  "time": 0.01
}

Returns NOT_FOUND if target/version does not exist.

activate_privacy_version()

Switch active version.

HTTP API

POST /api/v1/privacy-configs/{category}/{target_key}/activate

Request Body

FieldTypeRequiredDescription
versionintYesVersion number to activate
bash
curl -X POST "http://localhost:1933/api/v1/privacy-configs/skill/byted-viking-search-knowledgebase/activate" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -H "X-OpenViking-Account: default" \
  -H "X-OpenViking-User: alice" \
  -d '{"version": 2}'

Response

json
{
  "status": "ok",
  "result": {
    "version": 2,
    "category": "skill",
    "target_key": "byted-viking-search-knowledgebase",
    "values": {
      "api_key": "secret-1",
      "base_url": "https://example.com"
    }
  },
  "time": 0.01
}

Returns NOT_FOUND if target/version does not exist.

CLI Quick Operations

bash
# Categories and targets
openviking privacy categories
openviking privacy list skill

# Active config (shortcut supported)
openviking privacy get skill byted-viking-search-knowledgebase
openviking privacy skill byted-viking-search-knowledgebase

# Upsert with full JSON snapshot
openviking privacy upsert skill byted-viking-search-knowledgebase \
  --values-json '{"api_key":"secret-2","base_url":"https://example.com"}'

# Partial key update (CLI merges with current first)
openviking privacy upsert skill byted-viking-search-knowledgebase \
  --key-api_key secret-3

# Version query and activation
openviking privacy versions skill byted-viking-search-knowledgebase
openviking privacy version skill byted-viking-search-knowledgebase 2
openviking privacy activate skill byted-viking-search-knowledgebase 2