APIv4 Reference

Clever Cloud provides a public REST API used by its own services and customers, known as /v2. As our platform evolves, we’re progressively moving to /v4 endpoints, adding functionalities, with a more modern approach:

https://api.clever-cloud.com/v4/

While the documentation moves towards completion, this page presents the most useful endpoints and example requests available now.

Billing

• /v4/billing/organisations/{orgid}/invoices
• /v4/billing/organisations/{orgid}/invoices/{invoiceid}
• /v4/billing/organisations/{orgid}/invoices/{invoiceid}.html
• /v4/billing/organisations/{orgid}/invoices/{invoiceid}.pdf
• Type: GET

You can use optional parameters to filter it:

Example response, for each invoice:

[
    {
    "invoice_number": "",
    "kind": "",
    "owner_id": "",
    "address": {
      "address_id": "",
      "owner_id": "",
      "name": "",
      "company": "",
      "address": "",
      "city": "",
      "zipcode": "",
      "country_alpha2": "",
      "vat_number": "",
      "vat_percent": float,
      "customer_cost_center": "",
      "customer_purchase_order": ""
    },
    "emission_date": "",
    "pay_date": "",
    "status": "",
    "currency": "",
    "price_factor": float,
    "discount": float,
    "vat_percent": float,
    "total_tax_excluded": {
      "currency": "",
      "amount": float,
      "amount_formatted": "",
      "default_display": ""
    },
    "total_tax": {
      "currency": "",
      "amount": float,
      "amount_formatted": "",
      "default_display": ""
    },
    "category": "",
    "payment_provider": "",
    "transaction_id": "",
    "customer_order_id": ""
  },
  {...}
]

Deployments

• /v4/orchestration/organisations/{ownerId}/applications/{applicationId}/deployments
• /v4/orchestration/organisations/{ownerId}/applications/{applicationId}/deployments/{deploymentId}
• Type: GET

Example response, for each deployment:

[
  {
    "id": "",
    "ownerId": "",
    "applicationId": "",
    "startDate": "",
    "state": "",
    "steps": [
      {
        "state": "",
        "date": ""
      },
      {
        "state": "",
        "date": ""
      },
      {
        "state": "",
        "date": ""
      }
    ],
    "version": {
      "commitId": ""
    },
    "origin": {
      "action": "",
      "cause": "",
      "source": "",
      "authorId": "",
      "constraints": [
        ""
      ],
      "priority": ""
    },
    "hasDedicatedBuild": boolean
  },
  {...}
]

Instances

• /v4/orchestration/organisations/{ownerId}/applications/{applicationId}/instances
• Type: GET

You can use optional parameters to filter it:

Example response, for each instance:

[
  {
    "id": "",
    "ownerId": "",
    "applicationId": "",
    "deploymentId": "",
    "name": "",
    "flavor": "",
    "index": int,
    "state": "",
    "creationDate": "",
    "deletionDate": "",
    "network": {
      "ip": "",
      "port": int
    },
    "isBuildVm": boolean
  },
  {...}
]

Load Balancers

• /v4/load-balancers/organisations/{ownerId}/applications/{applicationId}/load-balancers/default
• Type: GET

Example response:

[
  {
    "id": "",
    "name": "",
    "zoneId": "",
    "dns": {
      "cname": "",
      "a": []
    }
  }
]

Logs

• /v4/logs/organisations/{ownerId}/applications/{applicationId}/logs
• Type: GET

Answers with logs in a SSE (Server-Sent Events) stream. You can use optional parameters to filter it:

Operators

A Clever Cloud Operator deploys and manage resources for a given service. Available operators are: keycloak, matomo, metabase, otoroshi.

• /v4/addon-providers/addon-{operator_name}/addons/{operator_id}
• Type: GET

Example response:

{
  "resourceId": "real_id",
  "addonId": "addon_id",
  "name": "resource_name",
  "ownerId": "user_or_org_id",
  "plan": "PLAN_NAME",
  "version": "x.y.z",
  "javaVersion": "X", # Optional
  "phpVersion": "X",  # Optional
  "accessUrl": "https://service-web-ui-id.services.clever-cloud.com",
  "api": { # Optional
    "url": "https://service-api-id.services.clever-cloud.com",
    ...
  },
  "availableVersions": [
    "x.y.z",
    ...
  ],
  "resources": {
    "entrypoint": "app_id",
    ...
  },
  "features": {
    ...
  },
  "envVars": {
    "VAR_NAME": "value",
    ...
  }
}

• /v4/addon-providers/addon-{operator_name}/addons/{operator_id}/reboot
• /v4/addon-providers/addon-{operator_name}/addons/{operator_id}/rebuild
• Type: POST
• Response code: 204

Network groups

You can add the deployed service main application in a Network Group to activate some enhanced features:

• keycloak: two instances are deployed and synced through a Network Group

• otoroshi: once in a Network Group, an Otoroshi instance can be used in front of Clever Cloud applications

• /v4/addon-providers/addon-{operator_name}/addons/{operator_id}/ng

• Type: POST

• Response code: 202

Response contains the full operator object with ng feature enabled:

features: {
  "ng": "ng_id",
}

• /v4/addon-providers/addon-{operator_name}/addons/{operator_id}/ng
• Type: DELETE
• Response code: 204 If no Network Group is found, the ng feature value is null:

features: {
  "ng": null,
}

Products zones

• /v4/products/zones
• /v4/products/zones/{name}
• Type: GET

Example response, for each zone:

[
  {
    "id": "",
    "name": "",
    "country": "",
    "countryCode": "",
    "city": "",
    "displayName": "",
    "lat": float,
    "lon": float,
    "outboundIPs": [],
    "tags": []
  },
  {...}
]

Pulsar policies

• /v4/addon-providers/addon-pulsar/addons/{addon-id}/storage-policies
• Type: GET/PATCH

Define or get offload/retention policies of a Pulsar add-on. Retention is how long messages are kept in the topic. Offload is how long messages are kept in the hot storage (NVMe SSD) before being moved to Cellar object storage (S3 compatible, HDD).

Example query/response:

{
  "retentionPolicies": {
    "sizeInMB": number,
    "durationInDays": number
  },
  "offloadPolicies": {
    "durationInDays": number,
    "sizeInMB": number
  }
}

A null value means an infinite retention or no offload.