A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Render API is how an app or AI agent manages a Render account: listing and creating services, triggering and rolling back deploys, setting environment variables, and provisioning Postgres and Key Value databases. Access is granted through a single API key sent in an Authorization header, and that key reaches every workspace the account belongs to, with no narrower per-method permissions to set. Render can also push events to a webhook URL when something happens to a service, like a deploy finishing or a server failing.
How an app or AI agent connects to Render determines what it can reach. There are two routes, the REST API for making calls and webhooks for receiving events, plus a first-party MCP server, and each is governed by the API key behind it.
The REST API answers at https://api.render.com/v1. It is a single, dated-version-free surface, served under the v1 path, that covers services, deploys, databases, environment variables, disks, and account management.
Render runs a first-party hosted Model Context Protocol server at https://mcp.render.com/mcp, generally available since 21 August 2025. It lets an agent create and inspect services and databases, read deploy history, filter logs, read metrics, run read-only Postgres queries, and update a service's environment variables. It authenticates with a Render API key, and the source is at github.com/render-oss/render-mcp-server.
Webhooks deliver the chosen events to a receiver URL, so an app or agent is notified when something happens to a service instead of polling, such as a deploy starting or ending, a build finishing, or a server failing.
A Render API key is created from the account settings page in the Render Dashboard and sent as 'Authorization: Bearer
The Render API is split into areas an agent can act on, such as services, deploys, databases, and environment variables. Each area has its own methods, and a single API key reaches every workspace the account belongs to.
List, read, create, update, and delete services, and suspend, resume, restart, or scale them.
List and read deploys, trigger a new deploy, cancel a running one, and roll a service back.
List, read, add, and remove the custom domains attached to a service.
List, read, add, update, and delete a service's environment variables.
List, read, create, and cancel one-off jobs that run a command against a service.
List, read, create, update, and delete Postgres databases, and read their connection info.
List, read, create, and delete Key Value (Redis-compatible) instances.
List, read, add, and delete the persistent disks attached to a service.
List the workspaces an API key can reach and read a single workspace.
List, read, create, update, and delete the webhooks that deliver Render events.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
ServicesList, read, create, update, and delete services, and suspend, resume, restart, or scale them.7 | ||||||
| GET | /v1/services | List the services in the workspaces an API key can reach. | read | — | Current | |
Render has no per-endpoint scopes; the API key reaches every service in every workspace its owner belongs to. Acts onservice Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit400 / minute (GET) SourceOfficial documentation ↗ | ||||||
| GET | /v1/services/{serviceId} | Retrieve a single service's details. | read | — | Current | |
Any valid API key whose owner can see the service can read it. Acts onservice Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit400 / minute (GET) SourceOfficial documentation ↗ | ||||||
| POST | /v1/services | Create a new service, such as a web service, static site, background worker, or cron job. | write | — | Current | |
No scope limits this; any valid key can create services. Held to 20 per hour. Acts onservice Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit20 / hour SourceOfficial documentation ↗ | ||||||
| PATCH | /v1/services/{serviceId} | Update a service's settings. | write | — | Current | |
A PATCH updates only the fields sent, and sending null on a field unsets it. Held to 10 per minute per service. Acts onservice Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit10 / minute / service SourceOfficial documentation ↗ | ||||||
| DELETE | /v1/services/{serviceId} | Delete a service. | write | — | Current | |
No scope limits this; any valid key can delete a service the account can reach. Acts onservice Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit30 / minute (POST/PATCH/DELETE) SourceOfficial documentation ↗ | ||||||
| POST | /v1/services/{serviceId}/suspend | Suspend a running service. | write | — | Current | |
Suspending stops the service from running until it is resumed. Acts onservice Permission (capability)None required VersionAvailable since the API’s base version Webhook event service_suspendedRate limit30 / minute (POST/PATCH/DELETE) SourceOfficial documentation ↗ | ||||||
| POST | /v1/services/{serviceId}/resume | Resume a suspended service. | write | — | Current | |
Resuming starts a service that was previously suspended. Acts onservice Permission (capability)None required VersionAvailable since the API’s base version Webhook event service_resumedRate limit30 / minute (POST/PATCH/DELETE) SourceOfficial documentation ↗ | ||||||
DeploysList and read deploys, trigger a new deploy, cancel a running one, and roll a service back.5 | ||||||
| GET | /v1/services/{serviceId}/deploys | List the deploys for a service. | read | — | Current | |
Any valid key whose owner can see the service can read its deploy history. Acts ondeploy Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit400 / minute (GET) SourceOfficial documentation ↗ | ||||||
| GET | /v1/services/{serviceId}/deploys/{deployId} | Retrieve a single deploy. | read | — | Current | |
Reads the status and detail of one deploy. Acts ondeploy Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit400 / minute (GET) SourceOfficial documentation ↗ | ||||||
| POST | /v1/services/{serviceId}/deploys | Trigger a new deploy for a service. | write | — | Current | |
Triggering a deploy ships new code or configuration. Held to 10 per minute per service. Acts ondeploy Permission (capability)None required VersionAvailable since the API’s base version Webhook event deploy_startedRate limit10 / minute / service SourceOfficial documentation ↗ | ||||||
| POST | /v1/services/{serviceId}/deploys/{deployId}/cancel | Cancel a deploy that is in progress. | write | — | Current | |
Cancels a running deploy before it completes. Acts ondeploy Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit10 / minute / service SourceOfficial documentation ↗ | ||||||
| POST | /v1/services/{serviceId}/rollback | Roll a service back to a previous deploy. | write | — | Current | |
A rollback redeploys an earlier version, so it changes what is live. Held to 10 per minute per service. Acts ondeploy Permission (capability)None required VersionAvailable since the API’s base version Webhook event deploy_startedRate limit10 / minute / service SourceOfficial documentation ↗ | ||||||
Custom domainsList, read, add, and remove the custom domains attached to a service.3 | ||||||
| GET | /v1/services/{serviceId}/custom-domains | List the custom domains attached to a service. | read | — | Current | |
Reads the domains pointing at a service. Acts oncustom domain Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit400 / minute (GET) SourceOfficial documentation ↗ | ||||||
| POST | /v1/services/{serviceId}/custom-domains | Add a custom domain to a service. | write | — | Current | |
Adding a domain changes where a service is reachable. Held to 50 per hour. Acts oncustom domain Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit50 / hour SourceOfficial documentation ↗ | ||||||
| DELETE | /v1/services/{serviceId}/custom-domains/{customDomainIdOrName} | Remove a custom domain from a service. | write | — | Current | |
Removing a domain stops the service answering on it. Acts oncustom domain Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit30 / minute (POST/PATCH/DELETE) SourceOfficial documentation ↗ | ||||||
Environment variablesList, read, add, update, and delete a service's environment variables.3 | ||||||
| GET | /v1/services/{serviceId}/env-vars | List a service's environment variables. | read | — | Current | |
Environment variables can hold secrets, and any valid key that can see the service can read them. Acts onenvironment variable Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit400 / minute (GET) SourceOfficial documentation ↗ | ||||||
| PUT | /v1/services/{serviceId}/env-vars/{envVarKey} | Add or update a single environment variable on a service. | write | — | Current | |
Setting an environment variable changes service configuration and can write a secret. Acts onenvironment variable Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit30 / minute (POST/PATCH/DELETE) SourceOfficial documentation ↗ | ||||||
| DELETE | /v1/services/{serviceId}/env-vars/{envVarKey} | Delete a single environment variable from a service. | write | — | Current | |
Removing a variable can break a service that depends on it. Acts onenvironment variable Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit30 / minute (POST/PATCH/DELETE) SourceOfficial documentation ↗ | ||||||
JobsList, read, create, and cancel one-off jobs that run a command against a service.2 | ||||||
| POST | /v1/services/{serviceId}/jobs | Create a one-off job that runs a command against a service. | write | — | Current | |
A one-off job runs an arbitrary command in the service's environment. Held to 100 per minute. Acts onjob Permission (capability)None required VersionAvailable since the API’s base version Webhook event job_run_endedRate limit100 / minute SourceOfficial documentation ↗ | ||||||
| GET | /v1/services/{serviceId}/jobs | List the one-off jobs for a service. | read | — | Current | |
Reads the history and status of a service's one-off jobs. Acts onjob Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit400 / minute (GET) SourceOfficial documentation ↗ | ||||||
Postgres databasesList, read, create, update, and delete Postgres databases, and read their connection info.4 | ||||||
| GET | /v1/postgres | List the Postgres databases an API key can reach. | read | — | Current | |
Lists databases across the workspaces the key's owner belongs to. Acts onpostgres database Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit400 / minute (GET) SourceOfficial documentation ↗ | ||||||
| POST | /v1/postgres | Create a Postgres database. | write | — | Current | |
Provisions a new managed Postgres database, which bills the account. Acts onpostgres database Permission (capability)None required VersionAvailable since the API’s base version Webhook event postgres_createdRate limit30 / minute (POST/PATCH/DELETE) SourceOfficial documentation ↗ | ||||||
| DELETE | /v1/postgres/{postgresId} | Delete a Postgres database. | write | — | Current | |
Deleting a database destroys its data; no per-key scope guards this. Acts onpostgres database Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit30 / minute (POST/PATCH/DELETE) SourceOfficial documentation ↗ | ||||||
| GET | /v1/postgres/{postgresId}/connection-info | Retrieve a Postgres database's connection info, including credentials. | read | — | Current | |
Returns the connection string and password for the database, so it exposes direct database credentials. Acts onpostgres database Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit400 / minute (GET) SourceOfficial documentation ↗ | ||||||
Key ValueList, read, create, and delete Key Value (Redis-compatible) instances.2 | ||||||
| POST | /v1/key-value | Create a Key Value (Redis-compatible) instance. | write | — | Current | |
Key Value is Render's Redis replacement, running Valkey. Creating one bills the account. Acts onkey value instance Permission (capability)None required VersionAvailable since the API’s base version Webhook event key_value_availableRate limit30 / minute (POST/PATCH/DELETE) SourceOfficial documentation ↗ | ||||||
| GET | /v1/key-value | List the Key Value instances an API key can reach. | read | — | Current | |
Lists Key Value instances across the workspaces the key's owner belongs to. Acts onkey value instance Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit400 / minute (GET) SourceOfficial documentation ↗ | ||||||
DisksList, read, add, and delete the persistent disks attached to a service.2 | ||||||
| POST | /v1/disks | Attach a persistent disk to a service. | write | — | Current | |
The service must be redeployed for the disk to take effect. Acts ondisk Permission (capability)None required VersionAvailable since the API’s base version Webhook event disk_createdRate limit30 / minute (POST/PATCH/DELETE) SourceOfficial documentation ↗ | ||||||
| DELETE | /v1/disks/{diskId} | Delete a persistent disk. | write | — | Current | |
Deleting a disk destroys the data stored on it. Acts ondisk Permission (capability)None required VersionAvailable since the API’s base version Webhook event disk_deletedRate limit30 / minute (POST/PATCH/DELETE) SourceOfficial documentation ↗ | ||||||
WorkspacesList the workspaces an API key can reach and read a single workspace.2 | ||||||
| GET | /v1/owners | List the workspaces an API key can reach, optionally filtered by name or owner email. | read | — | Current | |
Shows every workspace the key reaches; the path is /owners, the legacy name for workspaces. Acts onworkspace Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit400 / minute (GET) SourceOfficial documentation ↗ | ||||||
| GET | /v1/owners/{ownerId} | Retrieve a single workspace. | read | — | Current | |
Reads the detail of one workspace the key belongs to. Acts onworkspace Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit400 / minute (GET) SourceOfficial documentation ↗ | ||||||
WebhooksList, read, create, update, and delete the webhooks that deliver Render events.3 | ||||||
| GET | /v1/webhooks | List the webhooks registered in a workspace. | read | — | Current | |
Reads the configured webhook subscriptions. Acts onwebhook Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit400 / minute (GET) SourceOfficial documentation ↗ | ||||||
| POST | /v1/webhooks | Create a webhook that delivers Render events to a receiver URL. | write | — | Current | |
Registers a URL to receive chosen event types, such as deploy_ended or server_failed. Acts onwebhook Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit30 / minute (POST/PATCH/DELETE) SourceOfficial documentation ↗ | ||||||
| DELETE | /v1/webhooks/{webhookId} | Delete a webhook. | write | — | Current | |
Removing a webhook stops its event deliveries. Acts onwebhook Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit30 / minute (POST/PATCH/DELETE) SourceOfficial documentation ↗ | ||||||
Render can notify an app or AI agent when something happens to a service, instead of the app repeatedly asking. Render posts the event payload to a webhook URL that has been registered for the chosen events, such as a deploy starting or a server failing.
| Event | What it signals | Triggered by |
|---|---|---|
deploy_started | Fires when a deploy starts for a service. | /v1/services/{serviceId}/deploys/v1/services/{serviceId}/rollback |
deploy_ended | Fires when a deploy finishes, carrying a status field that says whether it succeeded, failed, or was canceled. | In-app only |
build_ended | Fires when a build finishes, with a status field showing success, failure, or cancellation. | In-app only |
server_failed | Fires when a running service fails at runtime. | In-app only |
service_suspended | Fires when a service is suspended. | /v1/services/{serviceId}/suspend |
service_resumed | Fires when a suspended service is resumed. | /v1/services/{serviceId}/resume |
job_run_ended | Fires when a one-off job run finishes. | /v1/services/{serviceId}/jobs |
postgres_created | Fires when a Postgres database is created. | /v1/postgres |
key_value_available | Fires when a Key Value instance becomes available. | /v1/key-value |
disk_created | Fires when a persistent disk is created. | /v1/disks |
disk_deleted | Fires when a persistent disk is deleted. | /v1/disks/{diskId} |
Render limits how fast an app or AI agent can call, through per-minute and per-hour quotas that vary by the kind of request. Read requests get a high ceiling, while writes, deploys, and service creation are held much tighter.
Render rate-limits by the kind of request rather than by a single account-wide quota. Read requests, the GET methods, get 400 per minute. Other writes, the POST, PATCH, and DELETE methods, get 30 per minute. On top of that, several actions carry their own tighter limits: service updates and deploys are capped at 10 per minute per service, log endpoints at 30 per minute, one-off jobs at 100 per minute, adding custom domains at 50 per hour, and creating new services at 20 per hour. Every response carries the Ratelimit-Limit, Ratelimit-Remaining, and Ratelimit-Reset headers, where Ratelimit-Reset is a UTC epoch second, so a client can see how much headroom is left. Exceeding a limit returns a 429, and Render recommends retrying on an exponential backoff schedule with random jitter.
List endpoints use cursor-based pagination. A request takes a limit parameter, which defaults to 20 and tops out at 100, and a cursor parameter, which is a string pointing at a position in the result list. Each response returns a cursor to pass to the next request, and following it walks the full list rather than building page numbers by hand.
Requests and responses are JSON. The page size is capped at 100 results per request through the limit parameter. Render does not document a single overall payload size ceiling across the whole API.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Bad Request | The request was malformed or a parameter was invalid. The body is a JSON object with id and message fields describing what went wrong. | Read the message field, fix the named parameter or body, and resend. |
| 401 | Unauthorized | Authorization information is missing or invalid. The API key was absent, malformed, or revoked. | Send a valid key in the Authorization header as 'Bearer |
| 404 | Not Found | The resource does not exist, or the API key's owner cannot reach it. Render returns 404 rather than confirming a resource the key cannot see. | Confirm the id is correct and the key's owner has access to that workspace. |
| 406 | Not Acceptable | Render cannot produce a response in the media type the Accept request header asked for. | Set the Accept header to application/json. |
| 429 | Too Many Requests | A rate limit was exceeded for the request type, such as more than 400 GETs per minute or more than 30 other writes per minute. | Check the Ratelimit-Reset header for the window reset, then retry with exponential backoff and random jitter. |
| 500 | Internal Server Error | An unexpected server error occurred on Render's side. The body carries id and message fields. | Retry after a short delay, and contact Render support if it persists. |
| 503 | Service Unavailable | The API is temporarily unavailable. | Retry after a short delay with backoff. |
Render serves a single, dated-version-free REST API under the v1 path. Changes ship continuously through release notes rather than as numbered versions an integration pins.
Render serves a single REST API under the v1 path at https://api.render.com/v1, with no dated versions to pin. New capabilities ship continuously through release notes rather than as numbered versions, so an integration always calls the same surface. The notable additions below are dated from Render's changelog.
Blueprint files, Render's infrastructure-as-code definitions, can be validated through the CLI or API before they are applied.
Webhooks for actions that finish now include a status field, so a receiver knows the outcome without a follow-up call.
Workspace and organization audit log events can be exported through the API.
Render's first-party Model Context Protocol server reached general availability, letting an AI agent manage Render in natural language. The hosted server answers at https://mcp.render.com/mcp and authenticates with a Render API key.
The API expanded to cover event webhooks, metrics streaming, and workspace member management.
New in-memory instances run Valkey 8, an open-source fork of Redis, under the Key Value name. Instances stay Redis-client compatible, and the older /redis endpoints are deprecated in favor of /key-value.
There is no version header to set; the v1 API is updated in place.
Render changelog ↗Bollard AI sits between a team's AI agents and Render. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.