> ## Documentation Index > Fetch the complete documentation index at: https://docs.rivi.software/llms.txt > Use this file to discover all available pages before exploring further. # Query with GraphQL > Query the station's published data with GraphQL. Requires a station-scoped Bearer credential with listener:read. GET carries the query in URL parameters, with variables and extensions as JSON-encoded strings; POST accepts a JSON GraphQL request. Send X-Preview-Grant only to read an editorial preview. After the station admits the request, responses use the GraphQL data and errors envelope. Authentication and station errors use the standard error response. Responses are no-store; keep the credential on your server, out of browser bundles and URLs. See the [GraphQL guide](/radiotools/api-reference/graphql) for the schema. ## OpenAPI ````yaml /radiotools/openapi.json post /api/v1/stations/{stationSlug}/graphql openapi: 3.1.0 info: title: RadioTools API version: 1.0.0 description: >- RadioTools APIs for listener websites and apps, published media, and now-playing metadata ingestion. servers: - url: https://radiotools.rivi.software description: radiotools API security: [] tags: - name: Public listener description: >- Tenant-token published delivery (listener:read; push:register for device changes). Published media remains anonymous. OPTIONS allows every origin; JSON is no-store with a strong ETag for conditional polling. - name: Ingest description: >- Automation credentials. The credential resolves the station; payloads cannot change it. paths: /api/v1/stations/{stationSlug}/graphql: post: tags: - Public listener summary: Query published station data with GraphQL description: >- Query the station's published data with GraphQL. Requires a station-scoped Bearer credential with listener:read. GET carries the query in URL parameters, with variables and extensions as JSON-encoded strings; POST accepts a JSON GraphQL request. Send X-Preview-Grant only to read an editorial preview. After the station admits the request, responses use the GraphQL data and errors envelope. Authentication and station errors use the standard error response. Responses are no-store; keep the credential on your server, out of browser bundles and URLs. See the [GraphQL guide](/radiotools/api-reference/graphql) for the schema. parameters: - schema: type: string required: true name: stationSlug in: path description: >- Public station slug from the station settings; distinct from the internal station ID. example: radio-rivier - schema: type: string required: false name: X-Preview-Grant in: header description: >- Editorial preview grant from the station's website preview link. Send it to read the unpublished revision it was issued for; omit it for published data. requestBody: content: application/json: schema: type: object properties: query: type: string operationName: type: - string - 'null' variables: type: - object - 'null' additionalProperties: {} extensions: type: object additionalProperties: {} required: - query example: token: fictional-fcm-device-token platform: android provider: fcm examples: android: summary: Register an Android device description: >- Replace the fictional token with the device token from your push provider; the provider must match the station configuration. value: token: fictional-fcm-device-token platform: android provider: fcm responses: '200': description: GraphQL result content: application/json: schema: $ref: '#/components/schemas/GraphqlResponse' '400': description: The request contains invalid parameters or input. content: application/json: schema: $ref: '#/components/schemas/GraphqlFailure' examples: error: summary: 400 VALIDATION_ERROR value: error: code: VALIDATION_ERROR message: The request contains invalid parameters or input. requestId: 28e5d867-1f87-4ca7-bca9-4ebc09b36ba3 issues: - path: query message: >- Check the parameter types and bounds documented for this operation. '401': description: A valid station credential with the required scope is needed. content: application/json: schema: $ref: '#/components/schemas/GraphqlFailure' examples: error: summary: 401 UNAUTHENTICATED value: error: code: UNAUTHENTICATED message: >- A valid station credential with the required scope is needed. requestId: 28e5d867-1f87-4ca7-bca9-4ebc09b36ba3 '403': description: The credential does not permit this operation. content: application/json: schema: $ref: '#/components/schemas/GraphqlFailure' examples: error: summary: 403 FORBIDDEN value: error: code: FORBIDDEN message: The credential does not permit this operation. requestId: 28e5d867-1f87-4ca7-bca9-4ebc09b36ba3 '404': description: >- The resource is missing, unpublished, disabled, or unavailable for this station. A switched-off station module returns MODULE_DISABLED. content: application/json: schema: $ref: '#/components/schemas/GraphqlFailure' examples: error: summary: 404 NOT_FOUND value: error: code: NOT_FOUND message: >- The resource is missing, unpublished, disabled, or unavailable for this station. A switched-off station module returns MODULE_DISABLED. requestId: 28e5d867-1f87-4ca7-bca9-4ebc09b36ba3 '409': description: The request conflicts with the current resource revision. content: application/json: schema: $ref: '#/components/schemas/GraphqlFailure' examples: error: summary: 409 REVISION_CONFLICT value: error: code: REVISION_CONFLICT message: >- The request conflicts with the current resource revision. requestId: 28e5d867-1f87-4ca7-bca9-4ebc09b36ba3 '429': description: Too many requests. Reduce the request frequency. content: application/json: schema: $ref: '#/components/schemas/GraphqlFailure' examples: error: summary: 429 RATE_LIMITED value: error: code: RATE_LIMITED message: Too many requests. Reduce the request frequency. requestId: 28e5d867-1f87-4ca7-bca9-4ebc09b36ba3 '500': description: GraphQL or station admission error content: application/json: schema: $ref: '#/components/schemas/GraphqlFailure' '503': description: An upstream service is temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/GraphqlFailure' examples: error: summary: 503 PROVIDER_UNAVAILABLE value: error: code: PROVIDER_UNAVAILABLE message: An upstream service is temporarily unavailable. requestId: 28e5d867-1f87-4ca7-bca9-4ebc09b36ba3 security: - machineToken: [] components: schemas: GraphqlResponse: type: object properties: data: type: - object - 'null' additionalProperties: {} errors: type: array items: type: object properties: message: type: string locations: type: array items: type: object properties: line: type: integer column: type: integer required: - line - column path: type: array items: anyOf: - type: string - type: integer extensions: type: object additionalProperties: {} required: - message extensions: type: object additionalProperties: {} GraphqlFailure: anyOf: - $ref: '#/components/schemas/GraphqlResponse' - type: object properties: error: type: object properties: code: type: string enum: - UNAUTHENTICATED - FORBIDDEN - VALIDATION_ERROR - NOT_FOUND - MODULE_DISABLED - METHOD_NOT_ALLOWED - REVISION_CONFLICT - IDEMPOTENCY_CONFLICT - RATE_LIMITED - PROVIDER_UNAVAILABLE - INTERNAL_ERROR message: type: string requestId: type: string format: uuid issues: type: array items: type: object properties: path: type: string message: type: string code: type: string maxLength: 64 suggestion: type: string maxLength: 200 retryAfter: type: integer minimum: 1 maximum: 86400 required: - path - message required: - code - message - requestId required: - error securitySchemes: machineToken: type: http scheme: bearer bearerFormat: rtm_… description: >- Station-scoped listener credential. Send Authorization: Bearer ``, for example Bearer rtm_…. Sending the rtm_ token alone without Bearer returns 401 UNAUTHENTICATED. In the interactive playground, enter only the raw rtm_ token; the playground adds the prefix. Listener REST and GraphQL: listener:read. Listener devices: push:register. ```` ## Related topics - [Query with GraphQL (GET)](/radiotools/api-reference/public-listener/query-graphql-get.md) - [GraphQL](/radiotools/api-reference/graphql.md) - [GraphQL schema reference](/radiotools/api-reference/graphql-reference.md) - [Errors and versioning](/radiotools/api-reference/errors-and-versioning.md) - [API overview](/radiotools/api-reference/overview.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.