Using the API

Render’s GraphQL API is used by the dashboard for all user operations. This API is not meant for public consumption but may be used temporarily until our public REST API is fully released. We will post in Render Community if any of the endpoints below change.

Public REST API (Early Access Available Now)

We are currently developing a user-facing REST API, which we encourage you to switch to if you’re currently using our GraphQL API.

Currently, our REST API is in Early Access, and we are gradually releasing endpoints as they’re made available. To see what endpoints are currently in Early Access, check out our Early Access API Docs. To be added to Early Access, email us at support@render.com. For discussion and questions, you can use the REST API Early Access category in our Community forum.

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"
  }
}
'