No announcement yet.

API Parameters

  • Filter
  • Time
  • Show
Clear All
new posts

  • API Parameters

    I'm looking to work with the data available from the API. Being a bit of a novice with APIs, I'm having problems understanding how to format the API statements to see the data. Ultimately, I want to be able to grab all the JSON data within the stories in a running order. I've figured out some basic stuff with the API like ( which outputs the JSON data for that particular story id. But I'm sure there's a better way to find out what running order or story with what ID...or to be able to view all stories and all running orders. But I'm not sure how to set the parameters to do that within your API.

  • #2
    Here are some of the relevant API endpoints for enumerating running orders, stories and MOS items. Note that you will need to supply an API key with these calls.
    • Enumerate all available running orders: /inception/RunningOrderManager/Object/Render.js and /inception/RunningOrderManager/Object/RowCount.js
    • Grab a running order with /inception/RunningOrder/Object/Render.js - there is a lot of superfluous data but here are some fields to focus on:
      • object/<number>/story/id/value - the ID of the story (to query in step 4)
      • object/<number>/story/object/value - the type of the story
      • object/<number>/slug/value - the slug of the story
      • object/<number>/page/value - the page number of the story
    • Grab a story with /inception.broadcast/BroadcastStory/Object/Get.js - relevant fields:
      • object/printBody - the script contents
    • Enumerate the MOS items of a story with /inception.mos/MosStoryItem/Object/Get.js
    • Get the raw MOS for each item with /inception.mos/MosStoryItem/Object/Object.js
    If you're working in Java here's some code to get you started:

      import java.util.ArrayList;
      import java.util.HashMap;
      import java.util.List;
      import java.util.Map;
      import java.util.Map.Entry;
      public class MOSUplinkAPI {
      private static final String RUNNING_ORDER_MANAGER_RENDER = "/inception/RunningOrderManager/Object/Render.js";
      private static final String RUNNING_ORDER_MANAGER_ROWCOUNT = "/inception/RunningOrderManager/Object/RowCount.js";
      public static void main(String[] args) {
      String apiKey = "BpBaGOUauiHiTrp7HHqiIO80uoaaySSK8Sqd1T0hTtG6AEcPDTlDeASOpJySBiS5";
      String inceptionUrl = "http://localhost";
      try {
      Map<String, Object> renderArgs = new HashMap<String, Object>();
      renderArgs.put("showArchived", "false");
      renderArgs.put("offset", "0");
      Map<String, Object> response = makeApiCall(inceptionUrl, RUNNING_ORDER_MANAGER_RENDER, apiKey, new HashMap<String, Object>());
      // List all the running orders
      ArrayList<Map<String, Object>> runningOrders = (ArrayList<Map<String,Object>>) response.get("object");
      for (Map<String,Object> runningOrder: runningOrders) {
      Map<String,Object> name = (Map<String,Object>)runningOrder.get("name");
      } catch (Exception e) {
      public static void verifyResponse(Map<String, Object> response, String endPoint) throws Exception {
      if (response.get("status") == null || response.get("status").equals("success") == false) {
                  String msgs = "";
                  List<String> responseMsgs = (List<String>) response.get("messages");
                  if (responseMsgs != null) {
                      for (String msg : responseMsgs) {
                          msgs += msg + "\n";
                  } else {
                   responseMsgs = new ArrayList<String>();
                  throw new Exception("API call to " + endPoint + " failed with the following messages: " + msgs);
      public static Map<String, Object> makeApiCall(String url, String endpoint, String apiKey, Map<String, Object> data) throws Exception {
      HttpURLConnection inceptionConnection = null;
      try {
      // initialize connection
      inceptionConnection = initializeConnection(url, endpoint);
      data.put("api", apiKey);
      // Convert data to post string
      String postData = getPostString(data);
      inceptionConnection.setRequestProperty("Content-Length", Integer.toString(postData.getBytes().length));
      // Write post data to stream
      DataOutputStream output = new DataOutputStream(inceptionConnection.getOutputStream());
              BufferedReader in = new BufferedReader(new InputStreamReader(inceptionConnection.getInputStream()));
              StringBuffer json = new StringBuffer();
              String line;
              while ((line = in.readLine()) != null) {
              Map<String, Object> response = new Gson().fromJson(json.toString(), new TypeToken<Map<String, Object>>(){}.getType());
              verifyResponse(response, endpoint);
      return response;
      } finally {
      if (inceptionConnection != null) {
      public static String getPostString(Map<String, Object> data) throws UnsupportedEncodingException {
      StringBuilder builder = new StringBuilder();
      for (Entry<String, Object> kv : data.entrySet()) {
      if (builder.length() > 0) {
      if (kv.getValue() instanceof List<?>) {
      List<Object> values = (List<Object>) kv.getValue();
      for (int i = 0; i < values.size(); i++) {
      if (i != 0) {
      builder.append(kv.getKey() + "=" + URLEncoder.encode(values.get(i).toString(), "UTF-8"));
      } else {
      builder.append(kv.getKey() + "=" + URLEncoder.encode(kv.getValue().toString(), "UTF-8"));
      return builder.toString();
      public static HttpURLConnection initializeConnection(String url, String endpoint) throws Exception {
      HttpURLConnection inceptionConnection = (HttpURLConnection) new URL(url + endpoint).openConnection();
      inceptionConnection.setRequestProperty("Accept-Language", "en-US,en;q=0.5");
      inceptionConnection.setRequestProperty("charset", "utf-8");
      inceptionConnection.setDoInput (true);
      return inceptionConnection;


    • #3
      Hi guys,

      I succeded in reading Running Orders List, stories contents, ... with the previous answer.

      However, even with the API documentation, i can't edit anything... For example, how could i change the slug of a story or anything else ? Do you have an exemple for this ?



      • #4
        Hi Chris,

        If you want to modify the data you need to make a separate HTTP POST request to the server with the data that you want to change. The above sample's makeApiCall method would be more than suitable for this.

        To update the text of the story you would identify the id and type of the story (for this example let's assume the id is 6 and the type is "BroadcastStory". This tells us that the story is meant for broadcast and which endpoints we can use to manipulate it. Since this example I've used a story with the "BroadcastStory" type I can refer to the API endpoints for Broadcast Story and see that there's a "save" endpoint that accepts a body parameter. This parameter can be used to replace the text of a broadcast story. From here we can build a short method that would set the body of a broadcast story:

        public static void setBroadcastBody(String url, String apiKey, long storyId, String body) {
           Map<String, Object> args = new HashMap<>();
           args.put("id", Long.toString(storyId));
           args.put("body", body);
           Map<String, Object> response = makeApiCall(url, "/inception.broadcast/BroadcastStory/Object/Save.js", apiKey, args);

        Similarly we can also change the slog of the story. It's important to realize though that the slug is shared by all formats of a story. Consequently it's a property of an object called "Story Version". The id of the story version can be found from the original sample under the path object/<number>/story/version/id/value. Similarly to changing the story text if we look at the endpoints in the API documentation we'll find a save method for Story Version's: /inception/StoryVersion/Object/Save.js. Adapting the previous code sample we can also kodify the story versions just as easily:

        public static void setStorySlug(String url, String apiKey, long versionId, String slug) {
           Map<String, Object> args = new HashMap<>();
           args.put("id", Long.toString(storyId));
           args.put("slug", body);
           Map<String, Object> response = makeApiCall(url, "/inception/StoryVersion/Object/Save.js", apiKey, args);


        • #5
          Thank's a lot, i will try this.


          • #6
            Just to be sure : I am using Inception API 11.1 but final customer Inception Server is 12.0.7 Build 10640-6500... Is it Okay or should i change my API version ?


            • jennjarvis
              jennjarvis commented
              Editing a comment
              V12 is still in limited release to a select number of customers. The API you are using is the released API and will be updated when V12 is made a general release.

          • #7
            Does anyone has an answer for the previous post ?