Skip to main content

Getting Started with the Tilaa GraphQL API

The Tilaa GraphQL API allows you to programmatically manage our modern cloud services, such as Serverless Containers and Cloud Databases.

Which API do I need?
  • GraphQL API: For Containers and Cloud Database.
  • REST API: For managing standard VPS instances and Big Disks. (See REST Documentation).

1. Prerequisites & Safety

Before you begin, we strongly recommend creating a dedicated API User rather than using your main account credentials.

  • Create a new user in the dashboard with a unique email address.
  • This isolates API access and allows you to revoke credentials without affecting your master account.
  • Read: How to create an extra user
Live Environment Warning:
The API interacts directly with the production environment. There is no sandbox. Mutations (create/delete actions) are executed immediately and will result in billable resources or data loss if used incorrectly.

2. Authentication

The API uses OAuth 2.0 Bearer Tokens. You must exchange your username (email) and password for an access token.

Step A: Get an Access Token

Run the following curl command in your terminal:

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

Response: You will receive a JSON object containing an access_token. This token is valid for 1800 seconds (30 minutes).

Step B: Refreshing the Token

When the token expires, use the refresh_token from the previous response to get a new one without re-entering credentials:

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

3. Using the Playground (Explorer)

The easiest way to learn the API schema is via our interactive Playground. Here you can click together your queries and see the documentation for every field.

  • URL: https://graphql.tilaa.com/
  • Note: You still need to obtain a token via step 2 and insert it into the "Headers" section of the playground.

4. Example Operations

Endpoint: https://graphql.tilaa.com/graphql/platform
Headers: Authorization: Bearer <YOUR_ACCESS_TOKEN>

Query Example (Read Data)

Retrieve your account details:

query GetAccountInfo {
  account {
    id
    email
    customer {
      id
      address {
        city
        country
      }
    }
  }
}

Mutation Example (Write Data)

Create a new container:

mutation CreateContainer {
  createContainer(
    containerInput: {
      name: "my-test-container",
      image: "nginx:latest",
      namespaceId: 10,
      resourceSpecificationId: 10
    }
  )
}

5. Handling Responses & Errors

Unlike REST, GraphQL always returns a 200 OK status, even if there are logical errors.

  • Success: The JSON contains a data object.
  • Failure: The JSON contains an errors array with detailed messages.

Error Example:

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