New: Flexible Plans for Render PostgreSQL

Learn more
July 18, 2024

Building Custom Integrations with the Render API

W Ian Douglas
Last week, we shipped over 50 new capabilities in the Render API—including endpoints for datastores, service logs, and Blueprints. The API now supports nearly every action available in the Render Dashboard, which means you can use it to build some seriously powerful automations. We've also published the OpenAPI specification for the API, which you can import into tools like Postman or Insomnia to create collections and test suites. There's a lot to try out! Let's get set up with the Render API, then look at some example use cases to help inspire your first integration.
After you build your own scripts with the Render API, we welcome pull requests to our example repo.

Create your API key

To start using the Render API, you'll first need an API key to include as a bearer token with each request. You can create API keys from your Account Settings page in the Render Dashboard:
Creating an API key in the Render Dashboard
Creating an API key in the Render Dashboard
Don't share your API key outside your team or commit it to version control! Your API key authorizes all of the same actions that you can perform while logged in to the Render Dashboard. Revoke any API key that might be compromised.
This Python example shows how to provide the API key in the Authorization header of a request. The other examples in the repo import this logic to make their specific calls.

Explore your options

With an API key ready to go, you can dive into the full API reference to see everything that's possible. First, take a look at some example workflows you can borrow or build from for your own integrations:

1. Trigger an off-schedule cron job run

Let's start with a quick one: your cron jobs usually run on a predefined schedule, but sometimes you might want to kick one off immediately. For example, the cron job might handle clearing a particular cache or generating a (usually) daily report that you need right away. In this case, you can use the Trigger cron job run endpoint, which only requires the ID of the cron job to start. Cron job IDs are available from the List services endpoint and in the Render Dashboard. Note that Render only runs one instance of any cron job at a time, so this endpoint terminates any existing run before kicking off a new one! See the example code.

2. Autoscale with custom logic

Render can autoscale your services based on their CPU and/or memory usage, but different scaling criteria might work better for your use case. With the Scale instance count endpoint, you can add and remove instances based on any logic you choose. Let's say we have a background worker service that pulls jobs from a Redis queue. As the queue's size changes over time, we want to spin worker instances up or down to match the current load. To tackle this, we can create a cron job that periodically does the following:
  1. Connect to the Redis instance and fetch the current queue size
  2. Calculate the optimal number of workers based on current load (for example: one instance for every 1,000 queued jobs, up to a max of 10 instances)
  3. Update our worker instance count with the Scale instance count endpoint
See the example code.

3. Analyze deploy times and other metrics

The Render Dashboard provides a view into every service's behavior and performance, but you can also create custom visualizations and reports to monitor the state of your infrastructure. Take deploy times as an example. You can use the API to identify which of your services take the longest to deploy, and whether a given service is suddenly taking longer than it used to. Plus, you can pull that data into a visualization tool like Grafana, or even a basic spreadsheet. Here's what those steps might look like:
  1. Fetch your services and their IDs with the List services endpoint.
  2. For each service, use the List deploys endpoint to one or more of its recent deploys.
  3. Calculate each deploy's total duration based on its createdAt and finishedAt fields.
  4. Format the data and import it into your preferred visualization tool.
See the example code. And deploy times are just the tip of the metrics iceberg—the API provides endpoints for fetching time series data of CPU, memory, disk usage, and more.

Share your creations

We can't wait to see all the ways you incorporate the Render API into your own scripts, apps, and CI/CD workflows. If you build an integration you'd like to contribute as an example, let us know by submitting a pull request to the render-api-examples repo.