OpenViking Assets Resolver

The OpenViking Assets Resolver parses and validates an openviking-assets/1 Manifest — either self-contained, with assets defined under its catalog field, or paired with a separate Catalog file — then returns a normalized asset plan for a client to execute. It does not clone repositories, create resources, or start synchronization jobs.

In normal use, run ov add-resource --manifest <file>; the CLI calls the Resolver and permission-preflight endpoints automatically. Call these endpoints directly only when implementing a custom client.

Resolve a Manifest

POST /api/v1/openviking-assets/resolve

Authentication

The endpoint uses the standard OpenViking Server authentication mechanism. When API-key authentication is enabled, include:

X-API-Key: <your-api-key>

Request body

Field	Type	Required	Default	Description
manifest_yaml	string	Yes	—	Complete Manifest YAML, 1–4,000,000 characters
catalog_yaml	string	No	—	Complete Catalog YAML, 1–4,000,000 characters. Required when the Manifest selects assets by name; must be omitted when the Manifest defines assets under catalog.
manifest_label	string	No	manifest.yaml	Manifest source label used in errors, 1–1,024 characters
catalog_label	string	No	catalog.yaml	Catalog source label used in errors, 1–1,024 characters

Example with a self-contained Manifest:

curl -X POST "${OPENVIKING_BASE_URL}/api/v1/openviking-assets/resolve" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ${OPENVIKING_API_KEY}" \
  --data-binary @- <<'JSON'
{
  "manifest_yaml": "protocol: openviking-assets/1\ncatalog:\n  - name: openviking\n    connector: git\n    watch_interval: 1440\n    params:\n      repo_url: https://github.com/volcengine/OpenViking\n      branch: main\n",
  "manifest_label": "manifest.yaml"
}
JSON

When a Manifest selects assets by name, send the Catalog YAML in catalog_yaml and its label in catalog_label.

Success response

{
  "status": "ok",
  "result": {
    "protocol": "openviking-assets/1",
    "manifest": "manifest.yaml",
    "catalog": "manifest.yaml",
    "assets": [
      {
        "name": "openviking",
        "connector": "git",
        "repo_url": "https://github.com/volcengine/OpenViking",
        "branch": "main",
        "auth_ref": null,
        "watch_interval": 1440.0,
        "locator": "github.com/volcengine/OpenViking",
        "git_ref": "main",
        "asset_id": "a1b2c3d4e5f6"
      }
    ]
  }
}

Where:

• locator is the normalized repository locator.
• git_ref is the resolved Git reference.
• asset_id is a stable 12-character identifier derived from the connector, normalized locator, and Git reference. The value above illustrates the format.
• watch_interval is measured in minutes.
• catalog echoes catalog_label; for a self-contained Manifest it equals the Manifest label.

Error responses

Protocol or content validation failures return HTTP 400 with the error code INVALID_ARGUMENT. Common causes include:

• malformed YAML or unknown fields;
• a protocol other than openviking-assets/1, or a Manifest that defines catalog without declaring protocol;
• a non-empty include, which v1 does not support;
• a Manifest that defines catalog submitted together with catalog_yaml;
• a Manifest that selects assets by name without any catalog_yaml;
• a Manifest referencing an asset absent from the Catalog;
• an invalid connector, repository URL, Git reference, or asset identity;
• duplicate asset identities in one Manifest.

Empty fields, incorrect field types, or length-limit violations are rejected by request validation with HTTP 422.

Preflight Git repository access

POST /api/v1/openviking-assets/preflight

This endpoint runs read-only git ls-remote in the OpenViking Server execution environment to verify that a repository and optional ref are readable. It does not clone the repository, create a resource, or start a task. Manifest mode calls it during both dry-run and pre-submission validation.

Request body

Field	Type	Required	Description
name	string	Yes	Asset name
connector	string	Yes	Must currently be git
repo_url	string	Yes	Git clone URL
branch	string	No	Branch or tag to verify; the remote HEAD is checked when omitted
auth_config.username	string	No	HTTP Basic username; defaults to oauth2
auth_config.token	string	No	One-shot Git token; never persisted

curl -X POST "${OPENVIKING_BASE_URL}/api/v1/openviking-assets/preflight" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ${OPENVIKING_API_KEY}" \
  -d '{
    "name": "private-repository",
    "connector": "git",
    "repo_url": "https://github.com/example/private-repository",
    "branch": "main",
    "auth_config": {
      "username": "oauth2",
      "token": "<github-token>"
    }
  }'

When a token is provided explicitly, preflight does not fall back to a server Git credential helper. The token is passed through the child-process environment and does not appear in Git command arguments or the response.

Success response

{
  "status": "ok",
  "result": {
    "name": "private-repository",
    "connector": "git",
    "locator": "github.com/example/private-repository",
    "git_ref": "main",
    "accessible": true
  }
}

Error responses

HTTP status	Error code	Meaning
403	PERMISSION_DENIED	Repository missing, invalid credentials, or insufficient read permission
404	NOT_FOUND	Repository is readable, but the requested branch/tag is absent
503	UNAVAILABLE	DNS, connection, or Git executable unavailable
504	DEADLINE_EXCEEDED	Permission preflight exceeded 15 seconds

Related documentation

• OpenViking Assets protocol and operations guide
• Resource Management API