Using the API
Render’s GraphQL API is used by the dashboard for all user operations. This API is not meant for public consumption yet, but we try our best to maintain backwards compatibility. We will post in Render Community if any of the endpoints below change.
GraphQL Schema
type Mutation {
createCustomDomain(customDomain: CustomDomainInput!): CustomDomain
deleteCustomDomain(id: String!): Boolean!
refreshCustomDomainStatus(id: String!): Boolean!
signIn(email: String, password: String!): AuthResult
updateServerInstanceCount(id: String!, count: Int!): Server
}
type Query {
server(id: String!): Server
}
type AuthResult {
idToken: String
user: User
}
input CustomDomainInput {
name: String!
serverId: String!
}
type CustomDomain {
id: String!
isApex: Boolean!
name: String!
publicSuffix: String
redirectForName: String
server: Server!
verified: Boolean!
}
type Server {
id: String!
extraInstances: Int!
}
You can make GraphQL requests to https://api.render.com/graphql with any HTTP client. It may be
convenient to use a GraphQL client in your favorite language; we’ll use curl
for this guide.
Authentication
Before you can make requests to any authorized endpoints, you need to authenticate, which will give you an ID token:
curl https://api.render.com/graphql -X POST -H 'Content-Type: application/json' -d '
{
"operationName": "signIn",
"query": "mutation signIn($email: String!, $password: String!) { signIn(email: $email, password: $password) { idToken } }",
"variables": {
"email": "test@example.com",
"password": "passw0rd"
}
}
'
The above command returns a JSON payload with the ID token for future use. This token has a short
expiration, so you should refresh it periodically. For most GraphQL requests, you’ll need to add
this token to an authorization header: Authorization: Bearer XXX
where XXX
is your token from
login.
Operations
Create a Custom Domain
Once you’ve created a web service, take note of its ID. This looks like srv-XXX
and is prominent
in the URL. Using the GraphQL API once again, you can create a custom domain with curl
:
curl https://api.render.com/graphql -X POST -H 'Content-Type: application/json' -H 'Authorization: Bearer XXX' -d '
{
"operationName": "createCustomDomain",
"query": "mutation createCustomDomain($customDomain: CustomDomainInput!) { createCustomDomain(customDomain: $customDomain) { id \n name } }",
"variables": {
"customDomain": {
"name": "www.example.com",
"serverId": "srv-XXX"
}
}
}
'
This should return the custom domain ID, which you should take note of; it looks like cd-XXX
.
Refresh Custom Domain Status
Assuming you’ve already set up DNS for the custom domain, it may still take some time to validate
the custom domain. You can refresh the status with curl
:
curl https://api.render.com/graphql -X POST -H 'Content-Type: application/json' -H 'Authorization: Bearer XXX' -d '
{
"operationName": "refreshCustomDomainStatus",
"query": "mutation refreshCustomDomainStatus($id: String!) { refreshCustomDomainStatus(id: $id) }",
"variables": {
"id": "cd-XXX"
}
}
'
Delete a Custom Domain
curl https://api.render.com/graphql -X POST -H 'Content-Type: application/json' -H 'Authorization: Bearer XXX' -d '
{
"operationName": "deleteCustomDomain",
"query": "mutation deleteCustomDomain($id: String!) { deleteCustomDomain(id: $id) }",
"variables": {
"id": "cd-XXX"
}
}
'
We’ll respond with true
if the custom domain was successfully deleted.
Change Service Instance Count
You can then update the instance count for a server using the mutation below:
curl https://api.render.com/graphql -X POST -H 'Content-Type: application/json' -H 'Authorization: Bearer XXX' -d '
{
"operationName": "updateServerInstanceCount",
"query": "mutation updateServerInstanceCount($id: String!, $count: Int!) { updateServerInstanceCount(id: $id, count: $count) { id extraInstances } }",
"variables": {
"id": "srv-XXX",
"count": "3"
}
}
'
Querying Service Instance Count
You can query the instance count for a server using the query below:
curl https://api.render.com/graphql -X POST -H 'Content-Type: application/json' -H 'Authorization: Bearer XXX' -d '
{
"operationName": "server",
"query": "query server($id: String!) { server(id: $id) { id extraInstances } }",
"variables": {
"id": "srv-XXX"
}
}
'