---
name: vimond-via-integration
description: Integrate with Vimond VIA — REST API, Management API, Image Service, viewer-facing services, auth, and content workflows.
---

# Vimond VIA integration (Agent Skill)

> Curated guidance for AI coding agents building on **Vimond VIA**. Factual endpoint lists live in generated OpenAPI indexes — load those for schemas; use this file for decisions, gotchas, and where to look first.

**Developer Hub:** https://developer.vimond.com/  
**Discovery manifest:** https://developer.vimond.com/llms.txt

## When to use which API

| You need to… | Start here | OpenAPI / reference |
|--------------|------------|---------------------|
| Back-office catalog, publishing, products, users (legacy REST) | [Getting started with VIA APIs](https://developer.vimond.com/docs/getting-started-with-via-apis/) | Compact index: [vimond-rest-api.llms.md](https://developer.vimond.com/openapi/vimond-rest-api.llms.md) → per-tag slice or [Scalar Vimond REST API](https://developer.vimond.com/reference/vimond-rest-api/) |
| 2.0 platform management (assets, users — not Image Service admin) | Same guides + tenant docs | [management-api.yaml](https://developer.vimond.com/openapi/management-api.yaml), [Scalar Management](https://developer.vimond.com/reference/management-api/) |
| Image URLs for players / websites | [Image service](https://developer.vimond.com/docs/image-service/), [Content images](https://developer.vimond.com/docs/content-images/) | [image-service.llms.md](https://developer.vimond.com/openapi/image-service.llms.md), [Scalar Image Service](https://developer.vimond.com/reference/image-service/) |
| Upload images, image packs, locations, crop | [Image management](https://developer.vimond.com/docs/image-management/) | Admin paths under `/adminAPI/` in [image-service.yaml](https://developer.vimond.com/openapi/image-service.yaml) — **not** in Management API 2.0 |
| Published catalog for apps (assets, categories, lists, EPG) | [Content discovery](https://developer.vimond.com/docs/content-discovery/), [Search APIs](https://developer.vimond.com/docs/search-apis/) | [content-discovery.llms.md](https://developer.vimond.com/openapi/content-discovery.llms.md), [Scalar Content Discovery](https://developer.vimond.com/reference/content-discovery/) |
| Stream URLs / playback (entitlements, DRM) | [Video playback](https://developer.vimond.com/docs/video-playback/), [Play service API](https://developer.vimond.com/docs/video-playback-1-1/) | [play-service.llms.md](https://developer.vimond.com/openapi/play-service.llms.md), [Scalar Play Service](https://developer.vimond.com/reference/play-service/) — use **v2** `POST /api/v2/asset/{id}/play` |
| End-user auth, player analytics | [authentication](/docs/authentication/), [player-session-api](/docs/player-session-api/) | Play response includes `playerEventRequest` template |
| Domain vocabulary (publisher vs company, asset vs program) | [Terminology](https://developer.vimond.com/docs/terminology-and-concepts/) | Also in compact REST index glossary |

## Retrieval ladder (do not load the 960 KB YAML first)

For **Vimond REST API**:

1. [vimond-rest-api.llms.md](https://developer.vimond.com/openapi/vimond-rest-api.llms.md) (~60 KB) — every `operationId`, tag, auth, one-line summary.
2. `https://developer.vimond.com/openapi/tags/<slug>.openapi.yml` — full schemas for one tag (e.g. `assets`, `products`).
3. [openapi.yml](https://developer.vimond.com/openapi/openapi.yml) — entire spec only when you need cross-tag schemas.

For **Image Service**:

1. [image-service.llms.md](https://developer.vimond.com/openapi/image-service.llms.md) (~17 KB).
2. `https://developer.vimond.com/openapi/image-service/tags/<slug>.openapi.yml`.
3. [image-service.yaml](https://developer.vimond.com/openapi/image-service.yaml).

For **Content Discovery**:

1. [content-discovery.llms.md](https://developer.vimond.com/openapi/content-discovery.llms.md) (~5 KB).
2. `https://developer.vimond.com/openapi/content-discovery/tags/<slug>.openapi.yml`.
3. [content-discovery.yaml](https://developer.vimond.com/openapi/content-discovery.yaml).

For **Play Service**:

1. [play-service.llms.md](https://developer.vimond.com/openapi/play-service.llms.md) (~3 KB).
2. `https://developer.vimond.com/openapi/play-service/tags/<slug>.openapi.yml`.
3. [play-service.yaml](https://developer.vimond.com/openapi/play-service.yaml).

Prose guides (auth flows, publishing workflows): fetch `https://developer.vimond.com/docs/<slug>.md` mirrors when HTML is too heavy.

## Authentication

- **Admin / back-office:** Bearer JWT — `Authorization: Bearer <token>`. See [api-authentication](https://developer.vimond.com/docs/api-authentication/).
- **End-user (viewer-facing):** Separate flows — [authentication](https://developer.vimond.com/docs/authentication/).
- **Image Service admin:** Same host as client URLs, path prefix `/adminAPI/` — Bearer JWT in 2.0 (not Management API).
- **Image Service client:** `GET /api/v2/img/{imagePackId}` is usually public; some tenants require `X-vimond-access-key` (header wins over query). See [image-urls-and-parameters](https://developer.vimond.com/docs/image-urls-and-parameters/).

## Vimond REST API — content negotiation

Always prefer **JSON**. Avoid XML on new integrations.

| Format | `Accept` / `Content-Type` | Notes |
|--------|---------------------------|--------|
| JSON v3 | `application/json;v=3` | **Preferred.** ISO 8601 dates; omits `null` keys; product periods are ISO 8601 durations (`PT1M`, `P1M`, `P30D`). |
| JSON v2 | `application/json;v=2` | List responses are always arrays. |
| JSON v1 | `application/json` | Single object vs array ambiguity — avoid unless required. If v1 is listed with v2/v3 in `Accept`, **v1 wins**. |

Recommended: `Accept: application/json;v=3, application/json;v=2, application/json`. If v3 returns `406`, retry with v2 explicitly.

## Vimond REST API — updates

- **No `PATCH`.** Updates are **full-resource `PUT`**: GET → merge changes → PUT complete body. Omitted fields may be cleared.
- Some resources support **ETag** / `If-Match` on PUT — verify per endpoint before relying on optimistic concurrency.

## Image Service — two parts (2.0)

| Part | Host pattern | Paths |
|------|--------------|--------|
| **Serving** (clients) | `https://{tenant}.image-service.{environment}.vmnd.tv` | `/api/v2/img/{imagePackId}?location=&width=&height=…` |
| **Management** (ingest/CMS) | Same host | `/adminAPI/...` |
| **Cache invalidation** | `https://manage.api.{environment}.vmnd.tv` | `DELETE /{environment}-lof/images/{tenant}/{imagePackId}` |

Client URL shape did not change when the **image handler** replaced legacy JVM serving; admin still uses the management service for originals and metadata.

**Image pack IDs** from Content Discovery often include a `-{timestamp}` suffix for cache busting; the handler treats the suffix as opaque.

## Terminology traps

| API / docs | CMS / user guide may say |
|------------|---------------------------|
| `company`, `publisherId` | Publisher |
| `asset` | Program, video, clip |
| `category` | Category tree node |
| `platform` | Device, target platform (`web`, `stb`, `mobile`, `all`) |
| `imagePackId` | `image-pack` on assets in discovery payloads |

Full glossaries: [terminology-and-concepts](https://developer.vimond.com/docs/terminology-and-concepts/), [VIA user guide — Terminology](https://via-docs.wikipage.io/c/5078679582/terminology).

## Common tasks

| Task | Guide | Hint |
|------|-------|------|
| Publish asset | [content-publishunpublishing](https://developer.vimond.com/docs/content-publishunpublishing/) | REST `publishinfo`; verify via Content Discovery |
| Show images in app | [content-images](https://developer.vimond.com/docs/content-images/) | Use discovery `images.templates`, not hand-built pack IDs |
| Create / upload image pack | [image-packs](https://developer.vimond.com/docs/image-packs/) | `POST /adminAPI/imagePacks`, then upload to `.../upload` |
| Force CDN refresh after image change | [image-cache-invalidation](https://developer.vimond.com/docs/image-cache-invalidation/) | Usually automatic ~5 min; manual unified-API `DELETE` if urgent |
| Change location pixel sizes | [image-location-configs](https://developer.vimond.com/docs/image-location-configs/) | `PUT .../imageLocationConfig/{name}?force=true` when resize behavior changes |

## Gotchas (read before generating client code)

1. **Do not assume Management API includes Image Service** in 2.0 — use [image-service.yaml](https://developer.vimond.com/openapi/image-service.yaml).
2. **Do not load full `openapi.yml` into context** unless necessary — use [vimond-rest-api.llms.md](https://developer.vimond.com/openapi/vimond-rest-api.llms.md) and tag slices.
3. **JSON v3 missing keys** often mean null/unset, not “field will never exist.”
4. **Partial PUT bodies** on REST or image admin may wipe fields you omitted.
5. **Image `resize-mode=includeAll`** returns transparency-friendly formats (PNG/WebP/AVIF); default `crop` fills the box.
6. **Deprecated REST operations** exist — check the Deprecated tag slice or compact index before building on legacy paths.
7. **Try it in Scalar** may fail CORS from the docs origin — that does not mean the API is down.

## Resources

- [llms.txt](https://developer.vimond.com/llms.txt) — hub entry points for agents
- [Vimond REST API compact index](https://developer.vimond.com/openapi/vimond-rest-api.llms.md)
- [Image Service compact index](https://developer.vimond.com/openapi/image-service.llms.md)
- [Content Discovery compact index](https://developer.vimond.com/openapi/content-discovery.llms.md)
- [Play Service compact index](https://developer.vimond.com/openapi/play-service.llms.md)
- [API reference home](https://developer.vimond.com/reference/) — Scalar UIs

Install this skill in Cursor: add this file to project rules or fetch `https://developer.vimond.com/skill.md` when working on VIA integrations.