Download OpenAPI specification:Download
The Contract Management API allows you to manage your gridscale contracts.
This API includes the following functions/areas:
To access this API, you need an valid X-Auth-Token
and your X-Auth-UserId
. As Partner, you get them in the API Keys
section in your Partner Panel. As a regular user, you can find them in your API Token
seciton in your panel and there you need to create an unlimited token.
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.
After you have successfully authenticated against the API, you still need the appropriate authorization for the various endpoints. Which authorizations you have depends on your user roles, with which you have created the API token. You can set different access rights for the contracts you have access to. The required scopes for a request can be found in the endpoint description.
You can have multiple of this scopes:
- PARTNER_READ
- PARTNER_WRITE
- PARTNER_ADMIN
- CONTRACT_READ
- CONTRACT_WRITE
- CONTRACT_ADMIN
- CONTRACT_OWNER
This API uses traditional HTTP response codes to indicate the success or failure of an API request. Therefore, the following applies: Codes in the 2xx range indicate successful processing of the request. Codes in the 4xx range indicate an error. Codes in the 5xx range indicate a very rare error at gridscale and are reported to gridscale fully automatically.
HTTP response codes in the 4xx range return a JSON response based on the RFC-7807 standard. The response can contain several individual problems that describe the error in more detail. For most of the errors, you can find more information if you follow the link in the type resource.
Example:
{
"errors": [
{
"type": "https:\/\/my.gridscale.io\/schema\/problem\/not-found",
"title": "Not Found",
"status": 404,
"detail": "The requested resource was not found. Read the API DOC https:\/\/https://api.gridscale.io/management\/management\/v1\/schema.json for more information.",
"instance": "\/management\/v1\/",
"data": [
]
}
]
}
Each API request contains a Correlate ID in the response. This ID can be found in the response headers under: x-correlate-id
. If you ever need to contact the gridscale support for a query, please include this x-correlate-id
if possible.
The Contract Management API is currently available in major version 1.1.0 You decide which version of the API you use via the API endpoint path.
When a new backwards incompatible version of the API appears, a new major version is provided. Once a new major version is released, an deprecation & sunset date is set for the previous version. They can be found in this document, as well as in the response headers of each request.
Minor API changes that are backwards compatible will be rolled out periodically. Detailed information can be found in the changelog. The currently used API version can be found in the X-Api-Version header.
Deprecation: unknown
Sunset: unknown
If you have access to a partner, then you will get all the relevant billing information displayed here.
One of the following Scopes is needed to access this endpoint:
X-Powered-By required | string Example: "Contract Management API" API Name |
X-Api-Version required | string Example: "1.1.0" API Version |
Content-Type required | string Example: "application/json" Content Type |
X-Correlate-Id required | string Example: "bca9bdf1-43fb-4d40-81d2-5e78a3ea766d" Correlation UUID |
Sunset | string Example: "Tue, 01 Nov 2000 12:45:26 GMT" Sunset date of this API version if known |
Deprecation | string Example: "Tue, 01 Nov 2000 12:45:26 GMT" Deprecation date of this API Version if known |
partner_uuid required | string <uuid> (UuidPartner) Unique UUID of the partner |
name required | string Name of the Partner Account |
billing_info required | string (BillingInfo) Postal address as it will be found on the next invoice. |
billing_email required | string <email> (BillingEmail) Commaseperated e-mail addresses, which will be sent the invoice. |
vat_id required | string (VatId) VAT ID, which is entered for the record. It will be found on the next invoice when billing is activated. |
required | object |
{- "partner_uuid": "fd24b847-6008-4ac3-a638-a89be42053d4",
- "name": "Partner name",
- "billing_info": "Company Gmbh Musterstrasse 111 12345 Musterstadt",
- "billing_email": "billing@company.com",
- "vat_id": "12/345/67890",
- "_links": {
- "linkPartnerContracts": "/management/v1/contracts",
- "linkPartnerPrices": "/management/v1/partner/prices",
- "linkPriceLists": "/management/v1/pricelists"
}
}
Get Partner Prices
One of the following Scopes is needed to access this endpoint:
X-Powered-By required | string Example: "Contract Management API" API Name |
X-Api-Version required | string Example: "1.1.0" API Version |
Content-Type required | string Example: "application/json" Content Type |
X-Correlate-Id required | string Example: "bca9bdf1-43fb-4d40-81d2-5e78a3ea766d" Correlation UUID |
Sunset | string Example: "Tue, 01 Nov 2000 12:45:26 GMT" Sunset date of this API version if known |
Deprecation | string Example: "Tue, 01 Nov 2000 12:45:26 GMT" Deprecation date of this API Version if known |
required | Array of objects (PriceListLocationListItem) |
{- "locations": [
- {
- "location_uuid": "16462e8d-6972-4420-9e4e-14d55f9ffee9",
- "name": "FRA1",
- "is_default_location": true,
- "is_virtual_location": false,
- "parent_location_uuid": null,
- "prices": [
- {
- "currency": "EUR",
- "name": "CPU Core",
- "price_per_unit": [
- 2.12,
- 0.0005
], - "product_number": [
- "123",
- "PPA100"
], - "type": "core",
- "unit": "per core, per minute"
}
]
}
]
}
Will return all your price lists
One of the following Scopes is needed to access this endpoint:
X-Powered-By required | string Example: "Contract Management API" API Name |
X-Api-Version required | string Example: "1.1.0" API Version |
Content-Type required | string Example: "application/json" Content Type |
X-Correlate-Id required | string Example: "bca9bdf1-43fb-4d40-81d2-5e78a3ea766d" Correlation UUID |
Sunset | string Example: "Tue, 01 Nov 2000 12:45:26 GMT" Sunset date of this API version if known |
Deprecation | string Example: "Tue, 01 Nov 2000 12:45:26 GMT" Deprecation date of this API Version if known |
price_list_uuid required | string <uuid> (UuidPriceList) Unique UUID of the price list |
name required | string (PriceListName) Name of the price list. It is visible in the panel for the users. |
is_default_price_list required | boolean (IsDefaultPriceList) The default price list is automatically assigned to new contracts. There can only be one default price list. If you set the flag for a price list, it will be removed from the previous one. You are not able to patch this field to "false". You need to set it to true to a different price list. |
contracts required | Array of strings <uuid> (Contracts) All contracts listed here are currently assigned to this price list. |
required | object |
[- {
- "price_list_uuid": "72d48c00-7473-4199-9f4f-e2af81f37dd8",
- "name": "default",
- "is_default_price_list": true,
- "contracts": [
- "cb9ff131-60b9-4f41-b3e1-01994dc2833e",
- "9dac34ef-1e15-41bb-9075-124ff9b0126d"
], - "_links": {
- "linkPriceListDetail": "/management/v1/pricelists/72d48c00-7473-4199-9f4f-e2af81f37dd8"
}
}
]
One of the following Scopes is needed to access this endpoint:
The payload for creating a new price list for a partner.
name required | string (PriceListName) Name of the price list. It is visible in the panel for the users. |
is_default_price_list | boolean (IsDefaultPriceList) The default price list is automatically assigned to new contracts. There can only be one default price list. If you set the flag for a price list, it will be removed from the previous one. You are not able to patch this field to "false". You need to set it to true to a different price list. |
contracts | Array of strings <uuid> (Contracts) All contracts listed here are currently assigned to this price list. |
X-Powered-By required | string Example: "Contract Management API" API Name |
X-Api-Version required | string Example: "1.1.0" API Version |
Content-Type required | string Example: "application/json" Content Type |
X-Correlate-Id required | string Example: "bca9bdf1-43fb-4d40-81d2-5e78a3ea766d" Correlation UUID |
Sunset | string Example: "Tue, 01 Nov 2000 12:45:26 GMT" |