Podchaser GraphQL API Overview

The Podchaser API allows you to create scripts and integrations for submitting, editing, and deleting Podchaser data. Additionally, using our Oauth system, you can allow users to authenticate your app to be able to create, edit, and delete user data, such as ratings, reviews, and lists.

Quick Reference

Use Cases

  • Hosting providers can submit a podcast to Podchaser when a user sets up their podcasts
  • Hosting providers can submit episodes or credits to Podchaser when a user adds a new episode
  • Podcast players can allow users to leave Podchaser ratings and reviews from within the player
  • Podcast players or other apps can allow users to create and edit Podchaser lists
  • Podcast players can show users similar podcasts and other podcasts that guests have appeared on
  • Services can load podcast insights to be able to review audience size, demographics, and more
  • And much more!

About GraphQL

GraphQL is a query language and is a newer alternative to REST APIs. It allows clients to request only the exact fields they need and combine/next multiple types. This allows you to get most of the data you need within a single request instead of multiple large requests.

GraphQL mirrors JSON and is hierarchical allowing data to have nested fields and entities. For example, instead of having separate endpoints for getting a creator and getting episodes they have appeared on, you can get both sets of data within a single creator object.

Displaying a "Powered By" Badge

You can display a "Powered By Podchaser" badge within your app, service, or integration! We created a zip that contains a variety of sizes and colors. Download "Powered By" assets.

Query Complexity Points

The Podchaser GraphQL API scores the complexity of a query. Generally, larger queries will have a higher complexity score. This cost of a query is measured in points. You can see the number of monthly points you have within your API settings page.

Cost Headers

Headers are included in the response from all queries to the API to allow you to track your points usage:

  • X-Podchaser-Points-Remaining: The number of points you have remaining (after the execution of this query, if successful)
  • X-Podchaser-Query-Cost: The number of points this query used or would have used

Failed Requests

If you query the /graphql endpoint with a query that would exceed the number of points you have remaining you will receive an HTTP 400 error and the query will not be executed. The response will still contain the Cost Headers described above.

Previewing Query Points

Before executing a query you can POST the same payload to https://api.podchaser.com/graphql/cost to determine how many points the query will use. The cost will be returned in a JSON payload as well as the standard cost headers described above.

Authorization

caution

Standard Client Credentials access tokens should not be used in any environment where they could be exposed to the end user. If compromised, you should contact Podchaser to revoke the access token.

To access the API from a client application with a Client Credentials token, use a Limited Scope token as described at the bottom of this section.

The API uses OAuth 2 to authenticate and authorize clients. Before you can make any queries, you will need to get your access token.

To get your token, you will use the requestAccessToken mutation as shown below. The access tokens last 1 year so you should store this token so you do not need to request new tokens with each query.

If you are needing to authenticate users to make actions within the API, such as leaving reviews or ratings, you will want to follow our User Oauth guide as that process is a little different than below.

POST https://api.podchaser.com/graphql
mutation {
requestAccessToken(
input: {
grant_type: CLIENT_CREDENTIALS
client_id: "YOURID"
client_secret: "YOURSECRET"
}
) {
access_token
token_type # Optional, will always be "Bearer"
expires_in # Optional, will almost always be 31536000
}
}

Example Response

{
"data": {
"requestAccessToken": {
"access_token": "YOURACCESSTOKEN",
"token_type": "Bearer",
"expires_in": 31536000
}
}
}

Once you have your access token, you will use it as the Bearer Token when interacting with other parts of our API.

Limited Scope Client Credentials Token

Your app can request an access token with limited scope that is safe to use directly from your mobile app or client application. These tokens will only allow read access to common entities, and will expire in an hour to limit their usage if compromised. Set the limited_scope to true when requesting an access token to retreive one.