Developer guide

Plainly’s REST API enables you to build custom video automation workflows or embed Plainly features directly in your own product.

This guide is written for developers who intend to interact with Plainly programmatically. We assume you are comfortable working with HTTP APIs and are familiar with concepts such as authentication headers, JSON request bodies and asynchronous processing.

Core concepts

Before diving into the technical details let’s review the three key resources of the API: projects, templates, and renders. A project represents an uploaded After Effects package. Each project can have one or more templates that define which layers are variable and can be populated with data when generating a video. Once you are ready to create a video you trigger a render, referencing a specific template and providing the data for its parameters. The render is processed on Plainly’s infrastructure and eventually results in an output file you can download.

Everything is an object

Everything in Plainly is an object, whether you create it with the API or not. Your uploaded project corresponds to a Project object, you create videos with Render objects, and so on.

Even native integrations produce these objects. So do actions you perform in the web-app. For instance, when you manually upload a project in the Dashboard, it still creates a Project object.

Objects have states

Each object has a state that indicates its current status. This is sometimes referred to as a state machine, and a state defines what actions you can perform on an object.

For example, when you call the API to create a render you will receive a response immediately, typically with a state like Pending. The render then moves through the states Queued and In-progress until it finally reaches Done or Failed. For instance, the Cancel render action can only be executed before a render reaches the In-progress state.

Asynchronous processing

Rendering a video takes time. Depending on the project complexity and system load, Plainly will need some time to render your video.

The usual way of getting notified about results of asynchronous processing is to use webhooks or polling. When possible, we always recommend using webhooks, as they allow you to receive instant notifications and avoid the need for constant polling.

Integration approaches

Full white label

A full white‑label integration gives your end users the ability to upload projects and define templates themselves. Your application interacts with every aspect of the API: creating projects, generating templates and finally triggering renders. This approach is suitable for companies building a product on top of Plainly where you do not want users to ever see the Plainly interface. You maintain full control over the user experience and simply use Plainly as a back‑end rendering service.

An example use-case for full white-label integration is an AdTech platform that allows users to create ads using their own After Effects projects.

Render only

A simpler approach is the render‑only integration. In this scenario you manage your projects and templates through the Plainly web app. Your application then only interacts with the renders endpoint, supplying the necessary project and template IDs and render parameter values. This method works well if you are building an automation flow based on the fixed set of templates you have created. You can trigger rendering on any event (user performing an action, system event happens, scheduled triggers, etc) and have the convenience of managing projects and templates in the UI.

For example, a use-case for render-only integration is scheduled weather forecast videos or CMS extension that supports video creation once a new blog post is published.

Hybrid

Some products require a middle ground. Perhaps you want to manage templates in the Plainly web interface but allow your users to fill in dynamic forms. The API lets you retrieve a template’s parameter definitions so you can build those forms programmatically. Users never need to see the Plainly UI, yet you avoid the complexity of exposing project uploads.

As an example, a hybrid integration could be used by digital agencies to expose a simple form to clients or internal teams where they can select a video template and provide data.

API limitations

While the API is comprehensive in terms of features it intentionally omits many aspects of organization management. You cannot create or delete API keys programmatically, nor can you manipulate team members or adjust billing settings. Those actions remain in the Plainly web application to keep the REST surface small and secure.

The API also does not provide endpoints to configure the native integrations such as Google Drive delivery for example. You can however deliver notifications to your third‑party services using webhooks and process the finished video in your own backend.

Start building

The following sections dive deeper into specific areas. We encourage you to experiment with the API as you read through the following pages.

Remember that we have a complete API reference  where each endpoint is described in detail with request and response schemas. Keep that reference handy while following guides to clarify any parameters that are not fully covered here.