Cloud GraphQL API

Machine Users

Authenticate automated systems and integrations with API tokens.

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
Login with your VRA Cloud manager user credentials
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:

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:

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

Input Variables Example:

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

// 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}`
    }))
  };
}

Error Handling

Common GraphQL Errors

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

Validation Errors

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

# 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

Machine Users

​Overview

​API Endpoints

​Production Environment

​Authentication

​GraphiQL Authentication

​Core Concepts

​Programs and Scheduling

​Media Management

​Key Operations

​Querying Programs

​Creating/Updating Programs

​Input Variables Example:

​RRule Format

​RRule Testing

​Integration Patterns

​External Scheduling System Sync

​Error Handling

​Common GraphQL Errors

​Validation Errors

​Best Practices

​Query Optimization

​Rate Limiting

​Development Workflow

​1. Exploration with GraphiQL

​2. Schema Introspection

​3. Testing Environment

​Troubleshooting

​Authentication Issues

​Schema Validation

​Debugging Tips

​Migration and Updates

​API Versioning

​Schema Updates