pydo.images.list()

Generated on 25 November 2024 from pydo version v0.6.0

Description

To list all of the images available on your account, send a GET request to /v2/images.

Filtering Results

It’s possible to request filtered results by including certain query parameters.

Image Type

Either 1-Click Application or OS Distribution images can be filtered by using the type query parameter.

Important: The type query parameter does not directly relate to the type attribute.

To retrieve only distribution images, include the type query parameter set to distribution, /v2/images?type=distribution.

To retrieve only application images, include the type query parameter set to application, /v2/images?type=application.

User Images

To retrieve only the private images of a user, include the private query parameter set to true, /v2/images?private=true.

Tags

To list all images assigned to a specific tag, include the tag_name query parameter set to the name of the tag in your GET request. For example, /v2/images?tag_name=$TAG_NAME.

Parameters

Name Type Required Description Default Value
type string False Filters results based on image type which can be either application or distribution.
private boolean False Used to filter only user images.
tag_name string False Used to filter images by a specific tag.
per_page integer False Number of items returned per page 20
page integer False Which ‘page’ of paginated results to return. 1

Request Sample

import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

resp = client.images.list()

Responses

See the API spec for this endpoint to view additional detail on responses, headers, parameters, and more.

The response will be a JSON object with a key called images. This will be set to an array of image objects, each of which will contain the standard image attributes.

Click to expand an example response for All. 
{
  "value": {
    "images": [
      {
        "id": 7555620,
        "name": "Nifty New Snapshot",
        "distribution": "Ubuntu",
        "slug": null,
        "public": false,
        "regions": [
          "nyc2",
          "nyc3"
        ],
        "created_at": "2014-11-04T22:23:02Z",
        "type": "snapshot",
        "min_disk_size": 20,
        "size_gigabytes": 2.34,
        "description": "",
        "tags": [],
        "status": "available",
        "error_message": ""
      },
      {
        "id": 7555621,
        "name": "Another Snapshot",
        "distribution": "Ubuntu",
        "slug": null,
        "public": false,
        "regions": [
          "nyc2"
        ],
        "created_at": "2014-11-04T22:23:02Z",
        "type": "snapshot",
        "min_disk_size": 20,
        "size_gigabytes": 2.34,
        "description": "",
        "tags": [],
        "status": "available",
        "error_message": ""
      },
      {
        "id": 63663980,
        "name": "20.04 (LTS) x64",
        "distribution": "Ubuntu",
        "slug": "ubuntu-20-04-x64",
        "public": true,
        "regions": [
          "nyc2",
          "nyc3"
        ],
        "created_at": "2020-05-15T05:47:50Z",
        "type": "snapshot",
        "min_disk_size": 20,
        "size_gigabytes": 2.36,
        "description": "",
        "tags": [],
        "status": "available",
        "error_message": ""
      },
      {
        "id": 7555621,
        "name": "A custom image",
        "distribution": "Arch Linux",
        "slug": null,
        "public": false,
        "regions": [
          "nyc3"
        ],
        "created_at": "2014-11-04T22:23:02Z",
        "type": "custom",
        "min_disk_size": 20,
        "size_gigabytes": 2.34,
        "description": "",
        "tags": [],
        "status": "available",
        "error_message": ""
      },
      {
        "id": 7555621,
        "name": "An APP image",
        "distribution": "Fedora",
        "slug": null,
        "public": false,
        "regions": [
          "nyc2",
          "nyc3"
        ],
        "created_at": "2014-11-04T22:23:02Z",
        "type": "snapshot",
        "min_disk_size": 20,
        "size_gigabytes": 2.34,
        "description": "",
        "tags": [],
        "status": "available",
        "error_message": ""
      },
      {
        "id": 7555621,
        "name": "A simple tagged image",
        "distribution": "CentOS",
        "slug": null,
        "public": false,
        "regions": [
          "nyc2",
          "nyc3"
        ],
        "created_at": "2014-11-04T22:23:02Z",
        "type": "snapshot",
        "min_disk_size": 20,
        "size_gigabytes": 2.34,
        "description": "",
        "tags": [
          "simple-image"
        ],
        "status": "available",
        "error_message": ""
      }
    ],
    "links": {
      "pages": {}
    },
    "meta": {
      "total": 6
    }
  }
}
Click to expand an example response for Snapshots. 
{
  "value": {
    "images": [
      {
        "id": 7555620,
        "name": "Nifty New Snapshot",
        "distribution": "Ubuntu",
        "slug": null,
        "public": false,
        "regions": [
          "nyc2",
          "nyc3"
        ],
        "created_at": "2014-11-04T22:23:02Z",
        "type": "snapshot",
        "min_disk_size": 20,
        "size_gigabytes": 2.34,
        "description": "",
        "tags": [],
        "status": "available",
        "error_message": ""
      },
      {
        "id": 7555621,
        "name": "Another Snapshot",
        "distribution": "Ubuntu",
        "slug": null,
        "public": false,
        "regions": [
          "nyc2"
        ],
        "created_at": "2014-11-04T22:23:02Z",
        "type": "snapshot",
        "min_disk_size": 20,
        "size_gigabytes": 2.34,
        "description": "",
        "tags": [],
        "status": "available",
        "error_message": ""
      }
    ],
    "links": {
      "pages": {}
    },
    "meta": {
      "total": 2
    }
  }
}
Click to expand an example response for Distribution. 
{
  "description": "**Important:**  \nThe `type` query parameter is not directly related to the `type` attribute.\nThe main thing to remember here is that DigitalOcean-produced distribution images will have `snapshot` as the type attribute. \n",
  "value": {
    "images": [
      {
        "id": 63663980,
        "name": "20.04 (LTS) x64",
        "distribution": "Ubuntu",
        "slug": "ubuntu-20-04-x64",
        "public": true,
        "regions": [
          "nyc2",
          "nyc3"
        ],
        "created_at": "2020-05-15T05:47:50Z",
        "type": "snapshot",
        "min_disk_size": 20,
        "size_gigabytes": 2.36,
        "description": "",
        "tags": [],
        "status": "available",
        "error_message": ""
      }
    ],
    "links": {
      "pages": {}
    },
    "meta": {
      "total": 1
    }
  }
}
Click to expand an example response for Custom. 
{
  "value": {
    "images": [
      {
        "id": 7555621,
        "name": "A custom image",
        "distribution": "Arch Linux",
        "slug": null,
        "public": false,
        "regions": [
          "nyc3"
        ],
        "created_at": "2014-11-04T22:23:02Z",
        "type": "custom",
        "min_disk_size": 20,
        "size_gigabytes": 2.34,
        "description": "",
        "tags": [],
        "status": "available",
        "error_message": ""
      }
    ],
    "links": {
      "pages": {}
    },
    "meta": {
      "total": 1
    }
  }
}
Click to expand an example response for Application. 
{
  "description": "**Important:**  \nThe `type` query parameter is not directly related to the `type` attribute.\n",
  "value": {
    "images": [
      {
        "id": 7555621,
        "name": "An APP image",
        "distribution": "Fedora",
        "slug": null,
        "public": false,
        "regions": [
          "nyc2",
          "nyc3"
        ],
        "created_at": "2014-11-04T22:23:02Z",
        "type": "snapshot",
        "min_disk_size": 20,
        "size_gigabytes": 2.34,
        "description": "",
        "tags": [],
        "status": "available",
        "error_message": ""
      }
    ],
    "links": {
      "pages": {}
    },
    "meta": {
      "total": 1
    }
  }
}
Click to expand an example response for Tagged. 
{
  "value": {
    "images": [
      {
        "id": 7555621,
        "name": "A simple tagged image",
        "distribution": "CentOS",
        "slug": null,
        "public": false,
        "regions": [
          "nyc2",
          "nyc3"
        ],
        "created_at": "2014-11-04T22:23:02Z",
        "type": "snapshot",
        "min_disk_size": 20,
        "size_gigabytes": 2.34,
        "description": "",
        "tags": [
          "simple-image"
        ],
        "status": "available",
        "error_message": ""
      }
    ],
    "links": {
      "pages": {}
    },
    "meta": {
      "total": 1
    }
  }
}

Unauthorized

Click to expand an example response. 
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

API Rate limit exceeded

Click to expand an example response. 
{
  "id": "too_many_requests",
  "message": "API Rate limit exceeded."
}

Server error.

Click to expand an example response. 
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

Unexpected error

Click to expand an example response. 
{
  "id": "example_error",
  "message": "some error message"
}
Control Panel Blog Pricing Careers Terms Privacy Status API Docs Tutorials Support