List all template sets.
Template sets are used to group available templates by topic. The 'default'
template set contains all vanilla SUSE templates, 'mono' contains those that
are optimized to be used for mono applications, for example.

Result: Example

GET /api/v2/user/template_sets/<name>

Arguments:

name - Name of template

Show template set name.

Result: Example

Appliances

GET /api/v2/user/appliances

List all appliances of the current user.

Result: Example

GET /api/v2/user/appliances/<id>

Arguments:

id - Id of the appliance

Show details of appliance with id id.

Result: Example

GET /api/v2/user/appliances/<id>/status

Arguments:

id - Id of the appliance

Show information on the status of the appliance with id id.

Result: Example

POST /api/v2/user/appliances?clone_from=<appliance_id>&name=<name>&arch=<arch>

Arguments:

clone_from - The template the new appliance should be based on.
name (optional) - The name of appliance
arch (optional) - The architecture of the appliance (x86_64 or i686)

Create a new appliance by cloning a template or another appliance with the id appliance_id.
If name is left out, a name will be generated. If arch is left out a i686 appliance will be created.

DELETE /api/v2/user/appliances/<id>

Arguments:

id - Id of the appliance

Delete appliance with id id.

Configuration

GET /api/v2/user/appliances/<id>/configuration

Arguments:

id - Id of the appliance

Returns the configuration for the appliance.

Result: Example

PUT /api/v2/user/appliances/<id>/configuration

Arguments:

id - Id of the appliance

Modify portions (or all) of the configuration. The input is sent as XML fragments in the POST body, using the same schema as what the GET call. For example, to change the network settings to "dhcp", the POST body would have:



dhcp

The result is then the current configuration settings, or an error.

Result: Example

GET /api/v2/user/appliances/<id>/configuration/logo

Arguments:

id - Id of the appliance

Returns the PNG of the appliance logo.

PUT /api/v2/user/appliances/<id>/configuration/logo

Arguments:

id - Id of the appliance

Changes the appliance logo. The data must be sent as a form-based upload (RFC 1867) in the file parameter in the body.

Returns a success or fail message.

GET /api/v2/user/appliances/<id>/configuration/background

Arguments:

id - Id of the appliance

Returns the appliance background as a 100x100 thumbnail.

PUT /api/v2/user/appliances/<id>/configuration/background

Arguments:

id - Id of the appliance

Changes the appliance background. The data must be sent as a form-based upload (RFC 1867) in the file parameter in the body.

Returns a success or fail message.

Sharing

GET /api/v2/user/appliances/<id>/sharing

Arguments:

id - Id of the appliance

Lists the users who are allowed to clone this appliance.

Result: Example

POST /api/v2/user/appliances/<id>/sharing/<username>

Arguments:

id - Id of the appliance
username - A username

Allows username to clone from this appliance.

Result: Example

DELETE /api/v2/user/appliances/<id>/sharing/<username>

Arguments:

id - Id of the appliance
username - A username

Removes username from the list of users allowed to clone this appliance.

Result: Example

Repositories

GET /api/v2/user/appliances/<id>/repositories

Arguments:

id - Id of the appliance

List all repositories of the appliance with id id.

Result: Example

PUT /api/v2/user/appliances/<id>/repositories

Arguments:

id - Id of the appliance

Update the list of repositories of the appliance with id id.

Note: Only the repository ids of the put xml are considered.

Result: Example

POST /api/v2/user/appliances/<id>/cmd/add_repository?repo_id=<repo_id>

Arguments:

id - Id of the appliance
repo_id - Id of the repository.

Add the specified repository to the appliance with id id.

Result: Example

POST /api/v2/user/appliances/<id>/cmd/remove_repository?repo_id=<repo_id>

Arguments:

id - Id of the appliance
repo_id - Id of the repository.

Remove the specified repository from the appliance with id id.

Result: Example

POST /api/v2/user/appliances/<id>/cmd/add_user_repository

Arguments:

id - Id of the appliance

Adds the according user repository (the one containing the uploaded RPMs) to the appliance.

Software Selection

GET /api/v2/user/appliances/<id>/software

Arguments:

id - Id of the appliance

List all selected packages and patterns of the appliance with id id.

Result: Example

PUT /api/v2/user/appliances/<id>/software

Arguments:

id - Id of the appliance

Update the list of selected packages and patterns of the appliance with id id.

Result: Example

GET /api/v2/user/appliances/<id>/software/installed?build_id=<build>

Arguments:

id - Id of the appliance
build_id (optional) - Id of the build.

List all packages and patterns that are installed. You can either specify the
appliance with the appliance_id parameter, which will list the software
that will installed with the next build or via an build id. That makes it possible
to retrieve the installed software for older builds.

Result: Example

POST /api/v2/user/appliances/<id>/cmd/add_package?name=<name>&version=<version>&repository_id=<repo_id>

Arguments:

id - Id of the appliance
name - Name of the package.
version (optional) - Version of the package.
repository_id (optional) - Repository to pick the package from.

Add the specified package to the appliance with id id.

Result: Example

POST /api/v2/user/appliances/<id>/cmd/remove_package?name=<name>

Arguments:

id - Id of the appliance
name - Name of the package.

Remove the specified package from the appliance with id id.

Result: Example

POST /api/v2/user/appliances/<id>/cmd/add_pattern?name=<name>&version=<version>&repository_id=<repo_id>

Arguments:

id - Id of the appliance
name - Name of the pattern.
version (optional) - Version of the pattern.
repository_id (optional) - Repository to pick the pattern from.

Add the specified pattern to the appliance with id id.

Result: Example

POST /api/v2/user/appliances/<id>/cmd/remove_pattern?name=<name>

Arguments:

id - Id of the appliance
name - Name of the pattern.

Remove the specified pattern from the appliance with id id.

Result: Example

POST /api/v2/user/appliances/<id>/cmd/ban_package?name=<name>

Arguments:

id - Id of the appliance
name - Name of the package.

Ban a package from the appliance with id id.

Result: Example

POST /api/v2/user/appliances/<id>/cmd/unban_package?name=<name>

Arguments:

id - Id of the appliance
name - Name of the package.

Unban a package from the appliance with id id.

Result: Example

GET /api/v2/user/appliances/<id>/software/search?q=<search_string>&all_fields=<all_fields>&all_repos=<all_repos>

Arguments:

id - Id of the appliance
q - The search string
all_fields (optional) - Option to perform the search on all fields. Default is 'false'.
all_repos (optional) - Option to perform the search on all repositories. Default is 'false'.

Search all software that matches the given search_string. If the all_fields
parameter is set to true all fields are considered, otherwise only the name of the package
or pattern is matched against the search_string.
By default only software that is available to the appliance is considered, e.g. the search is limited to the
repositories of this appliances. If you want to search in all repositories set the all_repos parameter to true.

Result: Example

GET /api/v2/user/appliances/<id>/software/manifest/<image_type>?version=<version>

Arguments:

id - Id of the appliance
image_type - The image type
version (optional) - Build version

This call returns the XML manifest file.

Image files

GET /api/v2/user/appliances/<id>/image_files?build_id=<build_id>&path=<path_to_file>

Arguments:

id - Id of the appliance.
build_id - Id of the build.
path - Path to the file in the built appliance.

Returns the file with the given path from an image.

GPG Keys

SUSE Studio allows to upload GPG keys that will be imported when the appliance is built.

GET /api/v2/user/appliances/<id>/gpg_keys

Arguments:

id - Id of the appliance.

Lists all GPG keys of the appliance with the id id.

Result: Example

GET /api/v2/user/appliances/<id>/gpg_keys/<key_id>

Arguments:

id - Id of the appliance.
key_id - Id of the GPG key.

Shows information on the GPG key with the id key_id.

Result: Example

POST /api/v2/user/appliances/<id>/gpg_keys?name=<name>&target=<target>&key=<the_key>

Arguments:

id - Id of the appliance.
name - A name for the key.
target - The target specifies in which keyring the key will be importet. Possible values are: 'rpm'.
key (optional) - The URL encoded key.

Uploads a GPG key to the appliance with the id id. The key can either
be given as the key parameter or wrapped as with form-based file uploads
in HTML (RFC 1867) in the body of the POST request.
The key will be imported into the keyring that is specified in the target parameter.

Result: Example

DELETE /api/v2/user/appliances/<id>/gpg_keys/<key_id>

Arguments:

id - Id of the appliance.
key_id - Id of the GPG key.

Deletes the GPG key with the id key_id from the appliance.

Overlay files

GET /api/v2/user/files?appliance_id=<id>

Arguments:

appliance_id - Id of the appliance.

List all overlay files of appliance with id id.

Result: Example

POST /api/v2/user/files?appliance_id=<id>&filename=<name>&path=<path>&owner=<owner>&group=<group>&permissions=<perms>&enabled=<enabled>&url=<url>

Arguments:

appliance_id - Id of the appliance.
filename (optional) - The name of the file in the filesystem.
path (optional) - The path where the file will be stored.
owner (optional) - The owner of the file.
group (optional) - The group of the file.
permissions (optional) - The permissions of the file.
enabled (optional) - Used to enable/disable this file for the builds.
url (optional) - The url of the file to add from the internet (HTTP and FTP are supported) when using the web upload method

Adds a file to the appliance with id id.
Files can either be uploaded in the body of the POST request or from a URL in the web:

With direct uploads the file is expected to be wrapped as with form-based file uploads in HTML (RFC 1867) in the body
of the POST request as the file parameter.
For Uploads from the web you have to provide the url parameter.

Optionally, one or more metadata settings can be specified. If those are left out, they
can also be change later (see below).

Result: Example

GET /api/v2/user/files/<file_id>/data

Arguments:

file_id - Id of the file.

Returns the file with id file_id.

PUT /api/v2/user/files/<file_id>/data

Arguments:

file_id - Id of the file.

Writes the content of the file with id file_id.
The file is expected to be wrapped as with form-based file uploads in HTML (RFC 1867) in the body of the PUT request
as the file parameter.

Result: Example

GET /api/v2/user/files/<file_id>

Arguments:

file_id - Id of the file.

Returns the meta data of the file with id file_id.

Result: Example

PUT /api/v2/user/files/<file_id>

Arguments:

file_id - Id of the file.

Writes the meta data of the file with id file_id.

Result: Example

DELETE /api/v2/user/files/<file_id>

Arguments:

file_id - Id of the file.

Delete the file with id file_id and its meta data.

Running builds

GET /api/v2/user/running_builds?appliance_id=<id>

Arguments:

appliance_id - Id of the appliance.

List all running builds for the appliance with id id.

Result: Example

GET /api/v2/user/running_builds/<build_id>

Arguments:

build_id - Id of the build.

Show status of the build with id build_id.

Result: Example

POST /api/v2/user/running_builds?appliance_id=<id>&force=<force>&version=<version>&image_type=<type>&multi=<multi>

Arguments:

appliance_id - Id of the appliance.
force (optional) - Force a build even if it overwrites an already existing build.
version (optional) - The version of the appliance.
image_type (optional) - The format of the build. Supported are 'xen', 'oem', 'vmx', 'iso', 'ec2', 'net', 'oemiso'.
multi (optional) - If set to true it enables multibuild mode, which allows to build different formats of one version.

Start a new build for the appliance with id id.
If there already is a build with the same appliance settings (build type and version)
an error is returned. In this case a build can be enforced by setting the optional
force parameter to true.
Optionally the appliance version and build type can be set with the version and image_type parameters.
It is possible to build different formats of one appliance version. Therefor do a first build and when it's done trigger
the other formats with the multi parameter set to true.

DELETE /api/v2/user/running_builds/<build_id>

Arguments:

build_id - Id of the build.

Cancel build with id build_id.

Finished builds

GET /api/v2/user/builds?appliance_id=<id>

Arguments:

appliance_id - Id of the appliance.

List all completed builds for the appliance with id id.

Result: Example

GET /api/v2/user/builds/<build_id>

Arguments:

build_id - Id of the build.

Show build info of the build with id build_id.

Result: Example

DELETE /api/v2/user/builds/<build_id>

Arguments:

build_id - Id of the build.

Delete build with id build_id.

RPM Uploads

GET /api/v2/user/rpms?base_system=<base>

Arguments:

base_system - Base system of the RPM or archive, e.g. 11.1 or SLED11.

List all uploaded RPMs for the base system base.

Result: Example

GET /api/v2/user/rpms/<rpm_id>

Arguments:

rpm_id - ID of the uploaded RPM.

Show information on the uploaded RPM with id rpm_id.

Result: Example

GET /api/v2/user/rpms/<rpm_id>/data

Arguments:

rpm_id - ID of the uploaded RPM.

Returns the RPM with id rpm_id.

POST /api/v2/user/rpms?base_system=<base>

Arguments:

base_system - Base system of the RPM or archive, e.g. 11.1 or SLED11.

Adds an RPM or archive to the user repository for appliances base on base.
The file is expected to be wrapped as with form-based file uploads in HTML (RFC 1867) in the body of the POST request
as the file parameter.

Result: Example

PUT /api/v2/user/rpms/<rpm_id>

Arguments:

rpm_id - ID of the uploaded RPM.

Update the content of the RPM or archive with the id rpm_id.
The file is expected to be wrapped as with form-based file uploads in HTML (RFC 1867) in the body of the POST request
as the file parameter.

Result: Example

DELETE /api/v2/user/rpms/<rpm_id>

Arguments:

rpm_id - ID of the uploaded RPM.

Deletes the RPM or archive with the id rpm_id from the user repository.

Repositories

GET /api/v2/user/repositories?base_system=<base>&filter=<search_string>

Arguments:

base_system (optional) - Limit the results to repositories with this base system.
filter (optional) - Only show repositories matching this search string.

Returns a list of repositories. If neither base_system nor filter are specified all available repositories are returned.
When filtering the results with the filter parameter, the repository name, repository url and repository packages are searched.

Result: Example

POST /api/v2/user/repositories?url=<url>&name=<name>

Arguments:

url - Base url of the repository.
name - Name for the repository.

Imports a new repository into Studio. Returns the metadata for the created repository.

Result: Example

GET /api/v2/user/repositories/<id>

Arguments:

id - Id of the repository.

Show information on the repository with the id id.

Result: Example

Testdrives

GET /api/v2/user/testdrives

Returns a list of running testdrives.

Result: Example

POST /api/v2/user/testdrives?build_id=<build_id>

Arguments:

build_id - Id of the build to run in testdrive.

Starts a new testdrive session of the given build on the server and returns information about how to access it.
Note: Testdrive sessions will be aborted when no client has connected after 60 seconds.

Result: Example

Gallery

GET /api/v2/user/gallery/appliances?query=<searchquery>&page=<pagenum>&per_page=<number_per_page>

Arguments:

query - One of four query types (see below). For example, <tt>?latest</tt> will list the latest appliances. <tt>?search=kde</tt> will search for KDE appliances.
page (optional) - Change the list page
per_page (optional) - Number of results per-page (default: 10)

This query will return a list of appliances published to the Gallery. The query types are:

latest - Lists the latest published appliances
popular - Lists the most popular published appliances
username - Lists the appliances published by a specific user
search - Searches appliances based on the search term specified in searchquery

Result: Example

GET /api/v2/user/gallery/appliances/<id>

Arguments:

id - Id of the appliance

This call will return more detailed information about a specific appliance.

Result: Example

GET /api/v2/user/gallery/appliances/<id>/version/<version>

Arguments:

id - Id of the appliance
version - A published version

This call will return more detailed information about a specific appliance.

Result: Example

POST /api/v2/user/gallery/appliances/<id>/version/<version>

Arguments:

id - Id of the appliance
version - The version to publish

This will publish a version to Gallery. The release notes for this version should be in the POST body.

Result: Example

PUT /api/v2/user/gallery/appliances/<id>/version/<version>

Arguments:

id - Id of the appliance
version - Version of the appliance

This will modify the release notes for a specific published version. The release notes should be in the POST body.

Result: Example

DELETE /api/v2/user/gallery/appliances/<id>/version/<version>

Arguments:

id - Id of the appliance
version - Version of the appliance

This will unpublish a version of the appliance. It will return success/fail.

GET /api/v2/user/gallery/appliances/<id>/versions

Arguments:

id - Id of the appliance

Returns the list of appliance versions.

Result: Example

GET /api/v2/user/gallery/appliances/<id>/rating

Arguments:

id - Id of the appliance

Returns the rating of the appliance.

Result: Example

POST /api/v2/user/gallery/appliances/<id>/rating?rating=<rating>

Arguments:

id - Id of the appliance
rating - A numerical rating from 0-5

Rates the appliance. If the user has previously rated this appliance, their rating will be changed.

Result: Example

GET /api/v2/user/gallery/appliances/<id>/software?version=<version>

Arguments:

id - Id of the appliance
version (optional) - A specific version of the appliance

Returns the complete list of software the appliance has. If the version is not specified, the latest published version will be used.

Result: Example

GET /api/v2/user/gallery/appliances/<id>/logo

Arguments:

id - Id of the appliance

Returns the PNG logo of the appliance.

GET /api/v2/user/gallery/appliances/<id>/background.

Arguments:

id - Id of the appliance

Returns the PNG background of the appliance as a 100x100 thumbnail.

POST /api/v2/user/gallery/appliances/<id>/testdrive?version=<version>

Arguments:

id - Id of the appliance
version (optional) - A specific version of the appliance

Starts a testdrive of the appliance, and returns information about how to access the testdrive using VNC.

Result: Example

GET /api/v2/user/gallery/appliances/<id>/comments

Arguments:

id - Id of the appliance

Returns the comments for an appliance.

Result: Example

POST /api/v2/user/gallery/appliances/<id>/comments?parent=<parent>

Arguments:

id - Id of the appliance
parent (optional) - A previous comment that this is in reply to.

Adds a comment to an appliance page.

Result: Example

Return Values

Studio returns several types of return values:

XML according to the call documentation above

A success message: <success></success>

One of many error results, which contain a code and a message. You will find an example at the bottom of the list.

unknown_error - A generic "catch all" when we don't have a more descriptive code to offer. The error message will tell you more.
internal_error - Something went wrong inside Studio, and it's probably not your fault. The error message will tell you more.
access_denied - For whatever reason, you do not have permission to do whatever it is you're trying to do.
wrong_http_method - You are POSTing when you should be GETting, or some other combination.
invalid_xml - You tried to POST XML that was not valid (missing a closing tag, perhaps?)
invalid_node - An unknown node was found during the parsing of POSTed XML.
invalid_value - You've POSTed a value that we can't do anything with.
missing_appliance_id - You've forgotten to tell us which appliance you'd like to work with.
invalid_appliance_id - Whoops!
invalid_version - You've requested a version of an appliance that doesn't exist.
missing_version - Sometimes we need to know which version of an appliance you're intending to GET or modify.
version_not_published - Not all versions of appliances have been published.
version_published - ... and sometimes you try to publish an appliance that is already on Gallery.
unknown_query - When you're searching for appliances in Gallery, you should use the queries we list.
invalid_username - Are you trying to share an appliance with a user who doesn't have an account?
invalid_image_type - Sometimes you get to specify which type of image (ISO, VMX, etc.) you'd like. And sometimes an appliance hasn't been built in that type.
invalid_parent - If you try to reply to a comment that doesn't exist, we'll tell you.
missing_rating - If you want to rate an appliance, you'll need to provide a value...
invalid_rating - ... between 0 and 5.
sle_agreement_missing - You need to accept some legal stuff before you can build and distribute SLE appliances.
invalid_architecture - You can't build ARM appliances yet, sorry.
missing_parameter - Seems you've left something out of your call!
invalid_build_id - You've requested a build of an appliance that doesn't exist.
raw_image_unavailable - We can't gain access to the file you've requested.
invalid_path - You've asked for a file that doesn't exist.
invalid_gpg_key_id - We can't find the GPG key that you're looking for.
invalid_name - We need a name to import GPG keys.
invalid_target - We need a proper target for the GPG key.
key_already_exists - It's already there!
invalid_key - The GPG key isn't going to work out.
invalid_request - Please don't POST with both file and url params together, and don't POST with neither.
invalid_protocol - You can only upload files-via-url that are HTTP(S) or FTP.
download_error - We couldn't download the file you've asked us to download.
invalid_overlay_file_id - I think that's clear enough.
invalid_running_build_id - That too.
read_only_mode_active - You can't modify appliances at the moment, please try again later.
configuration_error - Something has gone horribly wrong and we can't build your appliance.
image_is_locked - You can't rebuild appliances that have been published to the Gallery.
image_already_exists - You've already built a specific version of an appliance, so you'll need to force an overwrite if you want to keep going.
initial_build_pending - You'll need to wait until the first build of an appliance is done before building additional image types.
no_build_slots - We're at full capacity, so you'll need to come back later.
cannot_delete_published_build - You can't delete a published build, so unpublish it and try again.
invalid_template_set - That won't work.
invalid_base_system - That won't, either.
invalid_rpm_id - Yep, nor that.
invalid_file - You can only upload RPMs or tarballs with RPMs in them.
invalid_repository_id - If we can't find the repository, we can't add it to your appliance.
missing_url - We need a URL in order to add a repository.
missing_name - We need a name in order to add a repository.
repository_already_exists - Someone got there first.
user_repository_not_found - You've tried to add a user repository, but we can't find one.
build_not_found - We can't find the build you've asked for.

Result: Example

WARNING: Your browser is in offline mode!

SUSE Studio User API

Table of Contents

General information

Template sets

Appliances

Configuration

Sharing

Repositories

Software Selection

Image files

GPG Keys

Overlay files

Running builds

Finished builds

RPM Uploads

Repositories

Testdrives

Gallery

Return Values

Starting sign in process...

Sign in or create an account

WARNING: Your browser is in offline mode!

SUSE Studio User API

Table of Contents

General information

Template sets

Appliances

Configuration

Sharing

Repositories

Software Selection

Image files

GPG Keys

Overlay files

Running builds

Finished builds

RPM Uploads

Repositories

Testdrives

Gallery

Return Values