# Open Build Service API

Version: 2.7

Only authenticated users are allowed to access the API. Authentication is done
by sending a Basic HTTP Authorisation header.

Do NOT simply add api calls here without discussion before.

The main base routes are:
/source : To handle all source submissions and project setups
/build : To access build results and their states
/published : Read access to published repositories
/search : Access to search interface

## Table of Contents

- About
  - GET /about
- Architectures
  - GET /architectures
- Issue Trackers
  - GET /issue_trackers
  - GET /issue_trackers/<name>
  - PUT /issue_tracker/<name>
  - POST /issue_tracker/<name>
  - DELETE /issue_tracker/<name>
  - GET /issue_trackers/show_url_for
- Distribution List
  - GET /distributions
  - PUT /distributions
  - GET /distributions/<distribution_id>
  - POST /distributions/<distribution_id>
  - GET /distributions/include_remotes
- User data
  - GET /person/<userid>
  - PUT /person/<userid>
  - POST /person?cmd=register
  - POST /person/<userid>
  - GET /person/<userid>/token
  - POST /person/<userid>/token
  - DELETE /person/<userid>/token/<id>
- Group data
  - GET /group
  - GET /group/<group title>
  - PUT /group/<group title>
  - POST /group/<group title>
  - DELETE /group/<group title>
- Sources
  - Projects
    - GET /source/
    - POST /source
    - GET /source/<project>/_meta
    - PUT /source/<project>/_meta
    - DELETE /source/<project>
    - GET /source/<project>/_attribute/<attribute>
    - POST /source/<project>/_attribute/<attribute>
    - DELETE /source/<project>/_attribute/<attribute>
    - GET /source/<project>/_config
    - PUT /source/<project>/_config
    - GET /source/<project>/_pattern
    - GET /source/<project>/_pattern/<patternfile>
    - PUT /source/<project>/_pattern/<patternfile>
    - DELETE /source/<project>/_pattern/<patternfile>
    - GET /source/<project>/_pubkey
    - DELETE /source/<project>/_pubkey
    - POST /source/<project>
  - Packages
    - GET /source/<project>
    - GET /source/<project>/<package>
    - GET /source/<project>/<package>/_meta
    - PUT /source/<project>/<package>/_meta
    - DELETE /source/<project>/<package>
    - GET /source/<project>/<package>/_attribute/<attribute>
    - POST /source/<project>/<package>/_attribute/<attribute>
    - DELETE /source/<project>/<package>/_attribute/<attribute>
    - GET /source/<project>/<package>/_history
    - POST /source/<project>/<package>?cmd=showlinked
    - POST /source/<project>/<package>?cmd=diff
    - POST /source/<project>/<package>?cmd=instantiate
    - POST /source/<project>/<package>?cmd=release
    - POST /source/<project>/<package>?cmd=unlock
    - POST /source/<project>/<package>?cmd=branch
    - POST /source/<project>/<package>?cmd=set_flag
    - POST /source/<project>/<package>?cmd=createSpecFileTemplate
    - POST /source/<project>/<package>?cmd=commit
    - POST /source/<project>/<package>?cmd=collectbuildenv
    - POST /source/<project>/<package>?cmd=importchannel
    - POST /source/<project>/<package>?deleteuploadrev
  - Source files
    - GET /source/<project>/<package>
    - GET /source/<project>/<package>/<filename>
    - PUT /source/<project>/<package>/<filename>
    - DELETE /source/<project>/<package>/<filename>
    - POST /source/<project>/<package>
    - GET /source/<project>/<package>/<binary>/_attribute/<attribute>
    - POST /source/<project>/<package>/<binary>/_attribute/<attribute>
    - DELETE /source/<project>/<package>/<binary>/_attribute/<attribute>
- Requests
  - GET /request
  - GET /request/<id>
  - POST /request
  - PUT /request/<id>
  - POST /request/<id>?cmd=diff
  - POST /request/<id>
- Attribute definition api
  - GET /attribute/
  - GET /attribute/<namespace>/
  - GET /attribute/<namespace>/_meta
  - DELETE /attribute/<namespace>/_meta
  - PUT /attribute/<namespace>/_meta
  - GET /attribute/<namespace>/<name>/_meta
  - DELETE /attribute/<namespace>/<name>/_meta
  - PUT /attribute/<namespace>/<name>/_meta
- Comments api
  - GET /comments/request/:id
  - GET /comments/project/:name
  - GET /comments/package/:project/:pname
  - POST /comments/request/:id
  - POST /comments/project/:name
  - POST /comments/package/:project/:pname
  - DELETE /comment/:id
- Build Results
  - GET /build/
  - GET /build/_workerstatus
  - GET /build/<project>
  - GET /build/<project>/<repository>
  - GET /build/<project>/<repository/<arch>
  - Binaries
    - GET /build/<project>/<repository>/<arch>/<package>
    - GET /build/<project>/<repository>/<arch>/<package>/<binaryname>
    - GET /build/<project>/<repository>/<arch>/<package>/<binaryname>?view=fileinfo
    - GET /build/<project>/<repository>/<arch>/<package>/<binaryname>?view=fileinfo_ext
    - GET /build/<project>/<repository>/<arch>/_builddepinfo
    - POST /build/<project>/<repository>/<arch>/_builddepinfo
    - GET /build/<project>/<repository>/<arch>/_jobhistory?package=<package>&code=succeeded&limit=10
    - GET /build/<project>/<repository>/<arch>/_repository
    - POST /build/<project>/<repository>/<arch>/_repository?match=
    - PUT /build/<project>/<repository>/<arch>/_repository/<file>
    - GET /build/<project>/<repository>/<arch>/_repository/<binaryname>
  - Status
    - GET /build/<project>/_result
    - GET /build/<project>/<repository>/<arch>/<package>/_history
    - GET /build/<project>/<repository>/<arch>/<package>/_reason
    - GET /build/<project>/<repository>/<arch>/<package>/_jobstatus
    - GET /build/<project>/<repository>/<arch>/<package>/_status
    - GET /build/<project>/<repository>/<arch>/<package>/_log
  - Control
    - POST /build/<project>?cmd=rebuild
    - POST /build/<project>?cmd=abortbuild
    - POST /build/<project>?cmd=restartbuild
    - POST /build/<project>?cmd=wipe
  - Local Build
    - GET /build/<project>/<repository>/<arch>/<package>/_buildinfo
    - POST /build/<project>/<repository>/<arch>/<package>/_buildinfo
  - Trigger area
    - POST /trigger/runservice
  - Repository Information
    - GET /build/<project>/<repository>/<arch>/_repository
    - GET /build/<project>/<repository>/<arch>/_repository/<binaryname>
    - GET /build/<project>/<repository>/<arch>/<package>
    - GET /build/<project>/<repository>/<arch>/<package>/_buildinfo
    - POST /build/<project>/<repository>/<arch>/<package>/_buildinfo
    - GET /build/<project>/<repository>/<arch>/_builddepinfo
    - GET /build/<project>/<repository>/_buildconfig
- Search
  - GET /search/project
  - GET /search/project/id
  - GET /search/package
  - GET /search/package/id
  - GET /search/published/binary/id
  - GET /search/published/pattern/id
  - GET /search/channel/binary
  - GET /search/channel/binary/id
  - GET /search/released/binary
  - GET /search/released/binary/id
  - GET /search/request
  - GET /search/issue
  - GET /search/owner
  - GET /search/missing_owner
- Published binary package tree
  - GET /published
  - GET /published/<project>
  - GET /published/<project>/<repository>
  - GET /published/<project>/<repository>/<arch>
  - GET /published/<project>/<repository>/<arch>/<binary>
  - GET /published/<project>/<repository>/<arch>/<binary>?view=ymp
- Tags
  - GET /source/<project>/_tags
  - GET /source/<project>/<package>/_tags
  - GET /tag/<tag>/_projects
  - GET /tag/<tag>/_packages
  - GET /tag/<tag>/_all
  - GET /user/<user>/tags/_projects
  - GET /user/<user>/tags/_packages
  - GET /user/<user>/tags/_tagcloud
  - GET /tag/_tagcloud
  - GET user/<user>/tags/<project>
  - PUT user/<user>/tags/<project>
  - GET user/<user>/tags/<project>/<package>
  - PUT user/<user>/tags/<project>/<package>
- Build Results (Legacy)
  - Build Results
    - GET /result/<project>/<platform>/result
    - GET /result/<project>/<platform>/<package>/result
    - GET /result/<project>/<platform>/<package>/<arch>/log
- Statistics
  - GET /statistics/latest_added?limit=<limit>
  - GET /statistics/added_timestamp/<project>/<package>
  - GET /statistics/latest_updated?limit=<limit>
  - GET /statistics/updated_timestamp/<project>/<package>
  - GET /statistics/activity/<project>/<package>
  - GET /statistics/most_active?type=<type>&limit=<limit>
  - GET /statistics/highest_rated?limit=<limit>
  - GET /statistics/rating/<project>/<package>
  - PUT /statistics/rating/<project>/<package>
  - GET /statistics/download_counter?limit=<limit>
  - GET /statistics/download_counter?group_by=<group_by>&limit=<limit>
  - PUT /statistics/redirect_stats
  - GET /statistics/newest_stats
- Status Messages
  - GET /status_message/?limit=<limit>
  - PUT /status_message/
- Messages (for projects/packages)
  - GET /message/<id>
  - GET /message/?limit=<limit>
  - GET /message/?project=<project>
  - GET /message/?project=<project>&package=<package>
  - PUT /message/?project=<project>&package=<package>

## About

GET /about

Get information about API.

Result: Example Schema

## Architectures

GET /architectures

Get a list of all known architectures known to OBS in general.
This is not the list of architectures provided by this instance, go
to /configuration for this

Result: Example

## Issue Trackers

GET /issue_trackers

Get the list of available issue trackers

Result: Example Schema

GET /issue_trackers/<name>

Arguments:

- name

Read issue tracker data.

Result: Example Schema

PUT /issue_tracker/<name>

Arguments:

- name

Update issue tracker data.

Result: Example Schema

POST /issue_tracker/<name>

Arguments:

- name

Create new issue tracker.

Result: Example Schema

DELETE /issue_tracker/<name>

Arguments:

- name

Delete issue tracker.

Result: Example Schema

GET /issue_trackers/show_url_for

issue: attribute used for issue search (example: 'bnc#123456')

## Distribution List

GET /distributions

Get the list of base distributions hosted on this OBS instance

Result: Example Schema

PUT /distributions

Write the list of base distributions hosted on this OBS instance

Result: Example Schema

GET /distributions/<distribution_id>

Arguments:

- distribution_id

Get data of one base distributions hosted on this OBS instance

Result: Example Schema

POST /distributions/<distribution_id>

Arguments:

- distribution_id

Modifies one base distribution entry. Distro must be hosted on the OBS instance

Result: Example Schema

GET /distributions/include_remotes

Get the list of base distributions hosted on this OBS instance and on all used remote instances

Result: Example Schema

## User data

GET /person/<userid>

Arguments:

- userid - Id of user

Read user data.

Result: Example Schema

PUT /person/<userid>

Arguments:

- userid - Id of user

Write user data.

Body: Example Schema

Result: Example Schema

POST /person?cmd=register

Can be used to register a new user, if OBS instance is allowing this.

POST /person/<userid>

Arguments:

- userid - Id of user

cmd=change_password to post the new password in the request body. Just the first line gets used.

Body: password

Result: Example Schema

cmd: change_password

GET /person/<userid>/token

Arguments:

- userid - Id of user

Lists all authentification token for a user

Result: tokenlist

POST /person/<userid>/token

Arguments:

- userid - Id of user

Create a new authentification token for this user. It may be limited for a specific package
via optional project&package parameters.

cmd: create
project: create a token for a specific project
package: create a token for a specific package

Result: Example Schema

DELETE /person/<userid>/token/<id>

Arguments:

- userid - Id of user
- id

Delete a specific authentification token. The <id> is listed in GET call.

Result: Example Schema

## Group data

GET /group

List available groups

Result: Example Schema

login: List available groups of this user.

GET /group/<group title>

Arguments:

- group title

Read group data.

Result: Example Schema

PUT /group/<group title>

Arguments:

- group title

Write group data.

Body: Example Schema

Result: Example Schema

POST /group/<group title>

Arguments:

- group title

Modify group data.

Multiple commands on processing group.
add_user: add a user to a group
remove_user: remove a user from a group
set_email: set email adress of group.

userid: user login name, required for add_user and remove_user command
email: email address for set_email command. email of group gets removed if not defined

Result: Example Schema

DELETE /group/<group title>

Arguments:

- group title

Delete a group.

Result: Example Schema

## Sources

### Projects

GET /source/

Read list of projects.

Result: Example Schema

deleted: show deleted projects instead of existing

POST /source

Commands on processing sources globally. Possible commands are
branch: branch a set of packages based on attributes or on existing request
createmaintenanceincident: create mainatenance incident projects based on attribute search

linkrev: linked revision, optional (for linkrev=base)
attribute: attribute used for package search, default is OBS:Maintained
update_project_attribute: attribute name used to find out possible existing update projects of a package
request: branch by request, branch all packages in actions of request for superseding it
noaccess: the new created project will be read protected
target_project: project which will get used or created

GET /source/<project>/_meta

Arguments:

- project

Read project meta file.

rev: revision, mandatory

Result: Example Schema

PUT /source/<project>/_meta

Arguments:

- project

Write project meta file.

comment: comment, optional

Body: Example Schema

Result: Example Schema

DELETE /source/<project>

Arguments:

- project

Deletes specified project. All packages of this project are deleted as if a
DELETE request were issued for each package.

force: If force = 1, the project is deleted even if repositories of other
projects include a path to a repository from this project. The path
in the other repository is replaced by one pointing to 'deleted/standard',
preventing the build and publishing of the other repository.
comment: comment, optional

Result: Example Schema

GET /source/<project>/_attribute/<attribute>

Arguments:

- project
- attribute

Get all attributes or a specific one

Body: attribute

POST /source/<project>/_attribute/<attribute>

Arguments:

- project
- attribute

Modifies a specific attribute as in body

comment: comment, optional

Result: Example Schema

DELETE /source/<project>/_attribute/<attribute>

Arguments:

- project
- attribute

Removes a specific attribute

comment: comment, optional

Result: Example Schema

GET /source/<project>/_config

Arguments:

- project

Read project configuration

rev: revision, mandatory

Result: configuration as text/plain

PUT /source/<project>/_config

Arguments:

- project

Change project configuration

comment: comment, optional

Result: Example Schema

GET /source/<project>/_pattern

Arguments:

- project

Get list of all patterns set up for this project

Result: Schema

GET /source/<project>/_pattern/<patternfile>

Arguments:

- project
- patternfile

Get pattern

Result: Schema

PUT /source/<project>/_pattern/<patternfile>

Arguments:

- project
- patternfile

Write pattern

Body: Schema

Result: Example Schema

DELETE /source/<project>/_pattern/<patternfile>

Arguments:

- project
- patternfile

Remove pattern

Result: Example Schema

GET /source/<project>/_pubkey

Arguments:

- project

Get project GPG key. If the project has no own key (default), it uses
the first available one in the namespace hierarchy, ending at the global
buildservice key.

Result: gpgkey

DELETE /source/<project>/_pubkey

Arguments:

- project

Removes the current gpg key. Has no effect if no key is set.

Result: Example Schema

POST /source/<project>

Arguments:

- project

Multiple commands on processing sources in package. Possible commands are
createkey: Generate a new gpg key. If the project already has an own gpg key, the old key is discarded.
extendkey: Extend the expiration date of gpg keys.
undelete: undelete the project and all packages existing when the project got removed.
showlinked: List all projects linking to this one
copy: copy the entire project
move: ADMIN ONLY. schedulers need to be stopped. move all sources and binaries around from oproject.
createmaintenanceincident: create a single mainatenance incident project as sub project
createpatchinfo: create a new patchinfo package collecting all mentioned issues in sources
addchannels: add channel packages and repositories for matching packages in project
modifychannels: modify existing channels by specified mode
set_flag: change a defined flag, requires at least flag and status parameters
remove_flag: remove a defined flag, requires at least flag and status parameters
lock: lock a project
unlock: unlock a locked project
release: release sources and binaries according to release target specification

noaccess: the new created project will be read protected
repository: set_flag for given repository or release just this repository (optional)
arch: set_flag for given arch (optional)
flag: modify this flag (build/publish/..) for set_flag command
status: enable or disable for set_flag command
comment: description for the history
# for modifychannels and addchannels command only:
mode: how to deal with disabled channels: add_disabled(default), skip_disabled, enable_all
# for copy command only:
oproject: origin project name (required)
resign: resign all binaries with new target project key
makeolder: make a split, the source is bumped by two numbers and target by one
withhistory: copies sources with history on copy command
withbinaries: copies also binaries on copy command
noservice: do not run source services
setrelease: define a specific release tag when used with "release" command. Setting it to "-" strips
the release string. Note: this modifies only the filename.

### Packages

GET /source/<project>

Arguments:

- project

Read list of packages.

Result: Example Schema

deleted: show deleted package instead of existing
expand: include also packages from linked projects
view: issues, can be used to show all tracked issues for all packages in project
productlist, shows all containing products, unifies result when used with expand
verboseproductlist, same as productlist, but with detailed information about the product

GET /source/<project>/<package>

Arguments:

- project
- package

Package source listing

rev: revision of new package, optional
linkrev: linked revision, optional
emptylink: bool, , optional
expand: bool, expand links, optional
meta: bool, switch to meta files, optional
view: The "info" view will show data like source version, md5sums and build description files. May be used together with parse, arch or repository parameter, optional
"issues" can be used to show all tracked issues for all packages in project, optional
"products" show all products of a package (works only on "_product" packages)
extension: filter for file extension, optional
lastworking: bool, show sources of last mergeable sources in case of conflicting changes, optional
withlinked: bool, show all used package containers (in case of multiple link indirections) in linkinfo information, optional
deleted: bool, show content of deleted package instance
parse: bool, for view=info: take build description into account, optional
arch: string, for view=info: parse buildinfo for this architecture, optinal
repository: string, for view=info: parse buildinfo for this repository, optinal
product: string, limit the product view to a given product

Result: Example Schema

GET /source/<project>/<package>/_meta

Arguments:

- project
- package

Read project meta data.

rev: revision of new package, optional

Result: Example Schema

PUT /source/<project>/<package>/_meta

Arguments:

- project
- package

Write project meta data. Writing of the project meta data commits the packages
contained in the project to the build backend.

comment: comment, optional

Body: Example Schema

Result: Example Schema

DELETE /source/<project>/<package>

Arguments:

- project
- package

Deletes specified package including all source files

comment: comment, optional

Result: Example Schema

GET /source/<project>/<package>/_attribute/<attribute>

Arguments:

- project
- package
- attribute

Get all attributes or a specific one

Body: attribute

POST /source/<project>/<package>/_attribute/<attribute>

Arguments:

- project
- package
- attribute

Modifies a specific attribute as in body

comment: comment, optional

Result: Example Schema

DELETE /source/<project>/<package>/_attribute/<attribute>

Arguments:

- project
- package
- attribute

Removes a specific attribute

comment: comment, optional

Result: Example Schema

GET /source/<project>/<package>/_history

Arguments:

- project
- package

Get package commit history

Result: Example

POST /source/<project>/<package>?cmd=showlinked

Arguments:

- project
- package

List all package instances linking to this one.

Result: package list

POST /source/<project>/<package>?cmd=diff

Arguments:

- project
- package

Create a source diff

rev: revision of new package, optional
oproject: old project, optional
opackage: old package, optional
orev: old revision, optional

Result: diff as text/plain

POST /source/<project>/<package>?cmd=instantiate

Arguments:

- project
- package

Instantiate a package container, which is available via project links only so far.

makeoriginolder: optional, can be used to modify source and target to guarantee that new version
stay older also on future updates in older code stream

Result: Example Schema

POST /source/<project>/<package>?cmd=release

Arguments:

- project
- package

Releases sources and binaries of that package. This requires a set
release target in the repository definitions of <project>. Also the
trigger must be set to "manual"

comment: description for the history
repository: limit the release to the specified repository
target_repository: specify the target repository name (together with target_project)
target_project: overwrites the target definition from project meta
(repository and target_repository parameter required as well)

Result: Example Schema

POST /source/<project>/<package>?cmd=unlock

Arguments:

- project
- package

Unlocks a locked package

comment: description for the history

Result: Example Schema

POST /source/<project>/<package>?cmd=branch

Arguments:

- project
- package

Create a source link from a package of an existing project to a
new subproject of the requesters home project.
The default target is home:<user>:branches:<project>/<package>
A possible defined devel project in the package meta data gets ignored.

ignoredevel: bool, optional
target_project: target project name, optional
target_package: target package name, optional
noaccess: the new created project will be read protected, bool, optional
missingok: the target package does not exist
newinstance: the target package exists only via project links, but the link should point to given project
add_repositories: bool, optional, adds repositories base on source project (default for new projects)
update_path_elements: bool, optional, update all path elements if needed (used repositories depend on each other)
extend_package_names: bool, optional, extends package and repository names to allow multiple instances of same package
add_repositories_rebuild: use defined rebuild policy for new repos
add_repositories_block: use defined block policy for new repos

Result: Example Schema

POST /source/<project>/<package>?cmd=set_flag

Arguments:

- project
- package

Modify or set a defined flag for package

repository: set_flag for given repository (optional)
arch: set_flag for given arch (optional)
flag: modify this flag (build/publish/..) for set_flag command
status: enable or disable for set_flag command

Result: Example Schema

POST /source/<project>/<package>?cmd=createSpecFileTemplate

Arguments:

- project
- package

Create template for RPM SPEC file. Returns an error, if the SPEC file already
exists.

Result: Example Schema

POST /source/<project>/<package>?cmd=commit

Arguments:

- project
- package

Commits package changes to buildservice

rev: revision, mandatory
comment: comment, optional

Result: Example Schema

POST /source/<project>/<package>?cmd=collectbuildenv

Arguments:

- project
- package

Creates _buildenv files based on origin package builds. This can be used
to re-use exact older build enviroment even when further new binary packages
got added. For example to re-build an old maintenance update in the same way.

oproject: Origin project to copy from (required)
opackage: Origin package to copy from (required)
comment: Optional comment by the user

Result: Example Schema

POST /source/<project>/<package>?cmd=importchannel

Arguments:

- project
- package

Import a kiwi channel file for OBS. Project names will be set
to update projects if defined.

target_project: optional target repository to set
target_repository: optional target repository to set

Result: Example Schema

POST /source/<project>/<package>?deleteuploadrev

Arguments:

- project
- package

Removes all changes made to the upload revision and reverts to last revision

none

Result: Example Schema

### Source files

GET /source/<project>/<package>

Arguments:

- project
- package

Get directory listing of all source files in the package

rev: package source revision, optional
linkrev: linked revision, optional
expand: expand links, optional
meta: switch to meta files
lastworking: auto detect last working link revision, optional
view: The "cpio" view will stream all files as cpio, optional
extension: filter for file extension, optional

GET /source/<project>/<package>/<filename>

Arguments:

- project
- package
- filename - File name

Read source file.

Result: Content of file

meta: switch to meta files

PUT /source/<project>/<package>/<filename>

Arguments:

- project
- package
- filename - File name

Write source file.

rev: if set to 'upload', multiple files can be uploaded one by one in one commit, before
finishing the commit with cmd=commit (see below), optional
comment: comment, optional
keeplink: bool, optional
meta: switch to meta files

Body: Content of file

Result: Example Schema

DELETE /source/<project>/<package>/<filename>

Arguments:

- project
- package
- filename - File name

Delete source file.

Result: Example Schema

meta: switch to meta files

POST /source/<project>/<package>

Arguments:

- project
- package

Multiple commands on processing sources in package. Possible commands are
diff: for server side diff
linkdiff: for server side diff of a linked or branched package
servicediff: shows the changes of the service run
commit: commit files in upload revision
commitfilelist: commit defined files in upload revision
deleteuploadrev: delete all uploaded sources which are not committed yet
copy: copy package sources from another package
undelete: undelete the package
unlock: unlock a package with lock enabled. A comment is required.
release: release sources and binaries according to release target specification
branch: branch a package into another one
linktobranch: convert a plain source link into a full branch
enablechannel: adds repositories and enable this channel package
updatepatchinfo: update _patchinfo file, esp. the issues list
remove_flag: remove a specific flag from meta (flag must be defined, optionally arch and repository)
set_flag: remove a specific flag from meta (flag must be defined, optionally arch and repository)
showlinked: show all source packages linking to this one
deleteuploadrev: delete all uploaded, but not yet commited files.
rebuild: rebuild all builds
getprojectservices: list all service defined in project spaces defined for this package.
runservice: trigger run of defined services in _service file
waitservice: returns when all services have finished, code 200 when service run was successful
mergeservice: drops the _service file and commits all server side generated files
wipe: wipe all build results of this package

rev: package source revision, optional
linkrev: linked revision, optional
orev: origin package source revision as defined in opackage/project, optional
olinkrev: origin linked revision, optional
oproject: origin project, used as base project
opackage: origin package, used as base package
requestid: log the requestid in source history, optional (copy and commitfilelist only)
expand: expand links, optional
keeplink: keep link on source commit, optional
repairlink: repair link on source commit, optional
dontupdatesource: Do not update origin package, optional (copy only)
noservice: do not run source services
comment: comment for history, optional
meta: switch to meta files
arch: architecture when using flag modifing command
repository: repository when using flag modifing command
view: may be "xml" for structured answered (for diff commands)
withissues: set to get issues parsed from changelogs (for diff commands)
onlyissues: used to limit to issues (for diff commands)
setrelease: define a specific release tag when used with "release" command. Setting it to "-" strips
the release string.

GET /source/<project>/<package>/<binary>/_attribute/<attribute>

Arguments:

- project
- package
- binary
- attribute

Get all attributes or a specific one

Body: attribute

POST /source/<project>/<package>/<binary>/_attribute/<attribute>

Arguments:

- project
- package
- binary
- attribute

Modifies a specific attribute as in body

comment: comment, optional

Result: Example Schema

DELETE /source/<project>/<package>/<binary>/_attribute/<attribute>

Arguments:

- project
- package
- binary
- attribute

Removes a specific attribute

comment: comment, optional

Result: Example Schema

## Requests

GET /request

Get a list of requests. When using the "view=collection" you need also to filter
either by user, project or package.

view: collection, return a collection of requests instead of directory listing
user: filter for given user, includes all target projects and packages where
the user is maintainer and also open review requests
project: limit to result to defined target project or review requests
package: limit to result to defined target package or review requests
states: filter for given request state, multiple matches can be added as comma seperated list (eg states=new,review)
types: filter for given action types (comma seperated)
roles: filter for given roles (creator, maintainer, reviewer, source or target)
withhistory: includes the request history in result
withfullhistory: includes the request and review history in result

Result: collection

GET /request/<id>

Arguments:

- id

Get a request

withhistory: includes the request history in result
withfullhistory: includes the request and review history in result

Result: Example Schema

POST /request

Create a new request

Result: Example Schema

Commands on processing requests
create: to crfeate a new request

addrevision: ask the server to add revisions of current sources to the request

PUT /request/<id>

Arguments:

- id

Modify a request. NOTE: Only admins can change all parts of a request.

Result: Example Schema

POST /request/<id>?cmd=diff

Arguments:

- id

Shows the diff of all affected packages.

Result: diff as text/plain

POST /request/<id>

Arguments:

- id

Modify a request

Result: Example Schema

Commands on processing requests
addreview: Adds a review to a request
assignreview: Adds a review for a user and accepts it for the used group
changestate: Modifies the state of a request
changereviewstate: Modifies the state of a review inside a request
setpriority: Modifies the priority of a requst
setincident: Change the target incident for maintenance_incident actions
setacceptat: Set or modify the accept_at time. Either specified by time parameter or now.

newstate: Define the new state
priority: Define the new priority
by_user: Specify the user of the new review
by_group: Specify the group of the new review
by_project: Specify the project of the new review
by_package: Specify the user of the new review
incident: Specifiy inicdent number for setincident
time: Specifiy time for setacceptat

## Attribute definition api

GET /attribute/

List all attribute namespaces

Result: Example Schema

GET /attribute/<namespace>/

Arguments:

- namespace

List all attributes under given namespace

Result: Example Schema

GET /attribute/<namespace>/_meta

Arguments:

- namespace

shows namespace setup

Result: Example Schema

DELETE /attribute/<namespace>/_meta

Arguments:

- namespace

Delete a attribute namespace and all attributes below

Result: Example Schema

PUT /attribute/<namespace>/_meta

Arguments:

- namespace

change attribute namespace meta

Body: attribute_namespace_meta_data

Result: Example Schema

GET /attribute/<namespace>/<name>/_meta

Arguments:

- namespace
- name

shows attribute setup

Result: attribute_meta

DELETE /attribute/<namespace>/<name>/_meta

Arguments:

- namespace
- name

Delete a attribute and all its values in projects or packages

Result: Example Schema

PUT /attribute/<namespace>/<name>/_meta

Arguments:

- namespace
- name

change attribute meta

Body: attribute_meta_data

Result: Example Schema

## Comments api

GET /comments/request/:id

GET /comments/project/:name

GET /comments/package/:project/:pname

Get all comments for the object

Result: Example Schema

POST /comments/request/:id

POST /comments/project/:name

POST /comments/package/:project/:pname

Create a comment for the object

Result: Example Schema

DELETE /comment/:id

Delete a comment specified by the comment id

Result: Example Schema

## Build Results

GET /build/

List all repositories

Result: Example Schema

GET /build/_workerstatus

Lists all running jobs, waiting jobs, status of the backend services and general statistics.

Result: Example

GET /build/<project>

Arguments:

- project

List all repositories of the specified project

Result: Example Schema

GET /build/<project>/<repository>

Arguments:

- project
- repository

List all architectures of the specified project repository

Result: Example Schema

GET /build/<project>/<repository/<arch>

Arguments:

- project
- repository/<arch

List all packages used in this project repository for given architecture.

Result: Example Schema

### Binaries

GET /build/<project>/<repository>/<arch>/<package>

Arguments:

- project
- repository
- arch
- package

Get list of binaries built by the sources of the given package

Result: binarylist

GET /build/<project>/<repository>/<arch>/<package>/<binaryname>

Arguments:

- project
- repository
- arch
- package
- binaryname

Get single binary from build results of given package

Result: binary file

GET /build/<project>/<repository>/<arch>/<package>/<binaryname>?view=fileinfo

Arguments:

- project
- repository
- arch
- package
- binaryname

GET /build/<project>/<repository>/<arch>/<package>/<binaryname>?view=fileinfo_ext

Arguments:

- project
- repository
- arch
- package
- binaryname

Get information about the binary from build results of given package

Result: fileinfo

GET /build/<project>/<repository>/<arch>/_builddepinfo

Arguments:

- project
- repository
- arch

POST /build/<project>/<repository>/<arch>/_builddepinfo

Arguments:

- project
- repository
- arch

Shows all build dependencies of one or more packages, a change in any of them will
trigger a build.
A changed dependency can be posted to let the server recalculate the order
including the local dependency changes.

package=<name> filter package container, can be used multiple times
view=pkgnames show package names instead of binary names
view=revpkgnames show which packages will be triggered if the package is changed
view=order sort packages ordered by dependencies

Result: build dependencies

GET /build/<project>/<repository>/<arch>/_jobhistory?package=<package>&code=succeeded&limit=10

Arguments:

- project
- repository
- arch

Get the build log of all finished builds in this repository, including
time and trigger reason. Optional filtering for one ore more packages/codes is
possible.

Result: jobhistory

GET /build/<project>/<repository>/<arch>/_repository

Arguments:

- project
- repository
- arch

Get list of binaries in given repository (binaries produced by all packages
of the project)

Result: binarylist

POST /build/<project>/<repository>/<arch>/_repository?match=

Arguments:

- project
- repository
- arch

Uploads binaries to a given repository. ADMIN ONLY

Result: status

PUT /build/<project>/<repository>/<arch>/_repository/<file>

Arguments:

- project
- repository
- arch
- file

Uploads binaries into the repository. ADMIN ONLY.

Result: status

GET /build/<project>/<repository>/<arch>/_repository/<binaryname>

Arguments:

- project
- repository
- arch
- binaryname

Get single binary from the given repository

Result: binary file

### Status

GET /build/<project>/_result

Arguments:

- project

Return build results for the packages, architectures and repositories
specified by the parameters. If no parameters are given, all results for the
project are returned.

The view parameter specifies which sections are included in the results.
view=summary includes the summary of the status values. view=status includes
detailed status information. view=binarylist includes the list of generated
binary files. If no view parameter is given, view=status is assumed. To
combine views the parameter can be given multiple times.

package: package name, optional, multiple
arch: architecture, optional, multiple
repository: name of repository, optional, multiple
view: summary | status | binarylist
lastbuild: bool, optional

Result: Example

GET /build/<project>/<repository>/<arch>/<package>/_history

Arguments:

- project
- repository
- arch
- package

Get build history

Result: Example Schema

GET /build/<project>/<repository>/<arch>/<package>/_reason

Arguments:

- project
- repository
- arch
- package

Detailed reason, why the last build got triggered. This may be
caused by a source change, meta change (binary package below changed) or
release number sync.
A user triggered build will show up as source change.

Result: buildreason

GET /build/<project>/<repository>/<arch>/<package>/_jobstatus

Arguments:

- project
- repository
- arch
- package

Get build status of a current running build job or empty result if no job is running.

Result: jobstatus

GET /build/<project>/<repository>/<arch>/<package>/_status

Arguments:

- project
- repository
- arch
- package

Get build status of the specified project/package/repo/arch combination

Result: buildstatus

GET /build/<project>/<repository>/<arch>/<package>/_log

Arguments:

- project
- repository
- arch
- package

Get build log.

nostream: do not hang if the build is currently running
last: show log from last finished build
start: start at a given number of bytes
end: stop after the given number of bytes
view: special view instead of plain logfile. "entry" shows the size and mtime of logfile.

Result: Build log as text file.

### Control

POST /build/<project>?cmd=rebuild

Arguments:

- project

Triggers package rebuild for the repositories/architectures of the package
specified by the parameters. If no parameters are given, all packages of the
project are completely rebuilt.

Possible values for the code parameter are:

succeeded - build succeeded
failed - build failed
disabled - build is disabled in package config
excluded - build is excluded in spec file
scheduled - package is ready to be built
building - package is building on a worker
broken - package source is bad (i.e. no specfile)
unresolvable - build needs unavailable binary packages

package: package name, optional, multiple
arch: architecture, optional, multiple
repository: name of repository, optional, multiple
code: build status code, optional, multiple

Result: Example Schema

POST /build/<project>?cmd=abortbuild

Arguments:

- project

Kill all running builds, marking them as failed

see cmd=rebuild

POST /build/<project>?cmd=restartbuild

Arguments:

- project

Restart all running builds

see cmd=rebuild

POST /build/<project>?cmd=wipe

Arguments:

- project

Delete all binary packages from the packages

see cmd=rebuild

### Local Build

GET /build/<project>/<repository>/<arch>/<package>/_buildinfo

Arguments:

- project
- repository
- arch
- package

Get build information for local building

Result: buildinfo

POST /build/<project>/<repository>/<arch>/<package>/_buildinfo

Arguments:

- project
- repository
- arch
- package

Get build info for local building using the POSTed specfile.
<package> can be "_repository", if the designated package does not yet exist
on the server. Usefull for local build test before committing the initial package.

Body: specfile

Result: buildinfo

### Trigger area

POST /trigger/runservice

This call needs a token created via "createtoken" command to identify user and
package which shall be updated via a source service. The token must be delivered
as HTTP header:
Authorization: Token <TOKEN_STRING>

project: To be used together with "package" to identify the object.
package:

Result: Example Schema

### Repository Information

GET /build/<project>/<repository>/<arch>/_repository

Arguments:

- project
- repository
- arch

Returns list of binaries contained in the specified repository

Result: binarylist

GET /build/<project>/<repository>/<arch>/_repository/<binaryname>

Arguments:

- project
- repository
- arch
- binaryname

Returns binary

Result: binary file

GET /build/<project>/<repository>/<arch>/<package>

Arguments:

- project
- repository
- arch
- package

Returns list of binaries contained in the specified repository

Result: binarylist

GET /build/<project>/<repository>/<arch>/<package>/_buildinfo

Arguments:

- project
- repository
- arch
- package

Build info according to the committed sources

Result: buildinfo

POST /build/<project>/<repository>/<arch>/<package>/_buildinfo

Arguments:

- project
- repository
- arch
- package

Build info according to the uploaded sources

Result: buildinfo

GET /build/<project>/<repository>/<arch>/_builddepinfo

Arguments:

- project
- repository
- arch

Returns dependency information of packages in the specified repository. One or more
packages can be specified with the 'package' parameter. By default dependencies for
all packages are returned.

Result: builddepinfo

GET /build/<project>/<repository>/_buildconfig

Arguments:

- project
- repository

Build configuration for this repository, all base package requirements, mappings and macros.

## Search

GET /search/project

Searches for project metadata using xpath. A xpath predicate has to be
specified using the match parameter. The predicate will be used in this
expression: /project[<match>]. Only complete meta files will be returned.

match: xpath predicate, mandatory

Result: collection

GET /search/project/id

Searches for project metadata analogous to /search/project, only the root
element is returned without any children.

match: xpath predicate, mandatory

Result: collection

GET /search/package

Searches for package metadata using xpath. A xpath predicate has to be
specified using the match parameter. The predicate will be used in this
expression: /package[<match>]. Only complete meta files will be returned.

match: xpath predicate, mandatory

Result: collection

GET /search/package/id

Searches for package metadata analogous to /search/package, only the root
element is returned without any children.

match: xpath predicate, mandatory

Result: collection

GET /search/published/binary/id

Search for currenlty available binaries in the publish area.

match: xpath predicate, mandatory

Result: collection

GET /search/published/pattern/id

Search for published patterns

match: xpath predicate, mandatory

Result: collection

GET /search/channel/binary

Search for packages, sources or binaries which are referenced in channel files.
Unlike the released/binary search this works already after setting up a channel
even without releasing files.

match: xpath predicate, mandatory

Result: collection

GET /search/channel/binary/id

Search for packages, sources or binaries which are referenced in channel files.
Unlike the released/binary search this works already after setting up a channel
even without releasing files.

This is the short version without full release data information.

match: xpath predicate, mandatory

Result: collection

GET /search/released/binary

Search for binaries which got released. This works only for binaries published
via release mechanism. It also includes binaries which got removed again.

It is recommended to specify at least the @name binary package name or the
@disturl.

match: xpath predicate, mandatory

Result: collection

GET /search/released/binary/id

Search for binaries which got released. This works only for binaries published
via release mechanism. It also includes binaries which got removed again.

This is the short version without full release data information.

match: xpath predicate, mandatory

Result: collection

GET /search/request

Searches for requests using xpath. A xpath predicate has to be
specified using the match parameter. The predicate will be used in this
expression: /request[<match>]. Only complete meta files will be returned.

match: xpath predicate, mandatory
withhistory: includes the request history in result
withfullhistory: includes the request and review history in result

Result: collection

GET /search/issue

Searches for issue metadata using xpath. A xpath predicate has to be
specified using the match parameter. The predicate will be used in this
expression: /issue[<match>]. Only complete issue information will be returned.

match: xpath predicate, mandatory

Result: collection

GET /search/owner

Search for default responsible person or group.
Using the binary parameter the lookup happens via a build binary name
Using user or group all sources where they are responsible are for are listed.
Either binary, user or group parameter is required.

binary: specify the binary package to search for
user: specify a user login name to list his packages
group: specify a group title name to list their packages

devel: true/false: include devel package definitions?
limit: limit the number of results. Default is "1" single result. Use 0 for all hits, -1 for deepest match.
This works only when used together with binary search otherwise always all items get returned.
project: specify project to search in
filter: Comma seperated list of role names to be taken into account
attribute: specify attribute which is marking the default project(s). Default is OBS:OwnerRootProject

Result: collection

GET /search/missing_owner

Search for missing definitions of specific role.
No parameter is required by default

devel: true/false: include devel package definitions?
limit: limit the number of results.
project: specify project to search in
filter: Comma seperated list of role names to be taken into account
attribute: specify attribute which is marking the default project(s). Default is OBS:OwnerRootProject

Result: collection

## Published binary package tree

GET /published

List of published projects

Result: Example Schema

GET /published/<project>

Arguments:

- project

List of repositories of published projects

Result: Example Schema

GET /published/<project>/<repository>

Arguments:

- project
- repository

List of published repositories for the given project/repo

Result: Example Schema

GET /published/<project>/<repository>/<arch>

Arguments:

- project
- repository
- arch

List of published binaries for the given project/repo/arch

Result: Example Schema

GET /published/<project>/<repository>/<arch>/<binary>

Arguments:

- project
- repository
- arch
- binary

Download published binary
NOTE: use this only if you absolutely have to as it doesn't use
the redirector

Result: binary

GET /published/<project>/<repository>/<arch>/<binary>?view=ymp

Arguments:

- project
- repository
- arch
- binary

Generate an ymp pattern that includes the needed repositories to install the
given binary

Result: ymp

## Tags

GET /source/<project>/_tags

Arguments:

- project

Get tags by project.

Result: Example Schema

GET /source/<project>/<package>/_tags

Arguments:

- project
- package

Get tags by package.

Result: Example Schema

GET /tag/<tag>/_projects

Arguments:

- tag

Get projects by tag(s).
For selection by more than one tag use TagA::TagB for example.

Result: Example Schema

GET /tag/<tag>/_packages

Arguments:

- tag

Get packages by tag.

Result: Example Schema

GET /tag/<tag>/_all

Arguments:

- tag

Get projects and packages by tag.

Result: Example Schema

GET /user/<user>/tags/_projects

Arguments:

- user

Get all projects including tags assigned by the user

Result: Example Schema

GET /user/<user>/tags/_packages

Arguments:

- user

Get all packages including tags assigned by the user

Result: Example Schema

GET /user/<user>/tags/_tagcloud

Arguments:

- user

distribution=linear | logarithmic | raw
steps=[1..100]
limit=[0..] (default = 100, 0 = no limit)

Get a tag cloud from the tags used by the user.

Result: Example Schema

GET /tag/_tagcloud

distribution=linear | logarithmic | raw
steps=[1..100]
limit=[0..] (default = 100, 0 = no limit)

Get a tag cloud including all tags.

Result: Example Schema

GET user/<user>/tags/<project>

Arguments:

- user
- project

Get tags by user and project.

Result: Example Schema

PUT user/<user>/tags/<project>

Arguments:

- user
- project

Write tags by user and project.

Body: Example Schema

Result: Example Schema

GET user/<user>/tags/<project>/<package>

Arguments:

- user
- project
- package

Get tags by user and package.

PUT user/<user>/tags/<project>/<package>

Arguments:

- user
- project
- package

Write tags by user and package.

Body: Example Schema

Result: Example Schema

## Build Results (Legacy)

This section describes the obsolete API for build results. It will be replaced
by the API available under /build.

### Build Results

GET /result/<project>/<platform>/result

Arguments:

- project
- platform

Read project summary result.

Result: projectresult

GET /result/<project>/<platform>/<package>/result

Arguments:

- project
- platform
- package

Read package result.

Result: Example Schema

GET /result/<project>/<platform>/<package>/<arch>/log

Arguments:

- project
- platform
- package
- arch

Read build log.

Result: Build log as text file.

## Statistics

GET /statistics/latest_added?limit=<limit>

Get a list of packages and projects (mixed) latest added to the build
service. All entries are sorted by creation time.

Result: Example Schema

GET /statistics/added_timestamp/<project>/<package>

Arguments:

- project
- package

Get timestamp when project or package was added to the build service.

Result: Example Schema

GET /statistics/latest_updated?limit=<limit>

Get a list of packages and project that were last updated. All entries are
sorted by the update timestamp.

Result: Example Schema

GET /statistics/updated_timestamp/<project>/<package>

Arguments:

- project
- package

Get timestamp when project or package was last updated.

Result: Example Schema

GET /statistics/activity/<project>/<package>

Arguments:

- project
- package

Get activity in % of project or package.

Result: Example Schema

GET /statistics/most_active?type=<type>&limit=<limit>

Get list of most active packages (type=packages) or projects (type=projects).
Also returns count of updates since package was created when type=packages.
Also returns count of packages that are in this project when type=projects.

Result: Example Schema

GET /statistics/highest_rated?limit=<limit>

Get list of highest rated projects and packages. Results are sorted by score.
Only items with more than 3 ratings will show up in this list.

Result: Example Schema

GET /statistics/rating/<project>/<package>

Arguments:

- project
- package

Get rating of a specific project or package. Also returns what score the
logged in user gave and how many ratings there are already for the specified
object.

Result: Example Schema

PUT /statistics/rating/<project>/<package>

Arguments:

- project
- package

Rate this project / package.

Result: Example Schema

GET /statistics/download_counter?limit=<limit>

Get download counters for top downloaded files including to which project,
package, repository and architecture they belong.

Result: Example Schema

GET /statistics/download_counter?group_by=<group_by>&limit=<limit>

Get summarized download counters for top downloaded projects, packages,
repositories or architectures (by setting group_by parameter to project,
package, repo or arch) including count of files that belong to the respective
object.

Result: Example Schema

PUT /statistics/redirect_stats

Send download statistics from the openSUSE download redirector to the build
service api, to update the download_counter database.
User needs to have appropriate permissions.

Result: Example Schema

GET /statistics/newest_stats

Get the timestamp of the newest stats in build service. This is useful for the
create_stats_xml.rb script. Using this value it can import only those
statistics that changed from the last import of statistics.
If there are no statistics yet, returns "1970-01-01T01:00:00+01:00"

Result: Example Schema

## Status Messages

GET /status_message/?limit=<limit>

Get a list of status messages.

Result: Example Schema

PUT /status_message/

Send a new status message to the build service. User needs to have
appropriate permissions.

Result: Example

## Messages (for projects/packages)

GET /message/<id>

Arguments:

- id - message id

Get (one) message specified by id.

Result: Example Schema

GET /message/?limit=<limit>

Get a list of messages, independent of project or package.
All entries are ordered by creation time (latest first).

Result: Example Schema

GET /message/?project=<project>

Get a list of messages for this package.
All entries are ordered by creation time (latest first).

Result: Example Schema

GET /message/?project=<project>&package=<package>

Get a list of messages for this package.
All entries are ordered by creation time (latest first).

Result: Example Schema

PUT /message/?project=<project>&package=<package>

Append message to the specified package (or project, if package parameter
is omitted).

Result: Example Schema

## Internal only routes