= Open Build Service API

Version: 2.9

  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

Contents:

== About

GET /about

  Get information about API.

XmlResult: about

== 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, check the
  schedulers element from the /configuration route for this.

XmlResult: architecture list


== Issues

GET /issue_trackers

  Get the list of available issue trackers

XmlResult: issue_trackers

<name>: Issue tracker name

POST /issue_trackers

  Create an issue tracker.

XmlResult: status

GET /issue_trackers/<name>

  Read issue tracker data.

XmlResult: issue_tracker

PUT /issue_trackers/<name>

  Update issue tracker data.

XmlResult: status

DELETE /issue_trackers/<name>

  Delete issue tracker.

XmlBody: none
XmlResult: status

GET /issue_trackers/<tracker_name>/issues/<issue_name>

  Show the issue

XmlResult: issue


== Distribution List

GET /distributions

  Get all the base distributions hosted on this OBS instance

XmlResult: distributions

GET /distributions/<distribution_id>

  Get a base distribution hosted on this OBS instance

XmlResult: distribution

POST /distributions/

  Creates a base distribution

XmlBody: distribution
XmlResult: status

PUT /distributions/<distribution_id>

  Updates a base distribution. Note: Updating distribution from remote is not allowed.

XmlBody: distribution
XmlResult: status

GET /distributions/include_remotes

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

XmlResult: distributions

POST /distributions/bulk_replace

  Replace all the base distributions hosted on this OBS instance

XmlBody: distributions
XmlResult: status

== User data

<userid>: Id of user
<groupid> Id of group


GET /person/<userid>

  Read user data.

XmlResult: user


PUT /person/<userid>

  Write user data.

XmlBody: user
XmlResult: status


POST /person?cmd=register

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


POST /person/<userid>

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

XmlBody: password
XmlResult: status

Parameters:
  cmd: change_password
  cmd: lock             # will lock the user and their home projects
  cmd: delete           # will mark the user as deleted and remove her home projects

GET /person/<userid>/token

  Lists all authentication token for a user

XmlResult: tokenlist

POST /person/<userid>/token

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

  project: together with package, used to create a token for a specific package
  package: together with project, used to create a token for a specific package
  operation: runservice(default), rebuild, release
  scm_token: (Beta/Unstable) SCM token used in OBS workflows to report back the
             workflow status, when the operation is workflow.

XmlResult: status

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

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

XmlBody: none
XmlResult: status


== Group data

GET /group

  List available groups

XmlResult: directory

Parameters:
  login: List available groups of this user.

GET /group/<group title>

  Read group data.

XmlResult: group


PUT /group/<group title>

  Write group data.

XmlBody: user
XmlResult: status


POST /group/<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.

Parameters:
  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

XmlResult: status


DELETE /group/<group title>

  Delete a group.

XmlBody: none
XmlResult: status


== Sources

=== Projects


GET /source/

  Read list of projects.

XmlResult: directory

Parameters:

  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
  orderkiwirepos: sort the repositories inside of a kiwi file according to path relationships
  createmaintenanceincident: create mainatenance incident projects based on attribute search

Parameters:

  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

  Read project meta file.

XmlResult: project


PUT /source/<project>/_meta

  Write project meta file.

  If the project does not exist, create it.

Parameters:

  comment: comment, optional

XmlBody: project

XmlResult: status


DELETE /source/<project>

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

Parameters:
  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

XmlBody: none
XmlResult: status


GET /source/<project>/_project

  List project files

Parameters:

  meta: switch for _meta files, optional
  rev: revision, optional

XmlResult: project directory.xsd


GET /source/<project>/_project/<file>

  Read a project file.

Parameters:

  meta: switch for _meta files, optional
  rev: revision, optional


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

  Get all attributes or a specific one

XmlBody: attribute


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

  Modifies a specific attribute as in body

Parameters:

  comment: comment, optional

XmlResult: status


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

  Removes a specific attribute

Parameters:

  comment: comment, optional

XmlBody: none
XmlResult: status


GET /source/<project>/_config

  Read project configuration

Parameters:

  rev: revision, mandatory

Result: configuration as text/plain


PUT /source/<project>/_config

  Change project configuration

Parameters:

  comment: comment, optional

XmlResult: status


GET /source/<project>/_pattern

  Get list of all patterns set up for this project

XmlResult: pattern


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

  Get pattern

XmlResult: pattern


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

  Write pattern

XmlBody: pattern

XmlResult: status

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

  Remove pattern

XmlBody: none
XmlResult: status


GET /source/<project>/_pubkey

  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

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

XmlBody: none
XmlResult: status


POST /source/<project>?cmd=$COMMAND

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.
  freezelink: create/update a freeze of a project link
  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
  addcontainers: add docker container packages and repositories using the main
tained version of this package
  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

Additional Parameters:
  comment: description for the history
  # for set_flag command only:
  arch: set_flag for given arch (optional)
  flag: modify this flag (build/publish/..) for set_flag command
  repository: set_flag for given repository or release just this repository (optional)
  status: enable or disable for set_flag command
  # 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)
  makeolder: make target older, the source vrev is bumped by two numbers and target by one
  makeoriginolder: make origin older, the source vrev is extended and target is guaranteed to be newer
  noaccess: the new created project will be read protected
  nodelay: disables background copy operation, request will return after the job is finished
  noservice: do not run source services
  resign: resign all binaries with new target project key
  setrelease: define a specific release tag when used with "release" command. Setting it to "-" strips
              the release string. Note: this modifies only the filename.
  withbinaries: copies also binaries on copy command
  withhistory: copies sources with history on copy command

XmlResult: status

=== Packages


GET /source/<project>

  Read list of packages.

XmlResult: package directory.xsd

Parameters:

  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>

  Package source listing

Parameters:

  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)
        "productrepositories" show all repositories used in product definitions (or given product)
  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

XmlResult: directory_filelist directory.xsd


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

  Read project meta data.

Parameters:

  rev: revision of new package, optional

XmlResult: package


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

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

  If the package does not exist, create it.

Parameters:

  comment: comment, optional

XmlBody: package

XmlResult: status


DELETE /source/<project>/<package>

  Deletes specified package including all source files

Parameters:

  comment: comment, optional

XmlBody: none
XmlResult: status


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

  Get all attributes or a specific one

XmlBody: attribute


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

  Modifies a specific attribute as in body

Parameters:

  comment: comment, optional

XmlResult: status


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

  Removes a specific attribute

Parameters:

  comment: comment, optional

XmlBody: none
XmlResult: status



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

  Get package commit history

XmlResult: revisionlist revisionlist.rng



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

  List all package instances linking to this one.

Result: package list


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

  Create a source diff

Parameters:

  rev: revision of new package, optional
  oproject: old project, optional
  opackage: old package, optional
  orev: old revision, optional
  unified: set to 1 to use unified format without looking into archives,
           instead of custom format with showing diff of files inside archives
  expand: set to 1 to expand any link before diffing, optional
  filelimit: integer to limit the diff size by line numbers. built-in default
             is used by default, disable it via 0, optional
  tarlimit: integer to limit the diff size by line numbers. built-in default is
            used by default for tar ball content, disable it via 0, optional
  linkrev: specify a link revision in base package, use linkrev=base to use the
           commit revision, optional
  olinkrev: specify a link revision in origin package, use linkrev=base to use
            the commit revision, optional
  missingok: for diffing against inexisting origin, optional
  meta: diff meta data instead of sources by setting it to 1, optional
  file: limit diff to the given file name, optional
  view: view=xml for structured content, optional
  withissues: includes parsed issue tracker issues and their change state, optional
  onlyissues: no source diff, just the tracker issues and their change state, optional

Result: diff as text/plain


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

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

Parameters:

  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

XmlResult: status


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

  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"

Parameters:
  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)

XmlResult: status


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

  Unlocks a locked package

Parameters:
  comment: description for the history

XmlResult: status


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

  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.

Parameters:
  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 ("transitive", "direct" or "local") or copy it from the source project ("copy")
  add_repositories_block: use defined block policy for new repos

XmlResult: status


POST /source/<project>/<package>?cmd=set_flag
  Modify or set a defined flag for package

Parameters:
  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

XmlResult: status


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

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

XmlResult: status


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

  Commits package changes to buildservice

Parameters:

  rev: revision, mandatory
  comment: comment, optional

XmlResult: status


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

  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.

Parameters:

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

XmlResult: status


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

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

Parameters:

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

XmlResult: status


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

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

Parameters:

  none

XmlResult: status

=== Source files

<filename>: File name


GET /source/<project>/<package>

  Get directory listing of all source files in the package


Parameters:

  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>

  Read source file.

Result: Content of file

Parameters:

  meta: switch to meta files


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

  Write source file.

Parameters:

  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

XmlResult: status



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

  Delete the specified file and commits the changes.

XmlBody: none
XmlResult: status

Parameters:

  meta: switch to meta files


POST /source/<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
  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
  addchannels: add channel packages and repositories for matching packages in project
  addcontainers: add docker container packages and repositories using the maintained version of this 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
  time: set the time on undelete operation (admin only operation)
  wipe: wipe all build results of this package

Parameters:

  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
  extend_package_names: bool, optional, extends package and repository names to allow multiple instances of same package. used by default in incident projects.
  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.
  withvrev: copy also the vrev counter of the revision

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

  creating a new commit including defined files already uploaded to the repository.
  This can be done via PUT using rev=repository which avoids a commit.

  This requires a directory xml providing file name and md5 as body.
  It is recommended to use the withvalidate parameter and including the
  sha256 sum including "sha256:" prefix in "hash" attribute for security reason.

Parameters:
  withvalidate: activate sha validation code (optional, but recommended)
  comment: comment for history, optional
  keeplink: bool, optional. If the package is a link and keeplink is true, then the link is preserved. By default keeplink is false and the link is replaced with the expanded sources when creating a new revision.
  linkrev: optional, specifies the revision to link against when used together with keeplink parameter.
  repairlink: boolean, optional, for solving conflicts. The additional linkrev parameter is recommended.

XmlBody: directory


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

  Get all attributes or a specific one

XmlBody: attribute


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

  Modifies a specific attribute as in body

Parameters:

  comment: comment, optional

XmlResult: status


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

  Removes a specific attribute

Parameters:

  comment: comment, optional

XmlBody: none
XmlResult: status



== Requests


GET /request

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

Parameters:

  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
  limit: to limit the result to the given number of requests

XmlResult: collection


GET /request/<id>

  Get a request

Parameters:

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

XmlResult: request


POST /request

  Create a new request

XmlResult: request

  Commands on processing requests
  create: to crfeate a new request

Parameters:

  addrevision: ask the server to add revisions of current sources to the request
  ignore_delegate: enforce a new package instance in a project which has OBS:DelegateRequestTarget set
  ignore_build_state: skip the build state check


PUT /request/<id>

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

XmlResult: request


POST /request/<id>?cmd=diff

  Shows the diff of all affected packages.

Parameters:
  diff_to_superseded: diff relative to a given superseded request
  view: can be set to "xml" for structured diff
  withissues: included parsed issues

Result: diff as text/plain or xml based on view parameter


POST /request/<id>

  Modify a request

XmlResult: request

  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.
  approve: pre-approve a request in review state. Will turn into accepted after last review
  cancelapproval: reset the approval

Parameters:
  comment: Comment for the request history
  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
  keep_packages_locked: keep packages locked when revoking a maintenance release request
  incident: Specifiy inicdent number for setincident
  time: Specifiy time for setacceptat


== Attribute definition api


GET /attribute/

  List all attribute namespaces

XmlResult: directory


GET /attribute/<namespace>/

  List all attributes under given namespace

XmlResult: directory


GET /attribute/<namespace>/_meta

  shows namespace setup

XmlResult: attribute_namespace_meta


DELETE /attribute/<namespace>/_meta

  Delete a attribute namespace and all attributes below

XmlBody: none
XmlResult: status


PUT /attribute/<namespace>/_meta

  change attribute namespace meta

XmlBody: attribute_namespace_meta_data

XmlResult: status


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

  shows attribute setup

XmlResult: attribute_meta


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

  Delete a attribute and all its values in projects or packages

XmlBody: none
XmlResult: status


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

  change attribute meta

XmlBody: attribute_meta_data

XmlResult: status


== Comments api

GET /comments/request/:id
GET /comments/project/:name
GET /comments/package/:project/:pname

  Get all comments for the object

XmlResult: directory

POST /comments/request/:id?parent_id=<parent_comment_id>
POST /comments/project/:name?parent_id=<parent_comment_id>
POST /comments/package/:project/:pname?parent_id=<parent_comment_id>

  Create a comment for the object

XmlResult: status


DELETE /comment/:id

  Delete a comment specified by the comment id

XmlBody: none
XmlResult: status


== Build Results

<build>: Build repository

GET /build/

  List all repositories

XmlResult: directory


GET /build/<project>

  List all repositories of the specified project

XmlResult: directory


GET /build/<project>/<repository>

  List all architectures of the specified project repository

XmlResult: directory


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

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

XmlResult: directory

=== Binaries

GET /build/<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>

  Get single binary from build results of given package

Result: binary file

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

  Get information about the binary from build results of given package

Result: fileinfo


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

  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.

Parameters:

  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

  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

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

Result: binarylist


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

  Uploads binaries to a given repository. ADMIN ONLY

Result: status


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

  Uploads binaries into the repository. ADMIN ONLY.

Result: status


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

  Get single binary from the given repository

Result: binary file


=== Status

GET /build/<project>/_result

  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.

Parameters:

  package: package name, optional, multiple
  arch: architecture, optional, multiple
  repository: name of repository, optional, multiple
  view: summary | status | binarylist
  lastbuild: bool, show last build result (avoiding current building job state)
  locallink: bool, include build results from packages with project local links
  multibuild: bool, include build results from _multibuild definitions

XmlResult: buildresult


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

  Get build history

XmlResult: buildhistory


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

  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.

XmlResult: buildreason


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

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

XmlResult: jobstatus


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

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

XmlResult: buildstatus


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

  Get build log.

Parameters:

  nostream: do not hang if the build is currently running
  last: show log from last finished build
  lastsucceeded: show last succeeded log
  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.

=== Worker

GET /worker/_status

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

XmlResult: workerstatus


GET /worker/<hostarch>:<workerid>

  Lists all capabilities of the worker. Can be used for constraints

XmlResult: workercapability


POST /worker?cmd=checkconstraints

  Calculates the possible workers with a given constraints rule. Further required parameters
  are:

Parameters:

  project: project name
  package: package name
  arch: architecture
  repository: name of repository

XmlResult: directory


=== Control

POST /build/<project>?cmd=rebuild

  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

Parameters:

  package: package name, optional, multiple
  arch: architecture, optional, multiple
  repository: name of repository, optional, multiple
  code: build status code, optional, multiple
  lastbuild: use the state of last build result (together with code)

XmlResult: status


POST /build/<project>?cmd=abortbuild

  Kill all running builds, marking them as failed

Parameters:

  see cmd=rebuild


POST /build/<project>?cmd=restartbuild

  Restart all running builds

Parameters:

  see cmd=rebuild


POST /build/<project>?cmd=unpublish

  Delete all binary packages from publish area

Parameters:

  see cmd=rebuild


POST /build/<project>?cmd=sendsysrq

  Send a single sysrq char to the kernel of a running build
  Only a subset of debugging requests a are supported (eg. 9, t or w)

Parameters:

  see cmd=rebuild
  sysrq: for specifing the sysrq


POST /build/<project>?cmd=wipe

  Delete all binary packages from build area

Parameters:

  see cmd=rebuild


=== Local Build

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

  Get build information for local building

XmlResult: buildinfo


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

  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

XmlResult: buildinfo


=== Trigger area

POST /trigger/runservice

  This call needs a token to identify the user and package which shall be updated
  via a source service. See the cmd=create in the /person/<userid>/token route.

  The token itself must be delivered as a HTTP header:
    Authorization: Token <TOKEN_STRING>

Parameters
  project: To be used together with "package" to identify the object. Must not be used
           when the token is bound to a package.
  package: see project parameter.

XmlResult: status

=== Repository Information

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

  Returns list of binaries contained in the specified repository

XmlResult: binarylist


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

  Returns binary

Result: binary file


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

  Returns list of binaries contained in the specified repository

XmlResult: binarylist


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

  Build info according to the committed sources

XmlResult: buildinfo


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

  Build info according to the uploaded sources

XmlResult: buildinfo


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

  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.

XmlResult: builddepinfo


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

  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.

Parameters:

  match: xpath predicate, mandatory

XmlResult: collection


GET /search/project/id

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

Parameters:

  match: xpath predicate, mandatory

XmlResult: 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.

Parameters:

  match: xpath predicate, mandatory

XmlResult: collection


GET /search/package/id

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

Parameters:

  match: xpath predicate, mandatory

XmlResult: collection


GET /search/published/binary/id

  Search for currenlty available binaries in the publish area.

Parameters:

  match: xpath predicate, mandatory
  limit: override limit of entries, optional
  withdownloadurl: bool, add download url entries as well, optional

XmlResult: collection


GET /search/published/repoinfo/id

  Search for currenlty available repositories in the publish area.

Parameters:

  match: xpath predicate, mandatory
  limit: override limit of entries, optional
  withdownloadurl: bool, add download url entries as well, optional

XmlResult: collection


GET /search/published/pattern/id

  Search for published patterns

Parameters:

  match: xpath predicate, mandatory
  limit: override limit of entries, optional
  withdownloadurl: bool, add download url entries as well, optional

XmlResult: 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.

Parameters:

  match: xpath predicate, mandatory

XmlResult: 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.

Parameters:

  match: xpath predicate, mandatory

XmlResult: 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.

Parameters:

  match: xpath predicate, mandatory

XmlResult: 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.

Parameters:

  match: xpath predicate, mandatory

XmlResult: 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.

Parameters:

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

XmlResult: 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.

Parameters:

  match: xpath predicate, mandatory

XmlResult: 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.

Parameters:

  binary: specify the binary package to search for
  user: specify a user login name to list their 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

XmlResult: collection


GET /search/missing_owner

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

Parameters:

  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

XmlResult: collection


== Published binary package tree

GET /published

  List of published projects

XmlResult: directory


GET /published/<project>

  List of repositories of published projects

XmlResult: directory


GET /published/<project>/<repository>

  List of published repositories for the given project/repo

XmlResult: directory


GET /published/<project>/<repository>?view=status

  Delivers last publish information like time and repository build id

XmlResult: buildstatus


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

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

XmlResult: directory


GET /published/<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

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

XmlResult: ymp


== 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

  Read project summary result.

XmlResult: projectresult


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

  Read package result.

XmlResult: packageresult


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

  Read build log.

Result: Build log as text file.



== Statistics

<limit>: limit count of results. optional, defaults to 10.
<group_by>: group results by: project, package, repo or arch.
<type>: can be projects or packages. optional, defaults to packages


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.
XmlResult: latest_added


GET /statistics/added_timestamp/<project>/<package>
  Get timestamp when project or package was added to the build service.
XmlResult: added_timestamp


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.
XmlResult: latest_updated


GET /statistics/updated_timestamp/<project>/<package>
  Get timestamp when project or package was last updated.
XmlResult: updated_timestamp


GET /statistics/activity/<project>/<package>
  Get activity in % of project or package.
XmlResult: activity


GET /statistics/most_active_projects?limit=<limit>
  Get list of most active projects.
XmlResult: most_active_projects

GET /statistics/most_active_packages?limit=<limit>
  Get list of most active packages.
XmlResult: most_active_packages


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.
XmlResult: redirect_stats


== Status Messages

<limit>: limit count of messages. optional, defaults to unlimited.


GET /status/messages/<id>
  Get a the status message that matches <id>.
XmlResult: status_message

GET /status/messages/?limit=<limit>
  Get a list of status messages.
XmlResult: status_messages

POST /status/messages/
  Send a new status message to the build service. User needs to have
  appropriate permissions.
XmlResult: status_message

DELETE /status/messages/<id>
  Delete a status message. User needs to have appropriate permissions.


== Status Checks
  WARNING: This API is currently in beta and unstable

=== Repositories

<project>: The name of a project, e.g. home:user1
<repository>: The name of a repository of the project, e.g. openSUSE_Tumbleweed
<build_id>: The build id you have received for the repository, e.g. 12345

GET /status_reports/published/<project>/<repository>/reports/<build_id>
  Get a status report with this build id
XmlResult: status_report


PUT /status_reports/published/<project>/<repository>/reports/<build_id>
  Create or update check data
XmlResult: check

=== Requests

<request>: The number of the request, e.g. 12345

GET /status_reports/requests/<request>/reports
  Get a the status report for this request
XmlResult: status_report


PUT /status_reports/requests/<request>/reports
  Create or update check data
XmlResult: check

== Required Status Checks
  WARNING: This API is currently in beta and unstable

=== Projects

<project>: The name of a project, e.g. home:user1
<check>: The name of the required check

GET /status_reports/projects/<project>/required_checks
  Get all required checks for this project
XmlResult: required_checks

POST /status_reports/projects/<project>/required_checks/<check>
  Create a required check
XmlResult: required_checks

DELETE /status_reports/projects/<project>/required_checks/<check>
  Delete a required check

XmlBody: none
XmlResult: required_checks

=== Repositories

<project>: The name of a project, e.g. home:user1
<repository>: The name of a repository of the project, e.g. openSUSE_Tumbleweed
<check>: The name of the required check

GET /status_reports/repositories/<project>/<repository>/required_checks
  Get all required checks for this repository
XmlResult: required_checks


POST /status_reports/repositories/<project>/<repository>/required_checks/<check>
  Create a required check
XmlResult: required_checks


DELETE /status_reports/repositories/<project>/<repository>/required_checks/<check>
  Delete a required check

XmlBody: none
XmlResult: required_checks

== Staging
  WARNING: This API is currently in beta and unstable

=== Staging Workflow

<staging_workflow_project>: The name of the staging workflow project, e.g. openSUSE:Factory
<staging_project>: The name of the staging project, e.g. openSUSE:Factory:Staging:A
<staging_project_copy_name>: The name of the staging project's copy, e.g. openSUSE:Factory:Staging:B

POST /staging/<staging_workflow_project>/workflow
  Create a staging workflow for a given project.
XmlBody: create_staging_workflow
XmlResult: status_ok

PUT /staging/<staging_workflow_project>/workflow
  Update the managers group of a staging workflow.
XmlBody: update_staging_workflow
XmlResult: status_ok

DELETE /staging/<staging_workflow_project>/workflow
  Delete a staging workflow associated to a given project.

Parameters:
  with_staging_projects: deletes all staging projects of the staging workflow

XmlBody: none
XmlResult: status_ok

GET /staging/<staging_workflow_project>/staging_projects?requests=1&status=1&history=1
  Get the overall state of all staging projects belonging to a staging workflow project.
  Extra information can be requested by adding any combination of these parameters in the URL: requests, status and history.

  - If requests is present, the output includes the staged, untracked and obsolete requests as well as missing reviews.
  - If status is present, the output includes the overall state and the status xml (broken packages, missing reviews, checks, etc.)
  - If history is present, the output includes the history of the staging project.

XmlResult: staging_projects

GET /staging/<staging_workflow_project>/staging_projects/<staging_project>?requests=1&status=1&history=1
  Get the overall state of a staging project.
  Extra information can be requested by adding any combination of these parameters in the URL: requests, status and history.

  - If requests is present, the output includes the staged, untracked and obsolete requests as well as missing reviews.
  - If status is present, the output includes the overall state and the status xml (broken packages, missing reviews, checks, etc.)
  - If history is present, the output includes the history of the staging project.

XmlResult: staging_project

POST /staging/<staging_workflow_project>/staging_projects/<staging_project>/copy/<staging_project_copy_name>
  Copy a staging project
XmlResult: status_ok

POST /staging/<staging_workflow_project>/staging_projects/<staging_project>/accept?force=1
  Accept staging project. This accepts all staged requests and sets the project state back to 'empty'.
  Will return in an error if staging project is not acceptable, unless force is given. You can force
   accept staging projects with building or failing packages, but not with missing reviews
XmlResult: status_ok

POST /staging/<staging_workflow_project>/staging_projects
  Create staging projects

XmlBody: create_staging_projects
XmlResult: status_ok


=== Backlog

<staging_workflow_project>: The name of the staging workflow project, e.g. home:user1

GET /staging/<staging_workflow_project>/backlog
  Get the list of requests that are not added into any staging project or excluded.
XmlResult: backlog

=== Excluded Requests

<project>: The name of the main project of a Staging, e.g. openSUSE:Factory
<request>: The number of the request, e.g. 12345
<description>: A string of text (url encoded)

GET /staging/<project>/excluded_requests
  Get the list of excluded request for this Staging
XmlResult: excluded_requests

POST /staging/<project>/excluded_requests
  Exclude this request from this Staging
XmlBody: create_excluded_requests
XmlResult: status_ok

DELETE /staging/<project>/excluded_requests
  Stop excluding this request

XmlBody: delete_excluded_requests
XmlResult: status_ok

=== Staged Requests

<staging_workflow_project>: The name of the staging workflow project, e.g. home:user1
<staging_project>: The name of the staging project, e.g. home:user1:Staging:A

GET /staging/<staging_workflow_project>/staging_projects/<staging_project>/staged_requests
  Get all staged requests of a staging project.
XmlResult: staged_requests

POST /staging/<staging_workflow_project>/staging_projects/<staging_project>/staged_requests
  Add one or multiple bs_requests to the staged requests of a staging project
  remove_exclusion: removes the request from exclusion request before staging it.

XmlBody: remove_staged_requests
XmlResult: status_ok

DELETE /staging/<staging_workflow_project>/staged_requests
  Remove requests from the staging projects they are staged in.

XmlBody: remove_staged_requests
XmlResult: status_ok


== Configuration

GET /configuration

  Publicly readable configuration of this OBS instance.

XmlResult: configuration configuration.rng


== Internal only routes

   /public shall not be used in any tools, it is for OBS remote support only and may change or disappear at any time. The route is only working when anonymous mode is enabled.
