> ## 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. # 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. 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](/develop-with-vra/cloud-graphql-api/machine-users). ``` 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: ```graphql theme={null} 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 theme={null} mutation UpsertProgram($input: UpsertSchedulingProgramInput!) { upsertSchedulingProgram(input: $input) { id title start end } } ``` ### Input Variables Example: ```json theme={null} { "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](https://jkbrzt.github.io/rrule/) to test and generate RRule strings. ## Integration Patterns ### External Scheduling System Sync ```javascript theme={null} // 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 ```json theme={null} { "errors": [ { "message": "Authentication required", "extensions": { "code": "UNAUTHENTICATED" } } ] } ``` ### Validation Errors ```json theme={null} { "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](mailto: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 theme={null} # 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](http://status.visualradio.cloud) for API availability * Check [changelog.visualradioassist.live](http://changelog.visualradioassist.live) for significant documentation changes * Test integrations against new schema versions * Update code to use new features and deprecate old patterns