API Access

The Supporting Cast APIs allow you to integrate your software directly into Supporting Cast.

Overview

• Access is over HTTPS
• Requests all have the base path https://api.supportingcast.fm/
• All data is sent and received as JSON. Requests must have this header:

  Accept: application/json

  
  

Authentication

• All requests must have an Authorization header with an OAuth token. The header should be in this format:

  Authorization: Bearer OAUTH-TOKEN

• Supporting Cast tokens are created, invalidated, and otherwise managed at the API Tokens admin page under your subdomain at /admin/tokens

Lists

All lists will be paginated.

The default page size for v1 requests is 100 records. Our v1 API will return up to 500 records in a page.

The default page size for v2 requests is 20 records. Our v2 API will return up to 100 records in a page.

Request Limits

API clients are limited in how quickly they can make requests. If they hit these limits, they will receive a 429 Too Many Requests error.

• X-RateLimit-Limit - Total Allowed Requests
• X-RateLimit-Remaining - Remaining Requests for this API endpoint
• Retry-After - How many seconds until you can make another request to this API endpoint
• X-RateLimit-Reset - Timestamp when the current lock will reset

API v2

• Most v2 endpoints - 4 requests per second, up to 200 requests per minute
• POST /v2/…/api_tokens - 1 request per minute

Every v2 endpoint has its own counter, shared by all of your network's API tokens. Requests to one endpoint do not use up the limits of another.

API v1

• Most v1 endpoints - 10 requests every 10 seconds
• /v1/memberships/* - 5 GET requests every 10 seconds, 10 PUT/POST requests every 10 seconds
• /v1/managerships/* - 100 GET requests every 10 seconds, 10 PUT/POST requests every 10 seconds
• /v1/bulk - 1 request every 10 seconds. (but each request can call up to 100 APIs)
• DELETE requests - 10 requests every 10 seconds

All v1 requests share the same counter. For example, if you use all 10 DELETE requests, you will have 0 PUT/POST requests or 10 /v1/reports GET requests remaining.

If you need changes to these limits, please contact your account representative or email us at team@supportingcast.fm