If you are looking for Developer documentation and resources to help you get started using the AP ENPS and AP Storytelling (formerly Playbook) API, you've found it! Our API allows customers and partners to create and deploy custom applications to extend existing workflows in innovative ways via integration with both third-party and bespoke systems.
The API offers bi-directional (read/write) access to a broad scope of content and configuration information for ENPS and Storytelling via a standard REST/JSON architecture.
The API supports both request-based (pull) and subscription-based (push) approaches for receiving updates to ENPS and Storytelling data objects.
Within ENPS and Storytelling, custom "action buttons" can manually trigger external APIs to interact with Storytelling at a user's discretion.
Sample Workflows and Use Cases
Find out how you can take advantage of the API to enhance your newsroom workflow.
Getting Started with the API
Learn about access, installation, keys, rate limiting and supported protocols.
API Explorer/Swagger Spec (SDK)
Interact with the API. Discover, test and debug live calls. Generate a client SDK.
Additional Resources
Get your ENPS installers, Best Practices, JavaScript SDK documentation and more.
Getting Help
Contact us if you need additional assistance after reviewing the resources.
FAQs
Check out commonly asked questions about the API.
Using the API in the Cloud
Learn about the base URL and cookies to use the API in the cloud.
Here is how AP ENPS and AP Storytelling customers are using the API to enhance their newsroom's workflows.
The Associated Press uses the API to automatically generate Topics and Assignments in Storytelling for thousands of sporting events (NFL, NHL, NBA, NCAA, MLB, golf, etc.) based on schedule data from an external vendor's database. AP developed an application that pulls the data from the database – including home and away teams, league, game time, and location – and pushes that data to Storytelling along with additional metadata that is cross-referenced from an internal datastore. Having this information automatically loaded into Storytelling saves AP sports editors and reporters dozens of hours of manual data entry each week, allowing them to refocus that time on quality journalism and storytelling.
Voice of America (VOA) utilizes the API to ingest AP Planner content. The API pulls in data from a configured saved search that VOA created on the AP Planner site, assuring that only content VOA is interested in is converted into Playbook Topics. The created Topics include key information like Slug, Description, Organizer, Press Contacts, UniqueID and the Last Updated time of the item. Having this information automatically loaded into Playbook saves VOA planning editors and reporters hours of manual data entry each week, allowing them to refocus that time on quality journalism and storytelling.
NRK (Norway) was one of the first organizations to realize the potential of the API and now has multiple systems using it. NRK leveraged the API to create a system that acts as a bridge to its master scheduling system and automatically creates regional news running orders.
Another implementation is designed to improve communication and collaboration between regional newsrooms and the national headquarters in Oslo. The application monitors all regional planning grids for stories to indicate that the story may be of national interest.
This master grid is used to populate a web page that is displayed on a large monitor in the newsroom that shows contact details for all users referenced in stories.
The API is further leveraged in a system that tracks sports recordings and in another that automates large amounts of the testing that is applied to new releases of NRK's third-party MAM system.
This creative use of the API has allowed NRK to drastically reduce the amount of time spent on routine tasks and on editorial conference calls.
Gray Television uses the API to save hundreds of hours of busywork a year. Previously, someone in each newsroom of the company's TV stations would have to comb through all of the archived rundowns to compile lists of news stories in a variety of community interest categories to be submitted as part of their quarterly FCC reports.
Stations add a drop-down column to their stories that contain a list of community interest categories. If a story qualifies as being "FCC worthy," the producer flags it by selecting a category. The export program is hosted as a web application that taps into the Search and RundownContent endpoints of the API. The end user chooses a date range, and the application finds all of the stories that have an FCC category set. The application then displays the stories on the screen and provides an option to download them to a spreadsheet.
One broadcaster has utilized the API to siphon content from ENPS into two external systems: an SQL database to generate reports based on a wide range of ENPS metadata, and an archive management system that links script text, media and metadata to publish content to the archive.
The archive management implementation is part of a wider set of processes that links content from a variety of systems and is designed to improve the management of organization-wide metadata and facilitate better use of the archive.
A browser-based interface allows users to choose the channel and date, and to select from a list of broadcast programs initially populated by another system that generates the unique program IDs and contains the descriptions used in program guides. The user can incorporate additional metadata through integration with the media system, but also from ENPS via the API.
The browser-based interface allows users to choose the channel and date, and to select from a list of broadcast programs, initially populated by another system that generates the unique program IDs and contains the descriptions used in program guides. The user can incorporate additional metadata through integration with the audio system but also from ENPS via the Open API; clicking a button in the interface that calls the api/Search endpoint and then uses api/BasicContent and api/RundownContent to fetch the relevant running order and scripts, the latter filtered by a local matching algorithm to only keep items of interest.
This allows all content to be checked and additional metadata to be added prior to the rundown and script content being published to the archive.
The Associated Press uses the API to share its editorial coverage plans with members and subscribers by publishing planning data from Storytelling to the Coverage Plan section of its AP Newsroom portal. Once a Coverage Plan is ready to be made public, editors click a custom "Publish" button in the Storytelling interface that triggers AP’s custom code to retrieve the full data for that story and push the story plan to the portal's datastore. The publishing application then pushes a status update back into Storytelling indicating when the story was successfully published to the AP Newsroom portal and provides a link that allows AP journalists to view the story in AP Newsroom just as AP members would see it.
The AP also uses the API to produce daily content advisories – "digests" – to alert members and subscribers about the most important or interesting stories and related media that have already been published or those that are coming up later in the day. After selecting and ordering the stories in Storytelling's Cast module, an editor publishes the list to AP's digest automation system, which formats the content for distribution and sends it to an editor for final polishing before transmission on the wire.
Your API development key is a unique identifier for your organization. The API development key will be issued to you by the AP when your agreement to use the API is completed.
The API development key is used to initiate each session between your API-enabled system and your ENPS and/or Storytelling servers. That initial logon also requires a valid username and password tied to ENPS or Storytelling Staff Table. It is recommended that you create a separate "Service Account" that is not tied to an individual and does not change passwords without the involvement of an administrator who can also make the required updates to your API-enabled system. This account does not need to have ENPS "Administrator" status in ENPS or Storytelling but must have sufficient access in Staff Privileges to read or edit the information that your API-enabled system requires.
Following the initial per-session logon, validation for every subsequent query or command uses a dynamically-generated token that is issued uniquely per session and returned in the response to the logon call. At your discretion, communication between your API-enabled system and ENPS or Storytelling may be encrypted using HTTPS communication. This is especially and strongly recommended if transmission is across the public internet.
The API usage is "rate-limited" meaning there is a maximum number of calls that you may make to the API per minute. This is designed to protect your ENPS or Storytelling servers against a data storm generated by improper usage of the API that could interfere with users' ability to use the system. The API will reject all calls after you reach your limit for any given minute. The count begins cleanly at the commencement of the next minute. The default limit is 100 calls/minute.
Rate limiting is based on the total number of API calls using a single API development key against any ENPS or Storytelling systems. If you find that you are frequently reaching your limit because you are using the same API development key with multiple servers (for example, multiple sites across an enterprise), please email us at APNewsTech-API@ap.org so we may review your technical situation. There is no additional fee for increasing your rate limit.
Any server that the API is installed on must have access to the internet so it can communicate with our licensing service.
HTTP 1.1 and HTTPS 1.1 are supported for the API.
In support of HTTPS, AP ENPS and Storytelling provide the option for SSL security for API communication through configuration of Microsoft IIS components. It is mandatory and enforced on AP-hosted implementations.
On an ongoing basis, on AP-hosted services, the AP maintains SSL/TLS protocols at the currently recommended levels – and disables other levels as recommended by security advisers. You are strongly encouraged to keep systems under your control to the same standards.
As of mid-2022, only TLS protocols 1.2 and 1.3 should be enabled. Earlier versions of TLS and SSL should be disabled.
The Swagger-based API Explorer is included as an interactive quick reference that lists the API calls and parameters and allows for testing live API calls and generating sample code.
The API Explorer is installed as part of the API and can be accessed by adding "/swagger" to the end of your root API URL: https://servername/NOMWebServices3API/swagger.
To use the API Explorer, you'll first select the LOGON endpoint (POST) and log in using your ENPS/Storytelling credentials and API development key (similar to starting any API session outside the API Explorer).
Copy the SessionID value from the response X-ENPS-TOKEN. Click the Authorize button on the right side of the landing page, paste in the copied X-ENPS-TOKEN value, and click Authorize. This will now allow the X-ENPS-TOKEN to be used for all other activity in the API Explorer. When you're done, click Authorize again and select Logout to clear the token.
NOTE: The Swagger page is interacting with a live server in the URL, enabling Swagger exploration of your server-specific records and schema. Use caution when performing patch, put or delete operations on the server. Utilize the Swagger page on a development or testing server whenever possible.
On request, AP can also provide additional resources such as a Postman collection containing a basic environment and samples for all API calls.
Need help?
Try checking our FAQs and the Best Practices guide available at the ENPS Resources site. Both sections contain useful information that may get you the answer you need. You can also use the API Explorer to help develop and test specific API calls.
If those options don't get you the answer you are looking for, contact us at APNewsTech-API@ap.org.
We'll respond as quickly as we can, usually by the next business day.
They are one and the same. AP ENPS and AP Storytelling are built on a common platform and share many of their backend components, including the API. Some areas of the API are specific to one or the other, since not all objects and data types are used in both applications. All of the core endpoints (Logon, Search, BasicContent, etc.) are used equally for both AP ENPS and AP Storytelling.
For Customers: Use of the API requires an addendum to your contract for other AP services. Contact your AP representative for the form. If you don't know who your AP representative is, please e-mail us at APNewsTech-API@ap.org.
For Partners: We are eager to work with you to develop the best-integrated systems for our mutual users. Our Integration Team can work with you to set up development/test systems and provide you an API development key. Please e-mail us at APNewsTech-API@ap.org.
Once the above has been completed, an API development key will be issued to you with a default rate limit of 100 calls/minute. For more information on how and when to use the development key, see Keys. For an explanation of our rate limiting, see Rate Limiting.
Possibly, yes. Contact us at APNewsTech-API@ap.org to discuss your requirements.
Yes, but all calls will count against the same rate limit whether they originate from one application or multiple. If you need more than one development key, email us at APNewsTech-API@ap.org to discuss your requirements.
The API calls and responses are primarily in JSON. The few exceptions are endpoints that accept GET calls and return an empty response body with status codes indicating either success or failure.
The Swagger-based API Explorer is available. The API Explorer is an interactive quick reference that lists the API methods and parameters and allows for testing live API calls and generating sample code. An API development key is required for testing live API calls.
Yes, ENPS and Storytelling support the creation of webhook-based HTTP event streams that can be used to automatically push select updates to integrated systems downstream.
For both ENPS and Storytelling systems, an administrator can configure webhook functionality, or webhooks can be managed via the /Webhooks API endpoint. Webhook events can be raised on specific object types and further fine-tuned to result only from changes to specified fields when those fields are configured as Resthook triggers.
It is also possible to attach a WebhooksWatch field to a record pointing to a given webhook URL to raise events for any change to the object. This is useful for monitoring specific Rundowns or Topics.
No. Each AP ENPS and AP Storytelling customer is required to use an API key provided to that organization by the AP. Your product should have a means for your customer to load their own AP ENPS/AP Storytelling API key.
When using the API on an API-hosted instance in the cloud (for example, with hosted Storytelling installations), the following must be kept in mind:
The base URL for all calls to the API is https://siteID.apstorytelling.com/NomWebServices3API/api, where siteID is the first part of your Storytelling URL as assigned by AP.
So, if you are site XYZ, your Base URL would be:
https://xyz.apstorytelling.com/NomWebServices3API/api
Some implementations still use 'applaybook' instead of 'apstorytelling' in the domain name.
When first calling the API to logon, you will receive a pair of cookies returned in the response called AWSALB and AWSALBCORS. These cookies must be reused in the headers of all subsequent calls which are part of the same API logon session.
Some HTTP clients (browsers, Powershell) will manage these cookies automatically, others (Node libraries like Fetch, Axios or Express) will require the last 'set-cookie' header to be sent back on next request.
To set cookies in Node libraries, use the following:
NewRequest.headers.common['set-cookie'] = [(lastResponse.headers['set-cookie'][0]), (lastResponse.headers['set-cookie'][1]) ];