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

Method	Path	Description
GET	/api/v1/privacy-configs	List 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}/versions	List 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}/activate	Activate 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)

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

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

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

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

---

list_privacy_targets()

List target keys under a category.

HTTP API

GET /api/v1/privacy-configs/{category}

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

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

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

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

Field	Type	Required	Default	Description
values	object	Yes	-	Privacy key-value pairs
change_reason	string	No	""	Reason for change
labels	object	No	null	Labels stored in meta

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

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

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

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

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

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

Field	Type	Required	Description
version	int	Yes	Version number to activate

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

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

# 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

---

Related Documentation

• Skills - Skill write/read APIs
• File System - read/write/ls
• System - System status and observability