Developer API

API Documentation

All your Scaleway resources

The Scaleway API allows you to create and manage all your Scaleway resources programmatically.

Anything you can do through the Scaleway consoleOpen in new context 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.

Terraform

View Github

Scaleway CLI

View Github

Documentation for achieving specific use cases via each product's API can be found on our main website, in the API/CLI section for your product of choice.

Make your first request

Generate your API keyOpen in new context.
Run the curl request below in your terminal. Make sure you replace <your-secret-key> with the secret part of your API key.
```
Code
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-1 region, 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 consoleOpen in new context.

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.

Code
export SCW_SECRET_KEY=720438f9-fcb9-4ebb-80a7-808ebf15314b

Curl request:

Code
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 IAMOpen in new context permissions. An API key always inherits the IAM permissions of its bearer: the IAM userOpen in new context or IAM applicationOpen in new context 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 policiesOpen in new context.

Requests and responses

Requests and responses to the Scaleway API are JSON-based.

Requests

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:

Request method	Usage	Example
`GET`	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: `GET /instance/v1/zones/{zone}/servers`
`POST`	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: `POST instance/v1/zones/{zone}/servers`
`PATCH`	Used to modify an existing resource	Update an Instance: `PATCH instance/v1/zones/{zone}/servers/{server_id}`
`DELETE`	Used to delete a resource	Delete an Instance: `DELETE /instance/v1/zones/{zone}/servers/{server_id}`

Example request to list existing flexible IPs:

Code
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"

Responses

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:

Code
{
   "ips":[
      {
         "id":"b483671d-677f-435f-9de9-9a1adee70f25",
         "address":"50.17.253.160",
         "reverse":null,
         "server":{
            "id":"f9c1998a-9af8-4e2f-b6b7-9b9030daaa71",
            "name":"my-instance"
         },
         "organization":"8e3b57b8-eee9-4de1-975e-522c48c0dac0",
         "project":"a6cdba1f-2ee2-4a04-a5af-2d457b194ee3",
         "zone":"fr-par-1",
         "tags":[
         ]
      }
   ]
}

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
200 OK	Request was successful	N/A
201 Resource Created	Resource was successfully created	N/A
400 Bad Response	Request was unsuccessful	Often this means the request was missing a required parameter.
401 Unauthorized	Request was unsuccessful due to an unvalid API Key	If using IAM check your API key’s permissionsOpen in new context 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.

Endpoints

Every Scaleway API can be accessed through a single endpoint: api.scaleway.com.

Endpoints generally conform to one of the following patterns:

Zoned: api.scaleway.com/{product}/{version}/zones/{zone}/{object}..., e.g. api.scaleway.com/instance/v1/zones/{zone}/servers
Regional: api.scaleway.com/{product}/{version}/regions/{region}/{object}..., e.g. api.scaleway/com/k8s/v1/regions/fr-par/clusters
Global: api.scaleway.com/{product}/{version}/{object}... e.g. api.scaleway.com/iam/v1alpha1/users.

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:

Region	Zone	Description
`fr-par`	`fr-par-1`, `fr-par-2`, `fr-par-3`	France Paris
`nl-ams`	`nl-ams-1`, `nl-ams-2`, `nl-ams-3`	Netherlands Amsterdam
`pl-waw`	`pl-waw-1`, `pl-waw-2`, `pl-waw-3`	Poland Warsaw

Versions

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 api.scaleway.com/iam/v1alpha1/.

By default, the documentation for the current major version always displays on the main page for a given API, but alternative available versions may also be available via the version dropdown at the top of the page.

Versions do not reflect product stability, but rather the stability of the interface. API versions can be categorized into three main release tracks:

Example	Track
`v1`	General Availability. Stable.
`v1beta1`	Beta. Pre-GA.
`v1alpha1`	Alpha. Experimental.

When a new version is released, the older version remains available for a period of time to allow users time to move to it. Developer tools (CLI, Terraform, SDKS etc.) are updated to use the newer version. Remaining clients using the old version are notified and warned to move, before the old version is removed and can no longer receive requests.

Objects

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. GET, DELETE, POST etc and (if applicable) other parameters sent in the request, determines the action to be carried out on the object.

Scaleway Resource Names

A Scaleway Resource Name (SRN) is a Uniform Resource Identifier (URI) that uniquely identifies a Scaleway resource. It follows the format below:

Code
srn://product-slug.partition/locality-type/{locality}/resource-type/{resource-id}

Examples:

Code
# Key Manager key - an example with locality
srn://key-manager.scw.eu/regions/fr-par/keys/25f6c309-a2c6-4fb2-8d16-57960c3fb9df

# IAM application - an example with no locality
srn://iam.scw.eu/applications/25f6c309-a2c6-4fb2-8d16-57960c3fb9df

The following table explains how to compose an SRN:

SRN segment	Details
srn://	Specifies that the string that follows is a Scaleway Resource Name (SRN).
product-slug	An identifier for the product. Examples: `block` for Block Storage, `secret-manager` for Secret Manager
partition	The identifier of the Scaleway partition represented as a domain. Possible values (exhaustive list): `scw.eu`
locality-type	The locality type. Possible values (exhaustive list): `regions`, `zones`
locality	The Scaleway region code or zone code. Resources with locality will include the locality in a parent segment. Resources without locality have no locality-type nor locality segment. Examples for region: `fr-par`, `nl-ams`, `pl-waw`, `it-mil` Examples for zone: `fr-par-1`, `nl-ams-2`, `pl-waw-3`, `it-mil-1`
resource-type	The resource type in its plural form, similar to a REST segment for a resource. Examples: `routes` for VPC routes, `volumes` for Block volumes
resource-id	The unique identifier of the resource. You can retrieve this information from the resource's page in the Scaleway console or via the product's API.

For a complete list of SRNs, see Resource types and their SRNs.

For a complete list of product-slugs, see Product slugs.

Note that Object Storage resources are special:

The bucket and object resource IDs are user-set and unique by partition.
The object resource ID is a path inside the bucket.

As a result, the path will be split in two segments: the bucket and the object.

Code
srn://object.scw.eu/buckets/bucket-name
srn://object.scw.eu/buckets/bucket-name/objects/path/to/my/object

Note that some nested resources rely on a parent UUID and a user-set ID in order to be addressed (e.g., a secret version). In this scenario, the nearest parent with a UUID will be included in the SRN.

Example:

Code
srn://secret-manager.scw.eu/regions/fr-par/secrets/25f6c309-a2c6-4fb2-8d16-57960c3fb9df/versions/5

Resource types and their SRNs

Some products, such as Annotations, require you to provide an SRN when executing certain operations via the API.

The following table provides a list of resource types and corresponding Scaleway Resource Names.

The list is intended to be comprehensive; however, it is still a work in progress. It is updated continuously with new items.

To use an SRN, replace the ALL-CAPS segments with your resource-specific information.

Resource type	SRN
BlockSnapshot	`srn://block.scw.eu/zones/ZONE/snapshots/RESOURCE-ID`
BlockVolume	`srn://block.scw.eu/zones/ZONE/volumes/RESOURCE-ID`
BlockVolumeType	`srn://block.scw.eu/zones/ZONE/volume-types/TYPE`
DatawarehouseDatabase	`srn://datawarehouse.scw.eu/regions/REGION/deployments/DEPLOYMENT-ID/databases/NAME`
DatawarehouseDeployment	`srn://datawarehouse.scw.eu/regions/REGION/deployments/ID`
DatawarehouseEndpoint	`srn://datawarehouse.scw.eu/regions/REGION/endpoints/ID`
DatawarehouseUser	`srn://datawarehouse.scw.eu/regions/REGION/deployments/DEPLOYMENT-ID/users/NAME`
FileAttachment	`srn://file.scw.eu/regions/REGION/attachments/RESOURCE-ID`
FileFileSystem	`srn://file.scw.eu/regions/REGION/file-systems/RESOURCE-ID`
FlexibleIpFlexibleIp	`srn://flexible-ip.scw.eu/zones/ZONE/flexible-ips/ID`
IamApplication	`srn://iam.scw.eu/applications/RESOURCE-ID`
IamApiKey	`srn://iam.scw.eu/api-keys/ACCESS-KEY`
IamGroup	`srn://iam.scw.eu/groups/ID`
IamJwt	`srn://iam.scw.eu/jwts/JTI`
IamLog	`srn://iam.scw.eu/logs/ID`
IamPolicy	`srn://iam.scw.eu/policies/ID`
IamQuotum	`srn://iam.scw.eu/quota/NAME`
IamRule	`srn://iam.scw.eu/rules/ID`
IamSaml	`srn://iam.scw.eu/saml/ID`
IamSamlCertificate	`srn://iam.scw.eu/saml-certificates/ID`
IamSshKey	`srn://iam.scw.eu/ssh-keys/ID`
IamUser	`srn://iam.scw.eu/users/ID`
InstancePlacementGroup	`srn://instance.scw.eu/zones/ZONE/placement-groups/ID`
InstancePrivateNetworkInterface	`srn://instance.scw.eu/zones/ZONE/private-network-interfaces/ID`
InstanceSecurityGroup	`srn://instance.scw.eu/zones/ZONE/security-groups/ID`
InstanceSnapshot	`srn://instance.scw.eu/zones/ZONE/snapshots/ID`
InstanceTemplate	`srn://instance.scw.eu/zones/ZONE/templates/ID`
InstanceVolume	`srn://instance.scw.eu/zones/ZONE/volumes/ID`
InstanceServer	`srn://instance.scw.eu/zones/ZONE/servers/ID`
InterlinkDedicatedConnection	`srn://interlink.scw.eu/regions/REGION/dedicated-connections/ID`
InterlinkLink	`srn://interlink.scw.eu/regions/REGION/links/ID`
InterlinkPartner	`srn://interlink.scw.eu/regions/REGION/partners/ID`
InterlinkPop	`srn://interlink.scw.eu/regions/REGION/pops/ID`
InterlinkRoutingPolicy	`srn://interlink.scw.eu/regions/REGION/routing-policies/ID`
ipamIpPattern	`srn://ipam.scw.eu/regions/REGION/ips/ID`
ipamIpPattern	`srn://ipam.scw.eu/zones/ZONE/ips/ID`
K8SAclRule	`srn://k8s.scw.eu/regions/REGION/acl-rules/ID`
K8SCluster	`srn://k8s.scw.eu/regions/REGION/clusters/ID`
K8SClusterType	`srn://k8s.scw.eu/regions/REGION/cluster-types/NAME`
K8SNode	`srn://k8s.scw.eu/regions/REGION/nodes/ID`
K8SPool	`srn://k8s.scw.eu/regions/REGION/pools/ID`
K8SVersion	`srn://k8s.scw.eu/regions/REGION/versions/NAME`
KeyManagerKey	`srn://key-manager.scw.eu/regions/REGION/keys/RESOURCE-ID`
PublicGatewayGateway	`srn://public-gateway.scw.eu/zones/ZONE/gateways/ID`
PublicGatewayGatewayNetwork	`srn://public-gateway.scw.eu/zones/ZONE/gateway-networks/ID`
PublicGatewayIp	`srn://public-gateway.scw.eu/zones/ZONE/ips/ID`
PublicGatewayPatRule	`srn://public-gateway.scw.eu/zones/ZONE/pat-rules/ID`
S2SVpnConnection	`srn://s2s-vpn.scw.eu/regions/REGION/connections/ID`
S2SVpnCustomerGateway	`srn://s2s-vpn.scw.eu/regions/REGION/customer-gateways/ID`
S2SVpnRoutingPolicy	`srn://s2s-vpn.scw.eu/regions/REGION/routing-policies/ID`
S2SVpnVpnGateway	`srn://s2s-vpn.scw.eu/zones/ZONE/vpn-gateways/ID`
SecretManagerSecret	`srn://secret-manager.scw.eu/regions/REGION/secrets/RESOURCE-ID`
SecretManagerSecretVersion	`srn://secret-manager.scw.eu/regions/REGION/secrets/SECRET-ID/versions/REVISION`
ServerlessDbBackup	`srn://serverless-db.scw.eu/regions/REGION/backups/ID`
ServerlessDbDatabase	`srn://serverless-db.scw.eu/regions/REGION/databases/ID`
ServerlessDbVersion	`srn://serverless-db.scw.eu/regions/REGION/versions/NAME`
VpcIngressRule	`srn://vpc.scw.eu/regions/REGION/ingress-rules/RESOURCE-ID`
VpcPrivateNetwork	`srn://vpc.scw.eu/regions/REGION/private-networks/RESOURCE-ID`
VpcRoute	`srn://vpc.scw.eu/regions/REGION/routes/RESOURCE-ID`
VpcSubnet	`srn://vpc.scw.eu/regions/REGION/subnets/RESOURCE-ID`
VpcVPC	`srn://vpc.scw.eu/regions/REGION/vpcs/RESOURCE-ID`
VpcVPCConnector	`srn://vpc.scw.eu/regions/REGION/vpc-connectors/RESOURCE-ID`

Product slugs

The following table provides a list of products and corresponding product-slugs.