Skip to main content

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:
  1. Click the “Authorize with VRA Cloud” button in the GraphiQL interface
  2. Login with your VRA Cloud manager user credentials
  3. 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