How to use Tilaa's GraphQL API

Matthijs Van Gastel

Updated May 13, 2025 09:34

Introducing Tilaa's GraphQL Cloud API:

Tilaa's public GraphQL-API provides you with a set of tools and endpoints to set up your Serverless Containers and Cloud Databases offering the ability for you to execute CRUD method on resources (e.g. containers, container jobs etc.). The request needs to be sent to https://graphql.tilaa.com/graphql/platform, these requests need to contain an authorization token and one of the following: a query or a mutation.

For managing your VPS and everything related to it, take a look at our Restful API.

Getting started:

All GraphQL API calls require Bearer Authentication.

For security reasons you cannot use your main Tilaa user account to access this API. Instead, you should add an API user to your customer account and use the specified login credentials to authenticate.

More information about creating an extra user can be found here: HowTo - Create an extra user

This will require a unique and validated email address, which we will also use to notify you about important API related announcements, such as deprecation notifications, new features and maintenance windows.

For testing the API more easily, we advise you to navigate to https://graphql.tilaa.com/ in your browser.

On this page, you can explore the API schema, compose GraphQL operations and execute them to get a response. In other words, a nice interactive playground!

Queries and Mutations

The differences between these two are as followed:

- Query: A GraphQL query is a request for data that is sent to the server. It specifies the fields that the client wants to retrieve from the server, and the server responds with the requested data in JSON format.

Example:

query MyQuery($name: String = "example") {
  namespace(name: $name) {
    privateRegistries {
      id
      name
    }
  }
}

- Mutation: A GraphQL mutation is a request to modify data on the server. it can create, update, or delete data, and it returns the modified data as a response.

Example:

mutation MyMutation($image: String = "example/test:latest", $name: String = "example", $namespaceId: Int = 10, $resourceSpecificationId: Int = 10) {
  createContainer(
    containerInput: {
      namespaceId: $namespaceId,
      resourceSpecificationId: $resourceSpecificationId,
      name: $name,
      image: $image
    }
  )
}

Responses

The response you will receive when executing a query will result in either success or failure. You do not receive status codes. When the query fails you will also get a message stating what went wrong for the query to fail, for example no resource with that specific name or the authorization token is wrong. And when the query succeeds you will naturally receive the data requested in the query.

Successful query example:

{
  "data": {
    "namespace": {
      "containerJobs": []
    }
  }
}

Failing query example:

{
  "errors": [
    {
      "message": "Not found."
    }
  ]
}

For a mutation a failing result will give similar responses. But when succeeding you will only receive a response with the action and true.

Success mutation example:

{
  "data": {
    "createContainer": true
  }
}

Failing mutation example:

{
  "errors": [
    {
      "message": "Variable \"$name\" of required type \"String!\" was not provided.",
      "locations": [
        {
          "line": 2,
          "column": 42
        }
      ]
    }
  ]
}

The fields that are required and also optional field can be found in the documentation at https://graphql.tilaa.com. You can also execute queries and mutations. To set them you can just select the attributes in the explorer.

The queries and mutations are executed on the live server and not on a sandbox environment, so keep this in mind when execution queries and mutations.

Authentication:

With your API account, you can authenticate using the following request:

curl -d 'grant_type=password&client_id=cloud-tilaa&username=&password=' -X POST https://auth.tilaa.com/realms/tilaa/protocol/openid-connect/token

In the response you'll find the OAuth 2 access token (valid for 1800 seconds). Using the access_token in the response as bearer token in all the following API calls for authentication, you can do everything you need from our platform.

Refresh access token
To get a new access token with the use of the refresh token you can use the following request:

curl -d 'grant_type=refresh_token&client_id=cloud-tilaa&refresh_token=' -X POST https://auth.tilaa.com/realms/tilaa/protocol/openid-connect/token

A refresh token is also generated which can be used to renew the access token. Check https://oauth.net/2/ for more information on OAuth.

Creating the first query:

The API is based on GraphQL. To learn more about GraphQL, visit https://graphql.org/learn/.

An example query would be to try to retrieve our account details:

query {
  account {
    id
    role
    email
    name
    customer {
        id
        tag
        address {
            streetNameAndHouseNumber
            postalCode
            city
            country
        }
        termOfPayment
        billingPeriod
        recurringPayment
        ... on Business {
            vatNumber
        }
    }
  }
}

And don't forget to add your token to the call!

The entire list of available queries is shown in the list retrieved by the browser extension.

If you have any questions, issues, or feedback, our support team is here to help. Visit our Support Page to create a ticket or reach out to support@tilaa.com.