HTTP API

Eko provides a set of APIs to support customers who want a deeper personalization of eko projects within their applications. Once your app has been registered via eko representative, the HTTP API allows to override features of one of your project, or a set of projects using a config file.

Base URL: api.eko.com/

Authentication


To use the api, authenticate your requests using the API key given to you by eko when registered your app. Contact us for help.
Use:

  • As x-authentication in the header params.

API Endpoints:



/v1/projects/{projectId}

Param Type Description
projectId string Id of the project you wish to get

GET

Public route to get a project object by it’s id
This route does not require authentication.



/v1/{appId}/configs

Param Type Description
appId string A unique appId provided by eko

GET

Retrieve all of the config objects defined via your API key.
Returns an array of configs (JSON objects).

POST

Create a new config and link it to a list of project ids.
All of the projects should be linked to the app.

Body Parameters:
schema: config_post_schema



/v1/{appId}/configs/{configId}

Param Type Description
appId string A unique appId provided by eko
configId string Id of the config object you wish to get

GET

Retrieve the config object. The config includes an array of projects that are linked to it, and the override it defines.
Returns a config (JSON object).

PUT

Update either the list of projects that are linked to this config or the overrides settings this config defines.
Config should be linked to the app.

Body Parameters:
schema: config_put_schema

DELETE

Delete a config and remove this config from all of the projects it was linked to.
Config should be linked to the app.



/v1/{appId}/projects/{projectId}

Param Type Description
appId string A unique appId provided by eko
projectId string Id of the project you wish to get

GET

Gets project by its Id. Will merge the project model with any overrides defined in any configs linked to the project.
Upon creation in eko-Studio, the creating user must be a part of the app (API key).

PUT

Updates an existing project. Information that can be updated includes project title, project description, project thumbnail, and duration.
Upon creation in eko-Studio, the creating user must be a part of the app (API key).

Body Parameters:
schema: project_overrides_schema



/v1/{appId}/configs/{configId}/projects

Param Type Description
appId string A unique appId provided by eko
configId string Id of the config object you wish to get

GET

Get all the projects that are linked to this config.
Returns an array of projects (JSON objects)



/v1/{appId}/configs/{configId}/projects/{projectId}

Param Type Description
appId string A unique appId provided by eko
configId string Id of the config object you wish to get
projectId string Id of the project you wish to get

POST

Add a project to the list of projects this config is linked to.
Upon creation in eko-Studio, the creating user must be a part of the app (API key)

DELETE

Unlinks a project from this config (removed the project from the config’s list of projects).
Upon creation in eko-Studio, the creating user must be a part of the app (API key)



Our Models

project_overrides_schema

{
  "title": {
    "description": "The title of the project",
    "type": "string",
    "example": "#TMW"
  },
  "description": {
    "description": "The description of the project",
    "type": "string",
    "example": "Help Jill figure out his name!"
  },
  "thumbnail": {
    "description": "A URL of an image to be used as the thumbnail",
    "type": "string",
    "example": "https://d1ux84wfod9ezj.cloudfront.net/efu/upload/b706223d6acae0a7f478f77e2eb82be7.jpg"
  },
  "duration": {
    "description": "The duration of the project playthrough",
    "type": "number",
    "example": "420"
  },
  "canonicalUrl": {
    "description": "Sets the canonical tag",
    "type": "string",
    "example": "https://eko.com/v/101"
  },
  "checkpoints": {
    "enableResume": {
      "description": "Toggle on to save video watching progress. When the user navigates away from the video and comes back, there will be an option to resume or start over from the beginning.",
      "type": "boolean"
    },
    "enableSkipForward": {
      "description": "Enable skipping forwards in the video",
      "type": "boolean"
    },
    "enableSkipBackward": {
      "description": "Enable skipping backwards in the video.",
      "type": "boolean"
    }
  },
  "forceAudioLocked": {
    "description": "When set to true, audio will be forced to mute until the first interaction",
    "type": "boolean"
  },
  "metadata": {
    "type": "object"
  },
  "autoUpdateRevision": {
    "description": "Show the most recent publish from Eko Studio. Turn off to \"lock\" the delivery to a specific revision from Eko Studio.",
    "type": "boolean"
  },
  "kidsContent": {
    "description": "If turned on, EkoAnalytics will be disabled and send no events. The externalanalytics plugin will be disabled, disabling GTM and GA in the player/child frame and GTM and GA will be removed from the parent frame. IA will still send events.",
    "type": "boolean"
  },
  "playerSkin": {
    "components": {
      "pauseScreen": {
        "watchTime": {
          "description": "Show/hide the time remaining.",
          "type": "boolean"
        },
        "title": {
          "description": "Show/hide the title",
          "type": "boolean"
        },
        "subTitle": {
          "description": "Show/hide the sub title",
          "type": "boolean"
        },
        "startOver": {
          "description": "Show the start over button",
          "type": "boolean"
        },
        "background": {
          "description": "Valid CSS value for the background of the pause screen (can include gradients, image, etc)",
          "type": "string"
        }
      },
      "bufferingScreen": {
        "title": {
          "description": "Show/hide the title",
          "type": "boolean"
        }
      },
      "shareButton": {
        "icon": {
          "default": {
            "description": "URL of default share icon to use",
            "type": "string"
          },
          "ios": {
            "description": "URL of share icon to use on iOS",
            "type": "string"
          }
        },
        "location": "One of the following: topRight,bottomRight,false",
        "order": {
          "description": "Ordering on the screen from left to right",
          "type": "integer"
        }
      },
      "subtitlesButton": {
        "icon": {
          "enabled": {
            "description": "URL of icon to use for enabling subtitles",
            "type": "string"
          },
          "disabled": {
            "description": "URL of icon to use for disabling subtitles",
            "type": "string"
          }
        },
        "location": "One of the following: topRight,bottomRight,false",
        "order": {
          "description": "Ordering on the screen from left to right",
          "type": "integer"
        }
      },
      "volumeButton": {
        "icon": {
          "default": {
            "description": "URL of default volume icon to use",
            "type": "string"
          },
          "muted": {
            "description": "URL of muted volume icon to use",
            "type": "string"
          }
        },
        "location": "One of the following: topRight,bottomRight,false",
        "order": {
          "description": "Ordering on the screen from left to right",
          "type": "integer"
        }
      },
      "fullscreenButton": {
        "icon": {
          "maximize": {
            "description": "URL of maximize icon to use",
            "type": "string"
          },
          "minimize": {
            "description": "URL of minimize icon to use",
            "type": "string"
          }
        },
        "location": "One of the following: topRight,bottomRight,false",
        "order": {
          "description": "Ordering on the screen from left to right",
          "type": "integer"
        }
      },
      "customButtons": [
        {
          "id": {
            "description": "Id of custom button",
            "type": "string"
          },
          "icon": {
            "description": "URL of an SVG (icon for the button)",
            "type": "string"
          },
          "location": "One of the following: topRight,bottomRight,false",
          "order": {
            "description": "Ordering on the screen from left to right",
            "type": "integer"
          },
          "label": {
            "description": "Accessability label (aria) of custom button",
            "type": "string"
          }
        }
      ],
      "theme": {
        "colors": {
          "highlightColor": {
            "description": "Any valid CSS to use for the highlight color",
            "type": "string"
          }
        },
        "font": {
          "title": {
            "description": "Google fonts family name",
            "type": "string"
          },
          "paragraph": {
            "description": "Google fonts family name",
            "type": "string"
          }
        }
      }
    },
    "muteMessage": {
      "showMuteMessage": {
        "description": "Show the \"tap to unmute\" message if browser equires interaction to play audio of video",
        "type": "boolean"
      },
      "muteMessageTimer": {
        "description": "The length of time to show the mute message",
        "type": "integer"
      }
    }
  }
}

config_put_schema

{
  "projects": [
    "string"
  ],
  "overrides": "schema: project_overrides_schema"
}

config_post_schema

{
  "id": {
    "description": "A unique id (within the app id scope) for this config",
    "type": "string",
    "example": "age_under_14"
  },
  "projects": [
    "string"
  ],
  "overrides": "schema: project_overrides_schema"
}

project_response

{
  "id": {
    "type": "string",
    "example": "MebL1z"
  },
  "revision": {
    "type": "number",
    "example": 1
  },
  "orientation": {
    "type": "string",
    "example": "horizontal"
  },
  "title": {
    "description": "The title of the project",
    "type": "string",
    "example": "#TMW"
  },
  "description": {
    "description": "The description of the project",
    "type": "string",
    "example": "Help Jill figure out his name!"
  },
  "thumbnail": {
    "description": "A URL of an image to be used as the thumbnail",
    "type": "string",
    "example": "https://d1ux84wfod9ezj.cloudfront.net/efu/upload/b706223d6acae0a7f478f77e2eb82be7.jpg"
  },
  "duration": {
    "description": "The duration of the project playthrough",
    "type": "number",
    "example": "420"
  },
  "canonicalUrl": {
    "description": "Sets the canonical tag",
    "type": "string",
    "example": "https://eko.com/v/101"
  },
  "checkpoints": {
    "enableResume": {
      "description": "Toggle on to save video watching progress. When the user navigates away from the video and comes back, there will be an option to resume or start over from the beginning.",
      "type": "boolean"
    },
    "enableSkipForward": {
      "description": "Enable skipping forwards in the video",
      "type": "boolean"
    },
    "enableSkipBackward": {
      "description": "Enable skipping backwards in the video.",
      "type": "boolean"
    }
  },
  "forceAudioLocked": {
    "description": "When set to true, audio will be forced to mute until the first interaction",
    "type": "boolean"
  },
  "metadata": {
    "type": "object"
  },
  "autoUpdateRevision": {
    "description": "Show the most recent publish from Eko Studio. Turn off to \"lock\" the delivery to a specific revision from Eko Studio.",
    "type": "boolean"
  },
  "kidsContent": {
    "description": "If turned on, EkoAnalytics will be disabled and send no events. The externalanalytics plugin will be disabled, disabling GTM and GA in the player/child frame and GTM and GA will be removed from the parent frame. IA will still send events.",
    "type": "boolean"
  },
  "playerSkin": {
    "components": {
      "pauseScreen": {
        "watchTime": {
          "description": "Show/hide the time remaining.",
          "type": "boolean"
        },
        "title": {
          "description": "Show/hide the title",
          "type": "boolean"
        },
        "subTitle": {
          "description": "Show/hide the sub title",
          "type": "boolean"
        },
        "startOver": {
          "description": "Show the start over button",
          "type": "boolean"
        },
        "background": {
          "description": "Valid CSS value for the background of the pause screen (can include gradients, image, etc)",
          "type": "string"
        }
      },
      "bufferingScreen": {
        "title": {
          "description": "Show/hide the title",
          "type": "boolean"
        }
      },
      "shareButton": {
        "icon": {
          "default": {
            "description": "URL of default share icon to use",
            "type": "string"
          },
          "ios": {
            "description": "URL of share icon to use on iOS",
            "type": "string"
          }
        },
        "location": "One of the following: topRight,bottomRight,false",
        "order": {
          "description": "Ordering on the screen from left to right",
          "type": "integer"
        }
      },
      "subtitlesButton": {
        "icon": {
          "enabled": {
            "description": "URL of icon to use for enabling subtitles",
            "type": "string"
          },
          "disabled": {
            "description": "URL of icon to use for disabling subtitles",
            "type": "string"
          }
        },
        "location": "One of the following: topRight,bottomRight,false",
        "order": {
          "description": "Ordering on the screen from left to right",
          "type": "integer"
        }
      },
      "volumeButton": {
        "icon": {
          "default": {
            "description": "URL of default volume icon to use",
            "type": "string"
          },
          "muted": {
            "description": "URL of muted volume icon to use",
            "type": "string"
          }
        },
        "location": "One of the following: topRight,bottomRight,false",
        "order": {
          "description": "Ordering on the screen from left to right",
          "type": "integer"
        }
      },
      "fullscreenButton": {
        "icon": {
          "maximize": {
            "description": "URL of maximize icon to use",
            "type": "string"
          },
          "minimize": {
            "description": "URL of minimize icon to use",
            "type": "string"
          }
        },
        "location": "One of the following: topRight,bottomRight,false",
        "order": {
          "description": "Ordering on the screen from left to right",
          "type": "integer"
        }
      },
      "customButtons": [
        {
          "id": {
            "description": "Id of custom button",
            "type": "string"
          },
          "icon": {
            "description": "URL of an SVG (icon for the button)",
            "type": "string"
          },
          "location": "One of the following: topRight,bottomRight,false",
          "order": {
            "description": "Ordering on the screen from left to right",
            "type": "integer"
          },
          "label": {
            "description": "Accessability label (aria) of custom button",
            "type": "string"
          }
        }
      ],
      "theme": {
        "colors": {
          "highlightColor": {
            "description": "Any valid CSS to use for the highlight color",
            "type": "string"
          }
        },
        "font": {
          "title": {
            "description": "Google fonts family name",
            "type": "string"
          },
          "paragraph": {
            "description": "Google fonts family name",
            "type": "string"
          }
        }
      }
    },
    "muteMessage": {
      "showMuteMessage": {
        "description": "Show the \"tap to unmute\" message if browser equires interaction to play audio of video",
        "type": "boolean"
      },
      "muteMessageTimer": {
        "description": "The length of time to show the mute message",
        "type": "integer"
      }
    }
  }
}

Example Responses


Status Description Body
200 Success
{
“success”: true,
“status”: 200,
“data”: {
“id”: {
“description”: “A unique id (within the app id scope) for this config”,
“type”: “string”,
“example”: “age_under_14”
},
“projects”: [
“string”
],
“overrides”: {
“type”: “object”
}
},
“message”: “Successful”
}
204 Deleted Successfully.
{ }
400 Payload does not conform with the model
{
“statusCode”: 400,
“error”: “Bad Request”,
“message”: “\”value\” must be an object”
}
401 Authentication token is missing (api_key query param or x-authentication token)
{
“statusCode”: 401,
“error”: “Unauthorized”,
“message”: “Missing authentication”
}
403 appId doesn’t match the token
{
“statusCode”: 403,
“error”: “Forbidden”,
“message”: “You do not have permissions for that operation”
}
404 Item not found
{
“status”: 404,
“success”: false,
“message”: “Item not found”
}
500 Item failed schema validation or unknown error
{
“status”: 500,
“success”: false,
“message”: “Failed for unknown reason”
}
Rate this page: X
Tell us more!