Authentication & setup

Every interaction with the Plainly API is authenticated using an API key. This page walks you through obtaining a key, constructing requests and handling common error scenarios.

Base endpoint and authentication

All requests are made to the following base URL:

https://api.plainlyvideos.com

The API uses HTTP Basic authentication. Your API key is sent as the username and the password is left blank.

Every response will be in JSON format. Successful calls typically return status code 200. If something goes wrong the return body will contain error details.

Example request

Here is a simple cURL command that fetches a list of recent renders:

curl -u "$PLAINLY_API_KEY:" \
     https://api.plainlyvideos.com/api/v2/renders

Replace $PLAINLY_API_KEY with your actual key or set it as an environment variable in your shell profile. You will receive a JSON array describing the renders, including their IDs and status.

Understanding errors

When an error occurs the response body typically includes two fields: message and error. The message is suitable for display in logs or dashboards. In many cases we will include the X-PlainlyErrorCode header in the response, which contains the error code and helps in categorizing errors.

{
	"timestamp": "2025-07-29T11:39:50.490+00:00",
	"status": 404,
	"error": "Not Found",
	"message": "The project with the id 9924184e-f777-4768-a99b-dde9b90dc0bb does not exist.",
	"path": "/api/v2/renders"
}

Error handling

Plainly uses conventional HTTP status codes. A few you should pay special attention to are:

Always inspect the message field in the response body for a human‑readable explanation of the problem.

Rate limiting

To protect the service from abuse each organization has a limit on the number of requests per minute. The limit is currently set to 400 requests per minute in average (per organization), and we support burst of up to 600 requests in a single minute.

When you exceed this limit the API returns 429 Too Many Requests along with a Retry-After header indicating how long you should wait before making additional calls. Build retry logic into your integration so you can handle these responses gracefully. In most cases the limits are generous enough that typical usage will not hit them, but automated batch processes can trigger them if not paced.

Versioning

The current API is versioned under /api/v2/. We strive to maintain backward compatibility but occasionally minor breaking changes are unavoidable. When a breaking change is introduced there will always be a period of time that allows API users to implement migrations.

Best practices

• Use HTTPS – All endpoints require HTTPS. Never attempt to connect over plain HTTP.
• Handle failures gracefully – Renders can fail due to missing assets, invalid parameters or internal errors. Always check the final state and handle it appropriately. You can attempt to retry failed renders if the issue is transient.
• Secure webhooks – Use HTTPS endpoints for webhook delivery. Optionally include an HMAC signature in your webhook passthrough to cryptographically verify the passthrough payload.
• Limit concurrency – If you trigger many API requests at once consider pacing your requests to avoid hitting rate limits. The API supports a large throughput but your integration should still respect the standard 429 Too Many Requests response and retry after the indicated delay.
• Keep API keys private – Use environment variables or secure secrets management to store your keys. Rotate keys periodically and revoke keys that are no longer needed. Never expose API keys in client‑side code or public repositories.
• Limit API key scope – If your organization has multiple teams consider creating separate keys for each team. You can optionally limit the amount of resources each key can conume.
• Rotate keys – Periodically generate new keys and remove old ones to reduce the risk of compromise.

FAQ

Next steps

With authentication working you are ready to explore the core functionality: triggering renders and managing projects. Continue with the Renders API page to learn how to submit a render request, or jump to Projects API if you want to start by uploading an After Effects package.