Cloud GraphQL API

Visual Radio Assist provides a comprehensive GraphQL API that enables powerful integration capabilities with external broadcast systems, scheduling software, and custom applications. This API serves as the primary interface for programmatic interaction with VRA Cloud.

Overview

The VRA GraphQL API offers a flexible, efficient way to query and manipulate data within your Visual Radio Assist environment. Unlike traditional REST APIs, GraphQL allows you to request exactly the data you need in a single query, reducing network overhead and improving performance.

API Endpoints

Production Environment

API Endpoint: https://api.cloud.visualradioassist.live/graphql
GraphiQL Playground: https://api.cloud.visualradioassist.live/graphiql

Authentication

All API requests require authentication using a Machine User token. For details on creating Machine Users, see the Machine Users documentation.

POST /graphql
Content-Type: application/json
Authorization: Bearer your_machine_user_token

GraphiQL Authentication

The GraphiQL playground provides automated authentication:

Click the "Authorize with VRA Cloud" button in the GraphiQL interface

Select a machine user from the dropdown to automatically authorize the playground

For machine-to-machine access, use the token generated during the machine user creation process.

Core Concepts

Programs and Scheduling

The API centers around SchedulingProgram objects that represent broadcast programs:

Programs: Individual broadcast shows or segments

Presenters: Host information associated with programs

Recurring Patterns: Schedule repetition using RRule format

Media Assets: Associated visual and audio content

Media Management

Media References: Support for external URLs and media file references

Metadata Handling: Rich media information and categorization

Key Operations

Querying Programs

Retrieve existing program information:

graphql
query GetPrograms {
  schedulingPrograms {
    id
    title
    description
    start
    end
    presenters {
      id
      fname
      lname
      name
      avatar
    }
    media {
      cdnImageId
      metadata
    }
    rRule
  }
}

Creating/Updating Programs

Use the upsertSchedulingProgram mutation to create or update programs:

graphql
mutation UpsertProgram($input: UpsertSchedulingProgramInput!) {
  upsertSchedulingProgram(input: $input) {
    id
    title
    start
    end
  }
}

Input Variables Example:

json
{
  "input": {
    "id": "S623-20250722",
    "title": "Morning Show",
    "description": "Daily morning broadcast",
    "start": "2025-07-22 06:00:00",
    "end": "2025-07-22 10:00:00",
    "presenters": [
      {
        "id": 1,
        "fname": "John",
        "lname": "Doe",
        "name": "John Doe",
      }
    ],
    "metadata": {},
    "media": ["media_key_1", "media_key_2"],
    "rrule": "FREQ=DAILY;BYDAY=MO,TU,WE,TH,FR"
  }
}

RRule Format

VRA uses the iCalendar RRule standard for recurring programs. Common patterns:

Daily (weekdays only): FREQ=DAILY;BYDAY=MO,TU,WE,TH,FR
Weekly: FREQ=WEEKLY
Monthly: FREQ=MONTHLY
Custom interval: FREQ=WEEKLY;INTERVAL=2 (every 2 weeks)

RRule Testing

Use online tools like rrule.js demo to test and generate RRule strings.

Integration Patterns

External Scheduling System Sync

javascript
// Example Node.js integration
const fetch = require('node-fetch');

async function syncScheduleToVRA(externalPrograms) {
  const endpoint = 'https://api.cloud.visualradioassist.live/graphql';
  const token = process.env.VRA_MACHINE_USER_TOKEN;
  
  for (const program of externalPrograms) {
    const mutation = `
      mutation UpsertProgram($input: UpsertSchedulingProgramInput!) {
        upsertSchedulingProgram(input: $input) {
          id
          title
        }
      }
    `;
    
    const variables = {
      input: transformToVRAFormat(program)
    };
    
    await fetch(endpoint, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${token}`
      },
      body: JSON.stringify({
        query: mutation,
        variables: variables
      })
    });
  }
}

function transformToVRAFormat(externalProgram) {
  return {
    id: externalProgram.broadcastId,
    title: externalProgram.showName,
    description: externalProgram.synopsis,
    start: externalProgram.startTime,
    end: externalProgram.endTime,
    presenters: externalProgram.hosts.map(host => ({
      id: host.staffId,
      firstName: host.first,
      lastName: host.last,
      name: `${host.first} ${host.last}`
    }))
  };
}

Real-time Schedule Updates

javascript
// Webhook handler for schedule changes
app.post('/schedule-webhook', async (req, res) => {
  const { action, program } = req.body;
  
  if (action === 'update' || action === 'create') {
    await updateVRASchedule(program);
  } else if (action === 'delete') {
    await deleteVRAProgram(program.id);
  }
  
  res.status(200).send('OK');
});

Error Handling

Common GraphQL Errors

json
{
  "errors": [
    {
      "message": "Authentication required",
      "extensions": {
        "code": "UNAUTHENTICATED"
      }
    }
  ]
}

Validation Errors

json
{
  "errors": [
    {
      "message": "Invalid date format for field 'start'",
      "path": ["upsertSchedulingProgram", "start"],
      "extensions": {
        "code": "BAD_USER_INPUT"
      }
    }
  ]
}

Best Practices

Query Optimization

Request Only Needed Fields: GraphQL allows precise field selection

Use Fragments: Reuse common field sets across queries

Batch Operations: Combine multiple mutations when possible

Implement Caching: Cache frequently accessed data

Rate Limiting

Implement request throttling in your application

Monitor API usage through VRA Cloud dashboard

Contact support for rate limit adjustments if needed

Development Workflow

1. Exploration with GraphiQL

Use the interactive GraphiQL playground to:

Explore the complete schema

Test queries and mutations

Validate data structures

Generate example code

2. Schema Introspection

The GraphiQL interface provides full schema introspection, showing:

Available queries and mutations

Field types and relationships

Required vs optional fields

Deprecation notices

3. Testing Environment

Development environment access must be requested through support@visualradioassist.live:

Request development environment access for integration testing

Create test programs and data in the development environment

Validate data transformations

Test error scenarios

Troubleshooting

Authentication Issues

bash
# Test token validity
curl -X POST https://api.cloud.visualradioassist.live/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_token" \
  -d '{"query": "query { __typename }"}'

Schema Validation

Use GraphiQL's built-in validation to check:

Query syntax

Field availability

Type compatibility

Required field presence

Debugging Tips

Enable detailed logging in your application

Use GraphiQL for query testing and validation

Monitor VRA Cloud audit logs for API activity

Check network connectivity and DNS resolution

Migration and Updates

API Versioning

VRA maintains API compatibility but may introduce:

New fields and mutations

Deprecation warnings

Enhanced validation rules

Schema Updates

Monitor the GraphiQL playground for schema changes

Subscribe to status.visualradio.cloud for API availability

Check changelog.visualradioassist.live for significant documentation changes

Test integrations against new schema versions

Update code to use new features and deprecate old patterns