Manage your resources with the Scaleway API, using simple HTTP requests.
The Scaleway API allows you to create and manage all your Scaleway resources programmatically.
Anything you can do through the Scaleway console can also be done through the API, from creating Instances to attaching them to Private Networks, to configuring Identity and Access Management, and more.
Curl examples are provided throughout our API documentation. However, calls to the Scaleway API can also be made via various other libraries, SDKs and devtools.
Quickstart: First request
Run the curl request below in your browser. Make sure you replace
<your-secret-key>with the secret part of your API key.curl -X GET \-H "X-Auth-Token: <your-secret-key>" \-H "ContentType: application/json" \"https://api.scaleway.com/instance/v1/zones/fr-par-1/servers"
The response will be a JSON list of your Instances in the
fr-par-1region, and their details.
See How to authenticate for information on generating API keys, and Endpoints for further details on how the HTTPS endpoint breaks down.
How to authenticate
Each request made to Scaleway API must be authenticated by sending an
X-Auth-Token HTTP header with each request. This header contains the secret key part of your Scaleway API key, which you can generate on the Scaleway console.
We recommend exporting your secret key as an environment variable, which you can then pass directly in your curl request as follows. Remember to replace the example value with your own API secret key.
curl -X GET \-H "X-Auth-Token: $SCW_SECRET_KEY" \-H "ContentType: application/json" \"https://api.scaleway.com/instance/v1/zones/fr-par-1/servers"
Identity and Access Management (IAM)
Scaleway API keys are subject to IAM permissions. An API key always inherits the IAM permissions of its bearer: the IAM user or IAM application with which the key is associated.
If the API key is associated with the Owner of a Scaleway Organization, it has full rights and permissions for actions within that Organization. Otherwise, it has the permissions defined for the bearer in the Organization via policies.
Requests and responses
Requests and responses to the Scaleway API are JSON-based.
An API request consists of a call to the Scaleway API, asking it to carry out an action or provide information.
Each API request will include a specified method, depending on the action you wish to perform:
|Used to get a resource from a server. The server looks for the data you have requested, and sends it back to you.||List your Instances: |
|Often used to create a resource, this method provides additional data such as a JSON payload sent from the client to the server in the message body.||Create an Instance: |
|Used to modify an existing resource||Update an Instance: |
|Used to delete a resource||Delete an Instance: |
Example request to list existing flexible IPs:
curl -X GET \-H "X-Auth-Token: $SCW_SECRET_KEY" \-H "ContentType: application/json" \"https://api.scaleway.com/instance/v1/zones/fr-par-1/ips"
After receiving a request, the API sends a response. This consists of the response body, headers and the HTTP status code. When a request is successful, the response body will typically be sent back in the form of a JSON object. An exception to this is when a
DELETE request is processed, which will result in an empty response body.
Example response to the curl above, listing existing flexible IPs:
HTTP status codes
The Scaleway API uses conventional HTTP response codes to indicate the success or failure of a request.
In general, codes in the
2xx range indicate success, codes in the
4xx range indicate an error that resulted from the provided information (e.g. a required parameter is missing), and codes in the `5xx range indicate an error with our servers.
|HTTP status code||Meaning||Suggested solution|
|Request was successful||N/A|
201 No Content
|Request was successful but the response does not contain a body||N/A|
400 Bad Response
|Request was unsuccessful||Often this means the request was missing a required parameter.|
|Request was unsuccessful due to an unvalid API Key||If using IAM check your API key’s permissions otherwise check the API.|
For most non-
2xx status codes, a message is provided in the response body giving more detail about the cause of the issue.
Every Scaleway API can be accessed through a single endpoint:
Endpoints generally conform to one of the following patterns:
Regions and zones
Each Scaleway API is either zoned (e.g. Instances, Elastic Metal, Public Gateways), regional (e.g. Kubernetes, Serverless Functions, Messaging and Queuing) or global (e.g. IAM, Billing).
For zoned and regional APIs, the target zone or region for the request is specified in the endpoint (see the codes in the table below). All requests are scoped to that particular zone or region, so for example a
List servers request will list servers in that zone or region only.
Scaleway products are hosted in our datacenters across the following regions and zones:
Versioning allows Scaleway to improve its APIs without breaking clients’ applications when new versions are rolled out.
Versions are managed in the URI path, for example
By default, the documentation for the current major version always displays on the main page for a given API, but alternative documented versions may also be available via the version dropdown at the top of the page.
Each product API contains methods for one or more objects. In the case of the Instance API, for example, objects include servers (Instances), images, volumes, security groups and snapshots. The object, combined with the request method e.g.
POST etc and (if applicable) other parameters sent in the request, determines the action to be carried out on the object.