Preguntes Freqüents - FAQ

Get your API token ready

In order to use the API, you will need an API token. Make sure to create a separate API token for each project, as each API token is bound to the project it was created in and cannot be used for other projects.

If you haven't created an API token yet, do this now. The getting started "Generating an API token" explains step by step how this is done. Make sure to copy and save the API token after it was created, as it will not be possible to view the token again.

In all example commands, $API_TOKEN will be used as a placeholder. Remember that you will have to replace $API_TOKEN with your actual API token. Example:

-H "Authorization: Bearer $API_TOKEN" \

-H "Authorization: Bearer jEheVytlAoFl7F8MqUQ7jAo2hOXASztX" \

Refer to the documentation

Go to the Cloud API documentation and use the menu bar on the left to navigate to the request that you would like to perform.

Copy the curl command

After you have navigated to the action that you would like to perform, look for "HTTP Request":

The basic structure of "HTTP Request" is <request-type> <api-url-ending>.

This tells you which curl request you will have to use. There is also an example for every request on the right of the API documentation. In this example ("HTTP Request": GET /servers), the curl command would look like this:

curl \
    -H "Authorization: Bearer $API_TOKEN" \
    'https://api.hetzner.cloud/v1/servers'

Note that you have to replace $API_TOKEN with your own API token.

3. The curl command explained
   • -X {request-type} The first line usually specifies the type of request. However, for GET requests you do not need this line.
   • -H "Authorization: Bearer $API_TOKEN" This line is where you have to add the API token. The API token is bound to a specific project. Therefore, this line defines in which project the request should be performed.
   • For POST and PUT requests, you will sometimes need to define certain properties that are needed to create or modify a resource. A property could be a name ("name":"unique-name"), or a type ("type":"ipv4"), for example. To add this information, two additional lines are needed:
   curl \
      -X POST \
      -H "Authorization: Bearer $API_TOKEN" \
   +  -H "Content-Type: application/json" \
   +  -d '{"property":value,"property":value,...}' \
      'https://api.Progressiverobot.cloud/v1/servers'

 

4. Add properties to a POST or PUT request

   When you create a new resource, or update an existing one, you will probably want to specify certain properties, such as a name or location.

   To get started quickly, you can simply copy the example curl on the right. The example curl includes the most essential properties, and you can simply edit the values, or delete properties that you don't want to specify. Note, however, that some properties are mandatory and you have to specify them in the curl command. To learn more about the properties, you can look at the explanations given below the "Request" caption. Mandatory properties are marked as required.

5. Instead of copying the curl command, you can also use the documentation below the "Request" caption. It gives you a list of all available properties along with their value type and a short description of what the property is used for.

6. To add a property to the curl command, use this format:

   curl \
      -X {request-type} \
      -H "Authorization: Bearer $API_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{"property":value,"property":value,...}' \
      'https://api.Progressiverobot.cloud/v1/{api-url-ending}'
   
   

    

7. The different value types:

   value	format
   string	"any-text"
   integer	12
   object	{"property":value}
   boolean	true false
   nullable	null

   4. Create Resource X

      Request

      ---

      name string
      Name of resource

      ---

      resource_y integer
      ID of Resource Y which you would like to add to Resource X

      ---

      labels object
      User-defined labels (key-value pairs)

      ---

      labelkeystring
      

      • New label

      ---

      delete boolean
      If true, prevents the resource from being deleted

      ---

      description string – nullable
      Description of the resource

      
      Example -d line in curl command:

      -d '{"name":"my-resource","resource_y":18,"labels":{"labelkey":"my-label"},"delete":true,"description":null}'

      
      

      When it says array of ..., you can simply use the format "property":[value]. The individual values are separated by comma:

      array of ...	format
      strings	["any-text","any-text"]
      integers	[12,43]
      objects	[{"property":value,"property":value}]

    

   5. Query Parameters

      Query parameters make it possible to refine the results that are shown for a request. For example, you could specify that only resources with a certain label should be returned.

      Format to refine the results:

      • A simple query parameter

        https://api.Progressiverobot.cloud/v1/{api-url-ending}?parameter=value

      • A query parameter with an enum value
        "enum values" are predefined values that you can just copy and paste to the URL.

        https://api.Progressiverobot.cloud/v1/{api-url-ending}?parameter={enum-value}

      • Two or more query parameters
        The first parameter that is added to the URL begins with a question mark ?. Every other parameter that follows begins with an "and" sign &.

        https://api.Progressiverobot.cloud/v1/{api-url-ending}?parameter=value&parameter=value

      If you want to refine the results to a certain request, you can refer to "Query Parameters". This section gives you a list of any parameters that are available for a specific request.

8. 5. • Label selectors
        Resources can have simple labels that only consist of the key part, and they can have key  value  pairs ("key=value"). You can filter your resources by specifying either the "key" only, or both the "key" and the "value".
        https://api.Progressiverobot.cloud/v1/floating_ips?label_selector=env
        In this example, the request could return resources with labels such as env  production , env  testing , or with a simple env label. For more information, refer to the official documentation on label selectors.
        
        
      • Sort
        In the example image above, it says that you can sort your resources by ID or by their creation date. To sort the results by ID in an ascending ("asc") order, you can simply copy and paste the corresponding enum value.
        https://api.Progressiverobot.cloud/v1/floating_ips?sort=id:asc
        For more information, refer to the official documentation on sorting.
        
        
      • Two parameters in one request
        
        https://api.Progressiverobot.cloud/v1/floating_ips?label_selector=env&sort=id:asc

   
   

   6. Execute the curl command

      After you have copied and modified the curl command, make sure you have also added the correct API token. Then, execute the command using a command-line interface (CLI).

   After you executed the command, you will get a response that will let you know if the request was successful. Any changes you make via the API are also displayed in the Cloud Console.