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 the #api-private channel in chat 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"
  }
}
'