Charms

Endpoints related to charms and bundles.

charm_info

Introduced in version 22

Summary: GET /v2/charms/info/<name>

Given a name, return the details of the corresponding charm or bundle, and its released revisions.

Supports the following optional query params:

  • fields: A comma separated list of field names to include in the response. Optional. The following are always returned: type, id, name. Possible field names are in the successful response description below.

Responses are a JSON encoded dict. A successful response represents a single charm or bundle, and contains:

{
    "type": "charm" or "bundle".
    "id": str # 32 character identifier
    "name": str # The unique name of the charm or bundle.
    "result": {...} # Charm or bundle fields. Optional.
    "channel-map": [ # Array of all channels & revisions on them. Optional.
        {
            "channel": {...} # Optional.
            "revision": {...} # Optional.
        },
        ...
    ],
    "default-release": { # Optional.
        "channel": {...} # Most stable risk on default track. Optional.
        "revision": {...} # Last revision on that channel. Optional.
    }
}

Optional fields are only included if requested using the 'fields' param. See 'description' fields in the schema for details of each field.

Alternatively, an unsuccessful (non 2xx) response contains:

{
    "error-list": [
        {
            "code": str # String slug to identify the error type.
            "message": str # Human readble error message.
        },
        ...
    ]
}

charm_info changelog

  • Version 30: Added resource fields 'filename' and 'description'

  • Version 29: Added 'bundle-yaml' field to revision.

  • Version 28: Added 'resources' field to channelmap.

  • Version 27: Added "actions-yaml" to revision fields.

  • Version 22: Endpoint created.

Response JSON Schema

{
    "additionalProperties": false,
    "description": "The id and name of the requested charm or bundle, along with optional components: Its fields, all its releases in the form of a channel-map, and its most stable channel, along with the most recent revision on that channel.",
    "properties": {
        "channel-map": {
            "description": "All of this entity's releases, in the form of an array of channels and the revisions released on them.",
            "items": {
                "additionalProperties": false,
                "properties": {
                    "channel": {
                        "additionalProperties": false,
                        "description": "A channel used for releases, along with a revision released on that channel.",
                        "properties": {
                            "name": {
                                "description": "This channel's full name, as track/risk. eg \"latest/stable\".",
                                "type": "string"
                            },
                            "platform": {
                                "additionalProperties": false,
                                "description": "This channel's supported platform.",
                                "properties": {
                                    "architecture": {
                                        "description": "eg. \"amd64\", or \"all\".",
                                        "type": "string"
                                    },
                                    "os": {
                                        "description": "An operating system, eg. \"ubuntu\", \"windows\", \"centos\". We also consider \"kubernetes\" to be an OS. Or \"all\".",
                                        "type": "string"
                                    },
                                    "series": {
                                        "description": "A release of the operating system.  eg. \"xenial\" for Ubuntu, \"10\" for Windows, \"7\" for CentOS.Or \"all\".",
                                        "type": "string"
                                    }
                                },
                                "type": "object"
                            },
                            "released-at": {
                                "description": "The timestamp of the last release to this channel.",
                                "type": [
                                    "string",
                                    "null"
                                ]
                            },
                            "risk": {
                                "description": "This channel's risk, eg \"stable\", \"candidate\", \"beta\", \"edge\".",
                                "type": "string"
                            },
                            "track": {
                                "description": "This channel's track. eg. \"latest\".",
                                "type": "string"
                            }
                        },
                        "type": "object"
                    },
                    "resources": {
                        "introduced_at": 28,
                        "items": {
                            "additionalProperties": false,
                            "properties": {
                                "description": {
                                    "introduced_at": 30,
                                    "type": "string"
                                },
                                "download": {
                                    "additionalProperties": false,
                                    "properties": {
                                        "hash-sha256": {
                                            "type": "string"
                                        },
                                        "hash-sha3-384": {
                                            "type": "string"
                                        },
                                        "hash-sha384": {
                                            "type": "string"
                                        },
                                        "hash-sha512": {
                                            "type": "string"
                                        },
                                        "size": {
                                            "type": "number"
                                        },
                                        "url": {
                                            "type": "string"
                                        }
                                    },
                                    "type": "object"
                                },
                                "filename": {
                                    "introduced_at": 30,
                                    "type": "string"
                                },
                                "name": {
                                    "type": "string"
                                },
                                "revision": {
                                    "type": "number"
                                },
                                "type": {
                                    "type": "string"
                                }
                            },
                            "type": "object"
                        },
                        "type": "array"
                    },
                    "revision": {
                        "additionalProperties": false,
                        "description": "",
                        "properties": {
                            "actions-yaml": {
                                "description": "The content of this revision's actions.yaml file.",
                                "introduced_at": 27,
                                "type": "string"
                            },
                            "bundle-yaml": {
                                "description": "The content of this revision's bundle.yaml file.",
                                "introduced_at": 29,
                                "type": "string"
                            },
                            "config-yaml": {
                                "description": "The content of this revision's config.yaml file.",
                                "type": "string"
                            },
                            "created-at": {
                                "description": "The timestamp of this revision's creation.",
                                "type": "string"
                            },
                            "download": {
                                "additionalProperties": false,
                                "description": "The revision's download information.",
                                "properties": {
                                    "hash-sha-256": {
                                        "description": "The download's hash.",
                                        "type": [
                                            "string",
                                            "null"
                                        ]
                                    },
                                    "size": {
                                        "description": "The download's size in bytes.",
                                        "type": "number"
                                    },
                                    "url": {
                                        "description": "The download's url.",
                                        "type": "string"
                                    }
                                },
                                "type": "object"
                            },
                            "metadata-yaml": {
                                "description": "The content of this revision's metadata.yaml file.",
                                "type": "string"
                            },
                            "platforms": {
                                "description": "The revision's supported platforms.",
                                "items": {
                                    "additionalProperties": false,
                                    "properties": {
                                        "architecture": {
                                            "description": "eg. \"amd64\", or \"all\".",
                                            "type": "string"
                                        },
                                        "os": {
                                            "description": "An operating system, eg. \"ubuntu\", \"windows\", \"centos\". We also consider \"kubernetes\" to be an OS. Or \"all\".",
                                            "type": "string"
                                        },
                                        "series": {
                                            "description": "A release of the operating system.  eg. \"xenial\" for Ubuntu, \"10\" for Windows, \"7\" for CentOS.Or \"all\".",
                                            "type": "string"
                                        }
                                    },
                                    "type": "object"
                                },
                                "type": "array"
                            },
                            "readme-md": {
                                "description": "The content of this revision's README.md file.",
                                "type": "string"
                            },
                            "revision": {
                                "description": "The integer revision number.",
                                "type": "number"
                            },
                            "version": {
                                "description": "This revision's version string.",
                                "type": "string"
                            }
                        },
                        "type": "object"
                    }
                },
                "type": "object"
            },
            "type": "array"
        },
        "default-release": {
            "additionalProperties": false,
            "description": "A duplicate of the single channel-map entry representing the default channel & the last revision released on it. Default channel is defined as the most stable risk (eg. \"stable\") on the default track (falling back to \"latest\"). This is the channel used for deploys if clients express no overriding preferences. This allows clients to request representative info, such as when the last release was made, or how big the download will be, without having to request all the numerous entries in the full channel-map, or duplicate the server's logic for choosing the default channel.",
            "properties": {
                "channel": {
                    "additionalProperties": false,
                    "description": "A channel used for releases, along with a revision released on that channel.",
                    "properties": {
                        "name": {
                            "description": "This channel's full name, as track/risk. eg \"latest/stable\".",
                            "type": "string"
                        },
                        "platform": {
                            "additionalProperties": false,
                            "description": "This channel's supported platform.",
                            "properties": {
                                "architecture": {
                                    "description": "eg. \"amd64\", or \"all\".",
                                    "type": "string"
                                },
                                "os": {
                                    "description": "An operating system, eg. \"ubuntu\", \"windows\", \"centos\". We also consider \"kubernetes\" to be an OS. Or \"all\".",
                                    "type": "string"
                                },
                                "series": {
                                    "description": "A release of the operating system.  eg. \"xenial\" for Ubuntu, \"10\" for Windows, \"7\" for CentOS.Or \"all\".",
                                    "type": "string"
                                }
                            },
                            "type": "object"
                        },
                        "released-at": {
                            "description": "The timestamp of the last release to this channel.",
                            "type": [
                                "string",
                                "null"
                            ]
                        },
                        "risk": {
                            "description": "This channel's risk, eg \"stable\", \"candidate\", \"beta\", \"edge\".",
                            "type": "string"
                        },
                        "track": {
                            "description": "This channel's track. eg. \"latest\".",
                            "type": "string"
                        }
                    },
                    "type": "object"
                },
                "resources": {
                    "introduced_at": 28,
                    "items": {
                        "additionalProperties": false,
                        "properties": {
                            "description": {
                                "introduced_at": 30,
                                "type": "string"
                            },
                            "download": {
                                "additionalProperties": false,
                                "properties": {
                                    "hash-sha256": {
                                        "type": "string"
                                    },
                                    "hash-sha3-384": {
                                        "type": "string"
                                    },
                                    "hash-sha384": {
                                        "type": "string"
                                    },
                                    "hash-sha512": {
                                        "type": "string"
                                    },
                                    "size": {
                                        "type": "number"
                                    },
                                    "url": {
                                        "type": "string"
                                    }
                                },
                                "type": "object"
                            },
                            "filename": {
                                "introduced_at": 30,
                                "type": "string"
                            },
                            "name": {
                                "type": "string"
                            },
                            "revision": {
                                "type": "number"
                            },
                            "type": {
                                "type": "string"
                            }
                        },
                        "type": "object"
                    },
                    "type": "array"
                },
                "revision": {
                    "additionalProperties": false,
                    "description": "",
                    "properties": {
                        "actions-yaml": {
                            "description": "The content of this revision's actions.yaml file.",
                            "introduced_at": 27,
                            "type": "string"
                        },
                        "bundle-yaml": {
                            "description": "The content of this revision's bundle.yaml file.",
                            "introduced_at": 29,
                            "type": "string"
                        },
                        "config-yaml": {
                            "description": "The content of this revision's config.yaml file.",
                            "type": "string"
                        },
                        "created-at": {
                            "description": "The timestamp of this revision's creation.",
                            "type": "string"
                        },
                        "download": {
                            "additionalProperties": false,
                            "description": "The revision's download information.",
                            "properties": {
                                "hash-sha-256": {
                                    "description": "The download's hash.",
                                    "type": [
                                        "string",
                                        "null"
                                    ]
                                },
                                "size": {
                                    "description": "The download's size in bytes.",
                                    "type": "number"
                                },
                                "url": {
                                    "description": "The download's url.",
                                    "type": "string"
                                }
                            },
                            "type": "object"
                        },
                        "metadata-yaml": {
                            "description": "The content of this revision's metadata.yaml file.",
                            "type": "string"
                        },
                        "platforms": {
                            "description": "The revision's supported platforms.",
                            "items": {
                                "additionalProperties": false,
                                "properties": {
                                    "architecture": {
                                        "description": "eg. \"amd64\", or \"all\".",
                                        "type": "string"
                                    },
                                    "os": {
                                        "description": "An operating system, eg. \"ubuntu\", \"windows\", \"centos\". We also consider \"kubernetes\" to be an OS. Or \"all\".",
                                        "type": "string"
                                    },
                                    "series": {
                                        "description": "A release of the operating system.  eg. \"xenial\" for Ubuntu, \"10\" for Windows, \"7\" for CentOS.Or \"all\".",
                                        "type": "string"
                                    }
                                },
                                "type": "object"
                            },
                            "type": "array"
                        },
                        "readme-md": {
                            "description": "The content of this revision's README.md file.",
                            "type": "string"
                        },
                        "revision": {
                            "description": "The integer revision number.",
                            "type": "number"
                        },
                        "version": {
                            "description": "This revision's version string.",
                            "type": "string"
                        }
                    },
                    "type": "object"
                }
            },
            "type": "object"
        },
        "id": {
            "description": "This charm or bundle's ID within the store.",
            "pattern": "[0-9a-zA-Z]{32}",
            "type": "string"
        },
        "name": {
            "description": "Names of charms and bundles share a single flat namespace, so can usually be used as the unique identifier of a charm or bundle.",
            "type": "string"
        },
        "result": {
            "additionalProperties": false,
            "description": "The fields of the bundle or charm.",
            "properties": {
                "bugs-url": {
                    "description": "For reporting problems with this charm. May be a web page or a mailto: URL.",
                    "type": "string"
                },
                "categories": {
                    "description": "Categories to which the charm belongs.",
                    "items": {
                        "additionalProperties": false,
                        "description": "A category to which the charm belongs",
                        "properties": {
                            "featured": {
                                "description": "Has the charm been selected by the store for high visibility to users within this category?",
                                "type": "boolean"
                            },
                            "name": {
                                "description": "The category name",
                                "type": "string"
                            }
                        },
                        "type": "object"
                    },
                    "type": "array"
                },
                "contains-charms": {
                    "description": "Charms in this bundle (bundles only)",
                    "items": {
                        "additionalProperties": false,
                        "properties": {
                            "name": {
                                "description": "The charm's name",
                                "type": "string"
                            },
                            "package-id": {
                                "description": "The charm's unique identifier",
                                "type": "string"
                            },
                            "store-url": {
                                "description": "The store URL of this revision",
                                "type": "string"
                            }
                        },
                        "required": [
                            "package-id",
                            "name",
                            "store-url"
                        ],
                        "type": "object"
                    },
                    "type": "array"
                },
                "description": {
                    "description": "The charm's human-readable description, which may be very long.",
                    "type": "string"
                },
                "license": {
                    "description": "The charm license.",
                    "type": "string"
                },
                "media": {
                    "description": "An array of images, screenshots, icons, videos.",
                    "items": {
                        "additionalProperties": false,
                        "description": "A single image or video",
                        "properties": {
                            "height": {
                                "description": "Height of raster images. Omitted for SVG.",
                                "type": [
                                    "null",
                                    "integer"
                                ]
                            },
                            "type": {
                                "description": "Media type",
                                "type": "string"
                            },
                            "url": {
                                "description": "URL of the media",
                                "type": "string"
                            },
                            "width": {
                                "description": "Width of raster images. Omitted for SVG.",
                                "type": [
                                    "null",
                                    "integer"
                                ]
                            }
                        },
                        "type": "object"
                    },
                    "type": "array"
                },
                "publisher": {
                    "additionalProperties": false,
                    "description": "Only .display-name will be populated initially. Other fields will be added later, to match snap publishers, as the PublisherGW comes online and populates those fields.",
                    "properties": {
                        "display-name": {
                            "description": "The publisher's name as a human-readable string.",
                            "type": "string"
                        }
                    },
                    "type": "object"
                },
                "store-url": {
                    "description": "This charm's page in the charmhub store.",
                    "type": "string"
                },
                "store-url-old": {
                    "description": "This charm's page in the old, deprecated store.",
                    "type": "string"
                },
                "summary": {
                    "description": "One-line description of the charm.",
                    "type": "string"
                },
                "used-by": {
                    "description": "Bundles that use this (charms only).",
                    "items": {
                        "description": "A bundle name",
                        "type": "string"
                    },
                    "type": "array"
                },
                "website": {
                    "description": "External website for the charm.",
                    "type": [
                        "string",
                        "null"
                    ]
                }
            },
            "type": "object"
        },
        "type": {
            "description": "\"charm\" or \"bundle\".",
            "enum": [
                "bundle",
                "charm"
            ],
            "type": "string"
        }
    },
    "required": [
        "type",
        "id",
        "name"
    ],
    "type": "object"
}

list_resource_revisions

Introduced in version 1

Summary: GET /v2/charms/resources/<package_name>/<resource_name>/revisions

List given resource available revisions.

Response JSON Schema

{
    "additionalProperties": false,
    "properties": {
        "revisions": {
            "items": {
                "additionalProperties": false,
                "properties": {
                    "download": {
                        "additionalProperties": false,
                        "properties": {
                            "hash-sha256": {
                                "type": "string"
                            },
                            "hash-sha3-384": {
                                "type": "string"
                            },
                            "hash-sha384": {
                                "type": "string"
                            },
                            "hash-sha512": {
                                "type": "string"
                            },
                            "size": {
                                "type": "number"
                            },
                            "url": {
                                "type": "string"
                            }
                        },
                        "type": "object"
                    },
                    "name": {
                        "type": "string"
                    },
                    "revision": {
                        "type": "number"
                    },
                    "type": {
                        "type": "string"
                    }
                },
                "type": "object"
            },
            "type": "array"
        }
    },
    "required": [
        "revisions"
    ],
    "type": "object"
}

charm_refresh

Introduced in version 23

Summary: POST /v2/charms/refresh

Get the best revisions to install/refresh for the given charms.

charm_refresh changelog

  • Version 31: Remove unused metadata-yaml field

  • Version 30: Added resource fields 'filename' and 'description'

  • Version 29: Added 'resources' field.

  • Version 23: Endpoint created.

Request JSON Schema

{
    "additionalProperties": false,
    "properties": {
        "actions": {
            "items": {
                "additionalProperties": false,
                "properties": {
                    "action": {
                        "enum": [
                            "download",
                            "install",
                            "refresh",
                            "refresh-all"
                        ],
                        "type": "string"
                    },
                    "channel": {
                        "type": "string"
                    },
                    "id": {
                        "type": "string"
                    },
                    "instance-key": {
                        "type": "string"
                    },
                    "name": {
                        "type": "string"
                    },
                    "platform": {
                        "additionalProperties": false,
                        "properties": {
                            "architecture": {
                                "description": "eg. \"amd64\", or \"all\".",
                                "type": "string"
                            },
                            "os": {
                                "description": "An operating system, eg. \"ubuntu\", \"windows\", \"centos\". We also consider \"kubernetes\" to be an OS. Or \"all\".",
                                "type": "string"
                            },
                            "series": {
                                "description": "A release of the operating system.  eg. \"xenial\" for Ubuntu, \"10\" for Windows, \"7\" for CentOS.Or \"all\".",
                                "type": "string"
                            }
                        },
                        "type": "object"
                    },
                    "revision": {
                        "type": "number"
                    }
                },
                "required": [
                    "action"
                ],
                "type": "object"
            },
            "type": "array"
        },
        "context": {
            "items": {
                "additionalProperties": false,
                "properties": {
                    "id": {
                        "type": "string"
                    },
                    "instance-key": {
                        "type": "string"
                    },
                    "platform": {
                        "additionalProperties": false,
                        "properties": {
                            "architecture": {
                                "description": "eg. \"amd64\", or \"all\".",
                                "type": "string"
                            },
                            "os": {
                                "description": "An operating system, eg. \"ubuntu\", \"windows\", \"centos\". We also consider \"kubernetes\" to be an OS. Or \"all\".",
                                "type": "string"
                            },
                            "series": {
                                "description": "A release of the operating system.  eg. \"xenial\" for Ubuntu, \"10\" for Windows, \"7\" for CentOS.Or \"all\".",
                                "type": "string"
                            }
                        },
                        "type": "object"
                    },
                    "refreshed-date": {
                        "type": "string"
                    },
                    "revision": {
                        "type": "number"
                    },
                    "tracking-channel": {
                        "type": "string"
                    }
                },
                "required": [
                    "id",
                    "instance-key",
                    "platform",
                    "revision",
                    "tracking-channel"
                ],
                "type": "object"
            },
            "type": "array"
        },
        "fields": {
            "items": {
                "type": "string"
            },
            "type": "array"
        }
    },
    "required": [
        "context",
        "actions"
    ],
    "type": "object"
}

Response JSON Schema

{
    "additionalProperties": false,
    "properties": {
        "error-list": {
            "items": {
                "additionalProperties": false,
                "properties": {
                    "code": {
                        "type": "string"
                    },
                    "message": {
                        "type": "string"
                    }
                },
                "required": [
                    "code",
                    "message"
                ],
                "type": "object"
            },
            "type": "array"
        },
        "results": {
            "items": {
                "additionalProperties": false,
                "properties": {
                    "charm": {
                        "additionalProperties": false,
                        "properties": {
                            "contact": {
                                "type": "string"
                            },
                            "created-at": {
                                "type": "string"
                            },
                            "description": {
                                "type": "string"
                            },
                            "download": {
                                "additionalProperties": false,
                                "description": "The revision's download information.",
                                "properties": {
                                    "hash-sha-256": {
                                        "description": "The download's hash.",
                                        "type": [
                                            "string",
                                            "null"
                                        ]
                                    },
                                    "size": {
                                        "description": "The download's size in bytes.",
                                        "type": "number"
                                    },
                                    "url": {
                                        "description": "The download's url.",
                                        "type": "string"
                                    }
                                },
                                "type": "object"
                            },
                            "id": {
                                "type": "string"
                            },
                            "license": {
                                "type": "string"
                            },
                            "media": {
                                "items": {
                                    "additionalProperties": false,
                                    "properties": {
                                        "height": {
                                            "type": [
                                                "null",
                                                "integer"
                                            ]
                                        },
                                        "type": {
                                            "type": "string"
                                        },
                                        "url": {
                                            "type": "string"
                                        },
                                        "width": {
                                            "type": [
                                                "null",
                                                "integer"
                                            ]
                                        }
                                    },
                                    "required": [
                                        "type",
                                        "url",
                                        "width",
                                        "height"
                                    ],
                                    "type": "object"
                                },
                                "type": "array"
                            },
                            "name": {
                                "type": "string"
                            },
                            "platforms": {
                                "items": {
                                    "additionalProperties": false,
                                    "properties": {
                                        "architecture": {
                                            "description": "eg. \"amd64\", or \"all\".",
                                            "type": "string"
                                        },
                                        "os": {
                                            "description": "An operating system, eg. \"ubuntu\", \"windows\", \"centos\". We also consider \"kubernetes\" to be an OS. Or \"all\".",
                                            "type": "string"
                                        },
                                        "series": {
                                            "description": "A release of the operating system.  eg. \"xenial\" for Ubuntu, \"10\" for Windows, \"7\" for CentOS.Or \"all\".",
                                            "type": "string"
                                        }
                                    },
                                    "type": "object"
                                },
                                "type": "array"
                            },
                            "private": {
                                "type": "boolean"
                            },
                            "publisher": {
                                "additionalProperties": false,
                                "properties": {
                                    "display-name": {
                                        "type": "string"
                                    },
                                    "id": {
                                        "type": "string"
                                    },
                                    "username": {
                                        "type": "string"
                                    },
                                    "validation": {
                                        "type": "string"
                                    }
                                },
                                "required": [
                                    "id",
                                    "username",
                                    "display-name"
                                ],
                                "type": "object"
                            },
                            "resources": {
                                "introduced_at": 29,
                                "items": {
                                    "additionalProperties": false,
                                    "properties": {
                                        "description": {
                                            "introduced_at": 30,
                                            "type": "string"
                                        },
                                        "download": {
                                            "additionalProperties": false,
                                            "properties": {
                                                "hash-sha256": {
                                                    "type": "string"
                                                },
                                                "hash-sha3-384": {
                                                    "type": "string"
                                                },
                                                "hash-sha384": {
                                                    "type": "string"
                                                },
                                                "hash-sha512": {
                                                    "type": "string"
                                                },
                                                "size": {
                                                    "type": "number"
                                                },
                                                "url": {
                                                    "type": "string"
                                                }
                                            },
                                            "type": "object"
                                        },
                                        "filename": {
                                            "introduced_at": 30,
                                            "type": "string"
                                        },
                                        "name": {
                                            "type": "string"
                                        },
                                        "revision": {
                                            "type": "number"
                                        },
                                        "type": {
                                            "type": "string"
                                        }
                                    },
                                    "type": "object"
                                },
                                "type": "array"
                            },
                            "revision": {
                                "type": "number"
                            },
                            "summary": {
                                "type": "string"
                            },
                            "version": {
                                "type": "string"
                            },
                            "website": {
                                "type": "string"
                            }
                        },
                        "type": [
                            "object",
                            "null"
                        ]
                    },
                    "effective-channel": {
                        "type": "string"
                    },
                    "error": {
                        "additionalProperties": false,
                        "properties": {
                            "code": {
                                "type": "string"
                            },
                            "extra": {
                                "type": "object"
                            },
                            "message": {
                                "type": "string"
                            }
                        },
                        "required": [
                            "code",
                            "message"
                        ],
                        "type": "object"
                    },
                    "id": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "instance-key": {
                        "type": "string"
                    },
                    "name": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "redirect-channel": {
                        "type": "string"
                    },
                    "released-at": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "result": {
                        "type": "string"
                    }
                },
                "required": [
                    "instance-key",
                    "id",
                    "name",
                    "result"
                ],
                "type": "object"
            },
            "type": "array"
        }
    },
    "required": [
        "results",
        "error-list"
    ],
    "type": "object"
}

charm_find

Introduced in version 22

Summary: GET /v2/charms/find

"Find charms" handler.

Given a search term, return an array of matching search results. Each result will either be a charm or a bundle.

Supports the following optional query params:

  • q: The search term.
  • fields: A comma separated list of field names to include in the response. Optional. The following are always returned: type, id, name. Possible field names are in the successful response description below.

Responses are a JSON encoded dict. A successful response contains:

{
    "results": [
        RESULT,
        RESULT,
        ...
    ]
}

Where each RESULT object represents a single charm or bundle, and contains:

{
    "type": "charm" or "bundle".
    "id": str # 32 character identifier
    "name": str # The unique name of the charm or bundle.
    "result": {...} # Charm or bundle fields. Optional.
    "default-release": { # Optional.
        "channel": {...} # Most stable risk on default track. Optional.
        "revision": {...} # Last revision on that channel. Optional.
    }
}

Optional fields are only included if requested using the 'fields' param. See 'description' fields in the schema for each field and their sub-fields.

Alternatively, an unsuccessful (non 2xx) response contains:

{
    "error-list": [
        {
            "code": str # String slug to identify the error type.
            "message": str # Human readble error message.
        },
        ...
    ]
}

charm_find changelog

  • Version 30: Added resource fields 'filename' and 'description'

  • Version 29: Added 'bundle-yaml' field to revision.

  • Version 28: Added 'resources' field to channelmap.

  • Version 22: Endpoint created.

Response JSON Schema

{
    "additionalProperties": false,
    "properties": {
        "results": {
            "items": {
                "additionalProperties": false,
                "description": "The id and name of the requested charm or bundle, along with optional components: Its fields, all its releases in the form of a channel-map, and its most stable channel, along with the most recent revision on that channel.",
                "properties": {
                    "default-release": {
                        "additionalProperties": false,
                        "description": "A duplicate of the single channel-map entry representing the default channel & the last revision released on it. Default channel is defined as the most stable risk (eg. \"stable\") on the default track (falling back to \"latest\"). This is the channel used for deploys if clients express no overriding preferences. This allows clients to request representative info, such as when the last release was made, or how big the download will be, without having to request all the numerous entries in the full channel-map, or duplicate the server's logic for choosing the default channel.",
                        "properties": {
                            "channel": {
                                "additionalProperties": false,
                                "description": "A channel used for releases, along with a revision released on that channel.",
                                "properties": {
                                    "name": {
                                        "description": "This channel's full name, as track/risk. eg \"latest/stable\".",
                                        "type": "string"
                                    },
                                    "platform": {
                                        "additionalProperties": false,
                                        "description": "This channel's supported platform.",
                                        "properties": {
                                            "architecture": {
                                                "description": "eg. \"amd64\", or \"all\".",
                                                "type": "string"
                                            },
                                            "os": {
                                                "description": "An operating system, eg. \"ubuntu\", \"windows\", \"centos\". We also consider \"kubernetes\" to be an OS. Or \"all\".",
                                                "type": "string"
                                            },
                                            "series": {
                                                "description": "A release of the operating system.  eg. \"xenial\" for Ubuntu, \"10\" for Windows, \"7\" for CentOS.Or \"all\".",
                                                "type": "string"
                                            }
                                        },
                                        "type": "object"
                                    },
                                    "released-at": {
                                        "description": "The timestamp of the last release to this channel.",
                                        "type": [
                                            "string",
                                            "null"
                                        ]
                                    },
                                    "risk": {
                                        "description": "This channel's risk, eg \"stable\", \"candidate\", \"beta\", \"edge\".",
                                        "type": "string"
                                    },
                                    "track": {
                                        "description": "This channel's track. eg. \"latest\".",
                                        "type": "string"
                                    }
                                },
                                "type": "object"
                            },
                            "resources": {
                                "introduced_at": 28,
                                "items": {
                                    "additionalProperties": false,
                                    "properties": {
                                        "description": {
                                            "introduced_at": 30,
                                            "type": "string"
                                        },
                                        "download": {
                                            "additionalProperties": false,
                                            "properties": {
                                                "hash-sha256": {
                                                    "type": "string"
                                                },
                                                "hash-sha3-384": {
                                                    "type": "string"
                                                },
                                                "hash-sha384": {
                                                    "type": "string"
                                                },
                                                "hash-sha512": {
                                                    "type": "string"
                                                },
                                                "size": {
                                                    "type": "number"
                                                },
                                                "url": {
                                                    "type": "string"
                                                }
                                            },
                                            "type": "object"
                                        },
                                        "filename": {
                                            "introduced_at": 30,
                                            "type": "string"
                                        },
                                        "name": {
                                            "type": "string"
                                        },
                                        "revision": {
                                            "type": "number"
                                        },
                                        "type": {
                                            "type": "string"
                                        }
                                    },
                                    "type": "object"
                                },
                                "type": "array"
                            },
                            "revision": {
                                "additionalProperties": false,
                                "description": "",
                                "properties": {
                                    "created-at": {
                                        "description": "The timestamp of this revision's creation.",
                                        "type": "string"
                                    },
                                    "download": {
                                        "additionalProperties": false,
                                        "description": "The revision's download information.",
                                        "properties": {
                                            "hash-sha-256": {
                                                "description": "The download's hash.",
                                                "type": [
                                                    "string",
                                                    "null"
                                                ]
                                            },
                                            "size": {
                                                "description": "The download's size in bytes.",
                                                "type": "number"
                                            },
                                            "url": {
                                                "description": "The download's url.",
                                                "type": "string"
                                            }
                                        },
                                        "type": "object"
                                    },
                                    "platforms": {
                                        "description": "The revision's supported platforms.",
                                        "items": {
                                            "additionalProperties": false,
                                            "properties": {
                                                "architecture": {
                                                    "description": "eg. \"amd64\", or \"all\".",
                                                    "type": "string"
                                                },
                                                "os": {
                                                    "description": "An operating system, eg. \"ubuntu\", \"windows\", \"centos\". We also consider \"kubernetes\" to be an OS. Or \"all\".",
                                                    "type": "string"
                                                },
                                                "series": {
                                                    "description": "A release of the operating system.  eg. \"xenial\" for Ubuntu, \"10\" for Windows, \"7\" for CentOS.Or \"all\".",
                                                    "type": "string"
                                                }
                                            },
                                            "type": "object"
                                        },
                                        "type": "array"
                                    },
                                    "revision": {
                                        "description": "The integer revision number.",
                                        "type": "number"
                                    },
                                    "version": {
                                        "description": "This revision's version string.",
                                        "type": "string"
                                    }
                                },
                                "type": "object"
                            }
                        },
                        "type": "object"
                    },
                    "id": {
                        "description": "This charm or bundle's ID within the store.",
                        "pattern": "[0-9a-zA-Z]{32}",
                        "type": "string"
                    },
                    "name": {
                        "description": "Names of charms and bundles share a single flat namespace, so can usually be used as the unique identifier of a charm or bundle.",
                        "type": "string"
                    },
                    "result": {
                        "additionalProperties": false,
                        "description": "The fields of the bundle or charm.",
                        "properties": {
                            "bugs-url": {
                                "description": "For reporting problems with this charm. May be a web page or a mailto: URL.",
                                "type": "string"
                            },
                            "categories": {
                                "description": "Categories to which the charm belongs.",
                                "items": {
                                    "additionalProperties": false,
                                    "description": "A category to which the charm belongs",
                                    "properties": {
                                        "featured": {
                                            "description": "Has the charm been selected by the store for high visibility to users within this category?",
                                            "type": "boolean"
                                        },
                                        "name": {
                                            "description": "The category name",
                                            "type": "string"
                                        }
                                    },
                                    "type": "object"
                                },
                                "type": "array"
                            },
                            "contains-charms": {
                                "description": "Charms in this bundle (bundles only)",
                                "items": {
                                    "additionalProperties": false,
                                    "properties": {
                                        "name": {
                                            "description": "The charm's name",
                                            "type": "string"
                                        },
                                        "package-id": {
                                            "description": "The charm's unique identifier",
                                            "type": "string"
                                        },
                                        "store-url": {
                                            "description": "The store URL of this revision",
                                            "type": "string"
                                        }
                                    },
                                    "required": [
                                        "package-id",
                                        "name",
                                        "store-url"
                                    ],
                                    "type": "object"
                                },
                                "type": "array"
                            },
                            "description": {
                                "description": "The charm's human-readable description, which may be very long.",
                                "type": "string"
                            },
                            "license": {
                                "description": "The charm license.",
                                "type": "string"
                            },
                            "media": {
                                "description": "An array of images, screenshots, icons, videos.",
                                "items": {
                                    "additionalProperties": false,
                                    "description": "A single image or video",
                                    "properties": {
                                        "height": {
                                            "description": "Height of raster images. Omitted for SVG.",
                                            "type": [
                                                "null",
                                                "integer"
                                            ]
                                        },
                                        "type": {
                                            "description": "Media type",
                                            "type": "string"
                                        },
                                        "url": {
                                            "description": "URL of the media",
                                            "type": "string"
                                        },
                                        "width": {
                                            "description": "Width of raster images. Omitted for SVG.",
                                            "type": [
                                                "null",
                                                "integer"
                                            ]
                                        }
                                    },
                                    "type": "object"
                                },
                                "type": "array"
                            },
                            "publisher": {
                                "additionalProperties": false,
                                "description": "Only .display-name will be populated initially. Other fields will be added later, to match snap publishers, as the PublisherGW comes online and populates those fields.",
                                "properties": {
                                    "display-name": {
                                        "description": "The publisher's name as a human-readable string.",
                                        "type": "string"
                                    }
                                },
                                "type": "object"
                            },
                            "store-url": {
                                "description": "This charm's page in the charmhub store.",
                                "type": "string"
                            },
                            "store-url-old": {
                                "description": "This charm's page in the old, deprecated store.",
                                "type": "string"
                            },
                            "summary": {
                                "description": "One-line description of the charm.",
                                "type": "string"
                            },
                            "used-by": {
                                "description": "Bundles that use this (charms only).",
                                "items": {
                                    "description": "A bundle name",
                                    "type": "string"
                                },
                                "type": "array"
                            },
                            "website": {
                                "description": "External website for the charm.",
                                "type": [
                                    "string",
                                    "null"
                                ]
                            }
                        },
                        "type": "object"
                    },
                    "type": {
                        "description": "\"charm\" or \"bundle\".",
                        "enum": [
                            "bundle",
                            "charm"
                        ],
                        "type": "string"
                    }
                },
                "required": [
                    "type",
                    "id",
                    "name"
                ],
                "type": "object"
            },
            "type": "array"
        }
    },
    "required": [
        "results"
    ],
    "type": "object"
}

© 2019 Canonical Ltd. Ubuntu and Canonical are registered trademarks of Canonical Ltd.