> ## Documentation Index
> Fetch the complete documentation index at: https://docs.visualradioassist.live/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use the names from the glossary at https://docs.visualradioassist.live/glossary: Audio Manager (two words), command (never commando), on air and off air (never live) for programs and studios, and server apps for the VRA apps installed in the studio.
> Say which app an answer applies to, like VRA Cloud, the Core or the Output Player, and the version when the page names one.
> Only give settings, values and steps that are in these docs. Never invent one. If the docs don't cover it, say so.
> When the docs don't answer the question, send the user to Visual Radio Assist support at https://cloud.visualradioassist.live/support.

# AutomationLink ingest

> Push now playing and upcoming items into a studio through the Cloud GraphQL API when your radio automation cannot reach the Core directly.

The `ingestAutomationLinkData` mutation feeds AutomationLink from the cloud side. You send the current and upcoming items to a station, VRA Cloud hands them to the Core of each targeted studio, and the Core publishes them exactly like a locally linked radio automation. Use it when the automation runs outside the studio network, in a cloud playout system for example, and cannot post to the [Core Control API](/develop-with-vra/core-control-api) or the [generic HTTP link](/develop-with-vra/generic-http-radio-automation-link).

## How it works

1. Your automation calls `ingestAutomationLinkData` with the station, optionally one studio, and the `current` and `upcoming` sets.
2. VRA Cloud normalises each item and sends the sets to the Core of every targeted studio over the studio bus.
3. The Core publishes the items as now playing and upcoming, runs [Item Groups](/radio-automation-data) and updates the studio state.
4. For `MUSIC` items without `music_meta`, VRA Cloud looks up [Music Track Meta](/radio-automation-data) in the background and sends the enriched sets a moment later.

<Note>
  The studio needs a running Core. The Core owns the AutomationLink state, so ingested data reaches [visuals](/variables), the Live Switcher and the studio dashboard through the same path as any other radio automation.
</Note>

## Authentication

Authenticate as a [Machine User](/develop-with-vra/cloud-graphql-api/machine-users) of the station, or as a cloud user who has the station active. A machine user bound to another station is rejected with `Not authorized for this station`.

## Targeting studios

* `station_id` is required.
* `studio_id` targets one studio of the station. Omit it to send the same sets to every studio of the station.
* Omit `current` or `upcoming` to leave that set untouched on the Core. Send an empty list to clear it.

## Items

Each item in `current` and `upcoming` follows the `RadioAutomationItem` shape the Core uses for every automation:

* **id** - unique identifier from your automation. Use an md5 of artist and title if your system has none. The Core uses it to detect a new item, so a changed id means a new track.
* **title** and **artist** - the display values. Both must be at least 2 characters for Music Track Meta lookup.
* **type\_identifier** - your automation's own type code for the item, like `JINGLE`, `SWEEPER` or a numeric item type. Item Group conditions can match on it.
* **category** - `MUSIC`, `TRACK`, `STATION` or `UNKNOWN`. Defaults to `MUSIC`. Only `MUSIC` items are enriched.
* **timestamp** - start of the item as a datetime with offset, normalised to UTC.
* **duration** and **offset** - in milliseconds.
* **end\_timestamp** and **completed** - mark an item that already ended.
* **igroups** - item group identifiers you set yourself. Leave it out to let the Core match your [Item Groups](#item-groups). Read that section before you send it.
* **meta** - free-form source metadata like item codes, bpm or key, as a JSON encoded string. Stored as the item's meta string and available in visuals.
* **music\_meta** - artist, title and album details you already have. Any value here, even a cover URL alone, counts as supplied and skips the Music Track Meta lookup.

<Warning>
  `meta` is a `JSON` scalar and must be sent as a JSON encoded string, not as a GraphQL object literal. Write `meta: "{ \"item_code\": \"M-48213\" }"` or pass the string through a variable. An object literal is rejected by the schema.
</Warning>

## Item groups

[Item Groups](/radio-automation-data) are configured per station under **Settings → Outputs → Item Groups**. Each group has an identifier, a category, a match type and conditions on item fields. Outputs, playable items and conditions use the identifier to react to the kind of item on air.

The Core assigns them, not VRA Cloud. For every current and upcoming item, the Core checks the item's `igroups` first:

* **Empty or left out.** The Core runs every Item Group of the station against the item. Each group whose conditions match adds its identifier to `igroups` and sets the item's `category` to the group's category.
* **Not empty.** The Core uses your list as it is and skips Item Group matching for that item.

So there are two ways to classify an item. Pick one per integration.

**Let the Core match (recommended).** Send the fields your automation already has and leave `igroups` out. Conditions match on any item field, like `type_identifier`, `title`, `artist` or `category`, and on every key inside `meta`. A condition on `item_code` matches `meta: "{ \"item_code\": \"J-001\" }"`. Changing a group in VRA then works without touching your integration.

**Set `igroups` yourself.** Useful when your automation already knows the group and no field describes it. Keep in mind:

* Your list replaces matching completely. Sending one identifier means no configured group matches that item, not even the ones whose conditions would.
* The group's category is not applied. Send `category` yourself, or the item stays `MUSIC` and gets a Music Track Meta lookup.
* Identifiers are compared as exact text and are not checked against the station's groups. Use the identifier as it shows in Item Groups, which is uppercase with underscores, like `STATION_ID`. A typo or a renamed group fails without an error.

<Tip>
  Send `type_identifier` and let an Item Group match on it. That is how every built-in radio automation link classifies items.
</Tip>

## Example

Push one current track, a station ID and two upcoming tracks to a single studio. The current item ships its own cover and artist image, so VRA Cloud does not look it up. The station ID carries a `type_identifier` for an Item Group to match on and is not enriched. The two upcoming tracks have no `music_meta` and are enriched in the background.

```graphql theme={null}
mutation {
  ingestAutomationLinkData(input: {
    station_id: "94bf2c80-2fb6-4c0a-b33d-5d2d1bb888e7"
    studio_id: "99abda79-9c21-42a2-bb17-08f7886de136"
    current: [{
      id: "tame-impala-dracula"
      category: MUSIC
      artist: "Tame Impala"
      title: "Dracula (with JENNIE)"
      timestamp: "2026-08-14T08:12:30+02:00"
      duration: 209000
      completed: false
      meta: "{ \"item_code\": \"M-48213\", \"bpm\": 118 }"
      music_meta: {
        title: "Dracula (with JENNIE)"
        artists: [{
          name: "Tame Impala"
          image: {
            regular: "https://cdn-images.dzcdn.net/images/artist/879015e713cc6ad6ffaeec154c027505/250x250-000000-80-0-0.jpg"
            lg: "https://cdn-images.dzcdn.net/images/artist/879015e713cc6ad6ffaeec154c027505/500x500-000000-80-0-0.jpg"
          }
        }]
        album: {
          title: "Dracula (with JENNIE)"
          cover: {
            source: "deezer"
            variants: {
              sm: "https://cdn-images.dzcdn.net/images/cover/b868399da682f34dcd7d98af1c0de80b/250x250-000000-80-0-0.jpg"
              regular: "https://cdn-images.dzcdn.net/images/cover/b868399da682f34dcd7d98af1c0de80b/500x500-000000-80-0-0.jpg"
              lg: "https://cdn-images.dzcdn.net/images/cover/b868399da682f34dcd7d98af1c0de80b/1000x1000-000000-80-0-0.jpg"
            }
          }
        }
      }
    }]
    upcoming: [
      {
        id: "J-001"
        type_identifier: "JINGLE"
        category: STATION
        title: "Station ID"
        timestamp: "2026-08-14T08:15:59+02:00"
        duration: 6000
      },
      {
        id: "olivia-dean-man-i-need"
        category: MUSIC
        artist: "Olivia Dean"
        title: "Man I Need"
        timestamp: "2026-08-14T08:16:05+02:00"
        duration: 184000
      },
      {
        id: "ariana-grande-hate-that-i-made-you-love-me"
        category: MUSIC
        artist: "Ariana Grande"
        title: "hate that i made you love me"
        timestamp: "2026-08-14T08:19:09+02:00"
        duration: 198000
      }
    ]
  }) {
    ok
    studios
    enrichment_queued
  }
}
```

Response:

```json theme={null}
{
  "data": {
    "ingestAutomationLinkData": {
      "ok": true,
      "studios": 1,
      "enrichment_queued": 2
    }
  }
}
```

* **studios** - number of studios the sets were sent to.
* **enrichment\_queued** - number of unique `MUSIC` items queued for Music Track Meta lookup. The enriched sets follow on the same path once the lookup finishes, so expect a second update on the studio a few seconds later.

## Clearing the current item

Send an empty `current` list when the automation stops or goes to a non-music item you do not want on screen. `upcoming` stays as it was.

```graphql theme={null}
mutation {
  ingestAutomationLinkData(input: {
    station_id: "94bf2c80-2fb6-4c0a-b33d-5d2d1bb888e7"
    studio_id: "99abda79-9c21-42a2-bb17-08f7886de136"
    current: []
  }) {
    ok
  }
}
```

## Related

* [Studio control](/develop-with-vra/cloud-graphql-api/studio-control) to put a studio on air or activate its Core from the same API.
* [Connecting with AutomationLink](/develop-with-vra/connecting-with-automationlink) for the fields VRA needs from any radio automation.
* [Radio automation data](/radio-automation-data) for Music Track Meta and Item Groups.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.