Skip to content

API 20141201 Updates

Robert Kulagowski edited this page Nov 22, 2026 · 42 revisions

2026-11-22:

  • Program artwork: the documentation now shows only the full 14-character programID for /metadata/programs/.
  • Program artwork: a programID with no artwork returns code 6000 with the message "No artwork is available for this programID." (a programID that doesn't exist still says "Could not find requested programID."); documented with an example.

2026-11-21:

  • Image redirects: the host of the 303 Location can change (S3, CloudFront, Cloudflare R2); follow it without checking the host.
  • Station logos: the stationLogo examples show the current logo URLs (logos.json.schedulesdirect.org with a ?v= query string); use each URL exactly as given.
  • Schedule MD5s: lastModified changes only when a date's schedule content changes.
  • Token request: "username" is the Schedules Direct username, not the email address; the example no longer shows an email address (issue #76).

2026-11-04: Add code 4011 (CLIENT_UPGRADE_REQUIRED): a client version below the minimum Schedules Direct accepts for that client is refused, on any request, with HTTP 400.

2026-10-29: Note that /programs can briefly return a newer MD5 for a program than the schedules that list it, and how clients should store it. Clarify how often schedules are refreshed and how often clients should sync.

2026-10-21: Correct the image download counter reset for codes 5002 and 5003 (00:00Z, not 24h from the first download). State the token request limit (100 in 24 hours, counted from the first request; every request counts). Document code 5004 and the code 1050 response from ip_isblocked. Update the error code table: correct the name of code 5003; add codes 1012, 1050, 2006, 3002 and 4000.

2025-12-01: Deprecated the Automapping endpoint; it wasn't being used.

2025-11-23: Add an accountExpiration field as a UNIX epoch time which is returned in a status call. Add accountExpiration field to code 4001. Add ip_isblocked endpoint.

2025-11-07: Detail the HTTP response code for Code 5000, Code 5002 and Code 5003 errors.

2025-11-01: Add Code 4002 error. Add Code 4003 error. Add Code 4004 error. Add Code 4008 error.

2025-10-27: Enumerate errors that may be encountered during the login process.

2025-08-09: Update error code table; code 1011 is returned if the application isn't using Content-Type:application/json in the header.

2025-08-08: Be explicit that the client must send Content-Type:application/json in the header.

2025-08-08: Be explicit that the 24h token timer is based on the time of the first request.

2025-08-08: Be explicit about the responses the application might get for token requests.

2025-08-08: Be explicit that image URIs are ephemeral.

2025-08-08: Update documentation regarding program metadata; using the left-most 10 characters is deprecated.

2025-08-08: Be explicit that celebrity images and biography must use the personId element.

2025-07-13: Update error code table; add code 4010. Anti-fraud measure. Subscribers can open a ticket to increase the number of IP addresses they source from by opening a ticket with support.

2025-05-20: Add information about the image counter reset; it's at 00:00Z every day.

2025-05-19: Add details about the token response to include the serverTime field and that it can be used to determine if a client system clock is incorrect.

2025-03-15: Add note that useragent must include the version of the software for troubleshooting and to assist users in updating to the latest version of the grabber software.

2025-03-13: Add field to token request to force generation of a new token instead of returning an existing token. Add tokenExpires field to status response.

2025-03-06: Update information about issuing tokens; a token is valid for 24 hours, and any valid login during that 24 hour period will return the same token.

2025-02-13: Update error code table; add code 2055. Debugging connections must be coordinated with SchedulesDirect.

2025-02-12: Update error code table with all current error codes and human-readable explanations.

2025-02-11: Add details on code 5000 when making an image request.

2025-01-31: Add details on responses which are returned when requesting images if there are no downloads remaining for the user in this time period.

2025-01-14: Add celebrity endpoint.

2025-01-14: Provide details on the maximum number of tokens which will be issued within 24 hours.

2022-10-01: Require token in order to download image index and images.

2020-05-10: Updated stationLogo response to add categories and additional logos available.

2020-05-15: Added description for stationLogo categories.

Clone this wiki locally