API Documentation

Overview

OBS Git Explorer provides a REST API for programmatic access to build results, file search, and backend configuration. All endpoints return JSON unless otherwise noted.

Please note that these api calls may have a configured rate limit.

Base URL

All API endpoints are relative to this server's base URL: 

http://gitexplorer.opensuse.org/api/

Endpoints

GET /api/products/packages

Search or list packages from SPDX products

Description

Returns packages from indexed SPDX product data. This includes package metadata, VCS information (git repository, branch, commit), and the product they belong to. Optionally filter results by package name.

Query Parameters
Parameter Type Required Description
q string No Package name to filter by (case-insensitive partial match). If omitted, returns all packages.
Response

Returns a JSON object with package information:

{
  "search_term": "bash",
  "count": 25,
  "packages": [
    {
      "package_name": "bash",
      "arch": "x86_64",
      "filename": "bash-5.2.15-1.1.x86_64.rpm",
      "vcs_url": "https://src.opensuse.org/pool/bash",
      "vcs_org": "pool",
      "tracking_branch": "factory",
      "commit_hash": "abc123def456...",
      "disturl": "obs://build.opensuse.org/openSUSE:Factory/standard/...",
      "product": {
        "name": "openSUSE-Tumbleweed",
        "version": "20240401",
        "architecture": "x86_64",
        "build_number": "Snapshot20240401",
        "full_name": "openSUSE-Tumbleweed-DVD-x86_64-Snapshot20240401"
      }
    },
    {
      "package_name": "bash-completion",
      "arch": "noarch",
      "filename": "bash-completion-2.11-1.1.noarch.rpm",
      "vcs_url": "https://src.opensuse.org/pool/bash-completion",
      "vcs_org": "pool",
      "tracking_branch": "factory",
      "commit_hash": "def789ghi012...",
      "disturl": "obs://build.opensuse.org/openSUSE:Factory/standard/...",
      "product": {
        "name": "openSUSE-Tumbleweed",
        "version": "20240401",
        "architecture": "x86_64",
        "build_number": "Snapshot20240401",
        "full_name": "openSUSE-Tumbleweed-DVD-x86_64-Snapshot20240401"
      }
    }
  ]
}
Response Fields
  • search_term - The search term used (null if no filter applied)
  • count - Number of packages returned
  • packages - Array of package objects with:
    • package_name - Source package name
    • arch - Package architecture
    • filename - RPM filename
    • vcs_url - Git repository URL
    • vcs_org - Gitea organization name
    • tracking_branch - Git branch being tracked
    • commit_hash - Git commit hash used to build the package
    • disturl - OBS distribution URL
    • product - Product information (name, version, architecture, build number)
Example Requests

List all packages:

curl "http://gitexplorer.opensuse.org/api/products/packages"

Search for packages matching "bash":

curl "http://gitexplorer.opensuse.org/api/products/packages?q=bash"
Response Codes
  • 200 OK - Successful query
Notes
  • Results are sorted alphabetically by package name
  • The search is a case-insensitive substring match
  • Data comes from indexed SPDX product files (updated by cache daemon)

GET /api/products/files

Search for files in RPMs across all products

Description

Searches through the file lists of all indexed RPM packages to find files matching the query. Results are enriched with package metadata from SPDX products database.

Query Parameters
Parameter Type Required Description
q string Yes Search term (minimum 2 characters)
Response

Returns a JSON object with search results:

{
  "search_term": "bash",
  "count": 2,
  "results": [
    {
      "file_path": "/usr/bin/bash",
      "rpm_filename": "bash-5.2.15-1.1.x86_64.rpm",
      "packages": [
        {
          "package_name": "bash",
          "arch": "x86_64",
          "vcs_url": "https://src.opensuse.org/pool/bash",
          "vcs_org": "pool",
          "tracking_branch": "factory",
          "commit_hash": "abc123...",
          "disturl": "obs://build.opensuse.org/openSUSE:Factory/...",
          "product_name": "openSUSE-Tumbleweed",
          "product_version": "20240401",
          "product_build": "Snapshot20240401"
        }
      ]
    }
  ]
}
Example Request
curl "http://gitexplorer.opensuse.org/api/products/files?q=bash"
Response Codes
  • 200 OK - Successful search
  • 400 Bad Request - Search term too short (less than 2 characters)

GET /api/projects/<project_name>/_result

Get build results for an OBS project

Description

Returns build results for a specific project. In Redis mode, results are fetched from cache. Otherwise, results are fetched from the OBS API.

URL Parameters
Parameter Type Description
project_name string OBS project name (e.g., "openSUSE:Factory")
Query Parameters
Parameter Type Required Description
repos string No Comma-separated list of repositories to filter (e.g., "standard,product")
archs string No Comma-separated list of architectures to filter (e.g., "x86_64,aarch64")
status string No Filter by build status (e.g., "failed", "succeeded")
lastbuild string No Set to "1" for last build results only (not supported in Redis mode)
oldstate string No Checksum for change detection (not supported in Redis mode)
Response

Returns XML in OBS _result format:

<?xml version="1.0" encoding="UTF-8"?>
<resultlist state="...">
  <result project="openSUSE:Factory" repository="standard" arch="x86_64">
    <status package="bash" code="succeeded"/>
    <status package="vim" code="failed">
      <details>error: Bad exit status from /var/tmp/rpm-tmp.xyz</details>
    </status>
  </result>
</resultlist>
Example Request
curl "http://gitexplorer.opensuse.org/api/projects/openSUSE:Factory/_result?archs=x86_64&status=failed"
Response Codes
  • 200 OK - Successful query
  • 404 Not Found - Project not found or access restricted

GET /api/packages/<package_name>/fork-builds

Query build results from all forks of a repository

Description

Queries Gitea for all forks of a package repository and returns build results for each fork. Useful for tracking development in forked repositories.

URL Parameters
Parameter Type Description
package_name string Package/repository name in Gitea
Query Parameters
Parameter Type Required Description
org string No Gitea organization (defaults to configured organization)
Response
{
  "success": true,
  "forks": [
    {
      "owner": "user123",
      "name": "bash",
      "url": "https://src.opensuse.org/user123/bash",
      "build_results": [
        {
          "project": "home:user123:branches:openSUSE:Factory",
          "package": "bash",
          "repository": "openSUSE_Tumbleweed",
          "arch": "x86_64",
          "status": "succeeded"
        }
      ]
    }
  ]
}
Example Request
curl "http://gitexplorer.opensuse.org/api/packages/bash/fork-builds"
Response Codes
  • 200 OK - Successful query
  • 404 Not Found - Package not found or could not fetch forks

GET /api/search/binary

Search for published binary packages across OBS

Description

Searches for published binary packages (RPMs, DEBs, etc.) across all OBS projects. Results include download URLs and source repository information when available. Results are filtered based on project access control.

Query Parameters
Parameter Type Required Description
q string Yes Package name to search for
Response

Returns a JSON object with search results separated by SCM availability:

{
  "query": "bash",
  "total_count": 50,
  "count_with_scm": 45,
  "count_without_scm": 5,
  "results_with_scm": [
    {
      "name": "bash-5.2.15-1.1.x86_64.rpm",
      "project": "openSUSE:Factory",
      "package": "bash",
      "repository": "standard",
      "arch": "x86_64",
      "version": "5.2.15-1.1",
      "download_url": "http://download.opensuse.org/.../bash-5.2.15-1.1.x86_64.rpm",
      "source_url": "https://src.opensuse.org/pool/bash#factory",
      "git_org": "pool",
      "git_repo": "bash"
    }
  ],
  "results_without_scm": [
    {
      "name": "bash-doc-5.2.15-1.1.noarch.rpm",
      "project": "openSUSE:Leap:15.5",
      "package": "bash",
      "repository": "standard",
      "arch": "noarch",
      "version": "5.2.15-1.1",
      "download_url": "http://download.opensuse.org/.../bash-doc-5.2.15-1.1.noarch.rpm",
      "source_url": null,
      "git_org": null,
      "git_repo": null
    }
  ]
}
Response Fields
  • query - The search term used
  • total_count - Total number of matching binaries
  • count_with_scm - Number of results with SCM source information
  • count_without_scm - Number of results without SCM source information
  • results_with_scm - Array of binaries with git source repository information
  • results_without_scm - Array of binaries without git source repository information
Example Request
curl "http://gitexplorer.opensuse.org/api/search/binary?q=bash"
Response Codes
  • 200 OK - Successful search
  • 400 Bad Request - No query provided
  • 500 Internal Server Error - Failed to parse search results
  • 504 Gateway Timeout - Search request timed out
Notes
  • Results are automatically filtered to exclude binaries from projects with access restrictions
  • The source_url field contains the Gitea repository URL if the package is synchronized from git
  • Search timeout is 60 seconds

GET /api/backend-config

Get backend configuration information

Description

Returns configuration information from the OBS backend, including available schedulers, download settings, and other backend-specific settings.

Response
{
  "schedulers": {
    "arch": ["x86_64", "aarch64", "ppc64le", ...]
  },
  "download_url": "http://download.opensuse.org",
  ...
}
Example Request
curl "http://gitexplorer.opensuse.org/api/backend-config"
Response Codes
  • 200 OK - Successful query
  • 500 Internal Server Error - Could not fetch backend configuration

GET /badge/projects/<project_name>.svg

Generate SVG badge showing build status

Description

Returns a dynamic SVG badge showing the current build status for a project. The badge is embeddable in markdown (Gitea PR comments, README files, documentation). Badge color automatically adjusts based on build results: green for passing, red for failed, yellow for blocked, blue for building, gray for inactive/error.

Interactive badges: When viewing the SVG directly (not embedded in markdown), each status count is clickable and links to the filtered monitor view. For example, clicking "3 failed" opens the project page filtered to show only failed builds.

URL Parameters
Parameter Type Description
project_name string OBS project name (e.g., "SUSE:SLFO:1.2")
Query Parameters
Parameter Type Required Description
repos string No Comma-separated list of repositories to filter (e.g., "standard,pool")
archs string No Comma-separated list of architectures to filter (e.g., "x86_64,aarch64")
label string No Custom badge label text (default: "build")
Response

Returns an SVG image with Content-Type: image/svg+xml

Badge format: Left side shows label, right side shows status with color-coded background.

Example Usage

In Markdown (Gitea PR comments, README files):

![Build Status](http://gitexplorer.opensuse.org/badge/projects/SUSE:SLFO:1.2.svg)

With filters:

![x86_64 Status](http://gitexplorer.opensuse.org/badge/projects/SUSE:SLFO:1.2.svg?archs=x86_64&label=x86_64)

Specific repository:

![Pool Status](http://gitexplorer.opensuse.org/badge/projects/SUSE:SLFO:1.2.svg?repos=pool&label=pool)

Direct browser access:

curl "http://gitexplorer.opensuse.org/badge/projects/SUSE:SLFO:1.2.svg"
Badge Colors
  • Green (#44cc11): All builds succeeded
  • Red (#e05d44): Any failed/broken/unresolvable builds
  • Yellow (#dfb317): Any blocked builds
  • Blue (#007ec6): Building/scheduled/wip states only
  • Gray (#9f9f9f): Disabled/excluded/no builds/error
Response Codes
  • 200 OK - Badge generated successfully
Caching

Badges are cached for 30 seconds (Cache-Control: public, max-age=30). This provides frequent updates while balancing server load. When embedded in Gitea PR comments or README files, the badge will refresh automatically when the page is reloaded (after the cache expires).

Notes
  • If an error occurs (project not found, build results unavailable), a gray "error" badge is returned
  • SVG badges scale perfectly and work in all modern browsers
  • Project names with special characters (colons, slashes) must be URL-encoded

GET /badge/projects/<project_name>/summary.svg

Generate detailed SVG badge with status counts

Description

Similar to the basic badge, but shows detailed status counts (e.g., "45 succeeded, 3 failed, 1 building"). Useful for projects where you want to see exact numbers rather than just a status indicator.

URL Parameters
Parameter Type Description
project_name string OBS project name
Query Parameters

Same as /badge/projects/<project_name>.svg - supports repos, archs, and label.

Example Usage

In Markdown:

![Build Details](http://gitexplorer.opensuse.org/badge/projects/SUSE:SLFO:1.2/summary.svg)

With filters:

![Build Details](http://gitexplorer.opensuse.org/badge/projects/SUSE:SLFO:1.2/summary.svg?archs=x86_64)
Notes
  • Shows up to two most important status categories to keep badge readable
  • Priority order: succeeded, failed, blocked, building
  • Same caching behavior as basic badge (30 seconds)

GET /badge/projects/<project_name>/<package_name>.svg

Generate SVG badge showing build status for a specific package

Description

Returns a dynamic SVG badge showing build status for a specific package within a project. Useful for displaying package-specific status in package README files or PR comments.

URL Parameters
Parameter Type Description
project_name string OBS project name (e.g., "SUSE:SLFO:1.2")
package_name string Package name (e.g., "bash")
Query Parameters
Parameter Type Required Description
repos string No Comma-separated list of repositories to filter
archs string No Comma-separated list of architectures to filter
label string No Custom badge label text (default: package name)
Example Usage

In Package README.md:

![Build Status](http://gitexplorer.opensuse.org/badge/projects/SUSE:SLFO:1.2/bash.svg)

In Gitea PR comment:

Build status for poppler in SLFO 1.2:
![poppler](http://gitexplorer.opensuse.org/badge/projects/SUSE:SLFO:1.2/poppler.svg)

With architecture filter:

![x86_64](http://gitexplorer.opensuse.org/badge/projects/SUSE:SLFO:1.2/bash.svg?archs=x86_64&label=bash%20x86_64)
Notes
  • Badge label defaults to package name if not specified
  • Same color scheme and caching as project badges
  • Returns "error" badge if package not found in project

GET /badge/projects/<project_name>/_table.svg

Generate SVG showing full build status matrix table

Description

Returns an SVG image showing the complete build matrix table with packages as rows and repository/architecture combinations as columns. Each cell is color-coded by build status. This provides a visual overview of all builds at a glance.

Interactive elements:

  • Package header (top-left) - Clickable, opens the project's Monitor tab
  • Succeeded cells (green ✓) - Clickable, opens build log viewer popup
  • Failed cells (red ✗/⚠/?) - Clickable, opens build log viewer popup
  • Other cells (building, blocked) - Not clickable (no log available yet)

All clickable cells open in a new window with the build log displayed in a modal popup.

Two display modes available:

  • Full matrix (default): Shows individual cells for each package/repo/arch combination
  • Compact summary (compact=true): Shows status counts per package
URL Parameters
Parameter Type Description
project_name string OBS project name (e.g., "SUSE:SLFO:1.2")
Query Parameters
Parameter Type Required Description
repos string No Comma-separated list of repositories to filter
archs string No Comma-separated list of architectures to filter
compact boolean No Set to 'true' for compact summary view (default: false)
max_packages integer No Maximum packages to show, 1-100 (default: 50)
max_repos integer No Maximum repo/arch combinations to show, 1-20 (default: 10)
Example Usage

Full matrix view:

![Build Matrix](http://gitexplorer.opensuse.org/badge/projects/SUSE:SLFO:1.2/_table.svg)

Compact summary view:

![Build Summary](http://gitexplorer.opensuse.org/badge/projects/SUSE:SLFO:1.2/_table.svg?compact=true)

Filtered by architecture:

![x86_64 Matrix](http://gitexplorer.opensuse.org/badge/projects/SUSE:SLFO:1.2/_table.svg?archs=x86_64)

Limited to 20 packages:

![Top 20](http://gitexplorer.opensuse.org/badge/projects/SUSE:SLFO:1.2/_table.svg?max_packages=20)

Direct browser access:

curl "http://gitexplorer.opensuse.org/badge/projects/SUSE:SLFO:1.2/_table.svg" > matrix.svg
Color Coding
  • Green: Succeeded builds
  • Red: Failed/broken/unresolvable builds
  • Yellow: Blocked builds
  • Blue: Building/scheduled/in-progress
  • Gray: Disabled/excluded/no build
Response

Returns SVG image with Content-Type: image/svg+xml

Notes
  • Package names are truncated if longer than display width
  • Full matrix is limited to prevent extremely large SVGs (max 100 packages, 20 repo/arch)
  • Truncation indicator: When results are limited, the Package header shows a yellow warning (⚠ LIMITED VIEW) with the actual count (e.g., "50/75 pkgs") and a "Click for full" link to the monitor tab
  • Compact mode shows summary counts: ✓N (succeeded), ✗N (failed), ⟳N (building)
  • Same 30-second caching as other badges
  • Perfect for embedding in documentation or dashboards

OBS Backend Proxy

In addition to the JSON API endpoints above, this server provides read-only proxy access to the OBS backend. These endpoints forward requests to the underlying OBS instance and return responses in OBS XML format.

These can be used for example with osc when you configure an api url "http://gitexplorer.opensuse.org/obs .

GET /obs/source/<path>

Forward requests to OBS source API. Access project metadata, package lists, source files, and other source-related information.

Example Requests
# Get project metadata
curl "http://gitexplorer.opensuse.org/obs/source/openSUSE:Factory/_meta"

# List packages in a project
curl "http://gitexplorer.opensuse.org/obs/source/openSUSE:Factory"

# Get package metadata
curl "http://gitexplorer.opensuse.org/obs/source/openSUSE:Factory/bash/_meta"

GET /obs/build/<path>

Forward requests to OBS build API. Access build results, build logs, binary packages, and build-related information. This endpoint is also used by the web interface for displaying build results and logs.

Example Requests
# Get build results for a project
curl "http://gitexplorer.opensuse.org/obs/build/openSUSE:Factory/_result"

# Get build log for a specific package
curl "http://gitexplorer.opensuse.org/obs/build/openSUSE:Factory/standard/x86_64/bash/_log"

# Get binary package
curl "http://gitexplorer.opensuse.org/obs/build/openSUSE:Factory/standard/x86_64/bash/bash-5.2.rpm"

GET /obs/request/<path>

Forward requests to OBS request API. Returns an empty request list since this is a read-only interface and does not support request management.

Access Control
  • Read-only: Only GET requests are allowed (with few exceptions for read-only POST operations)
  • Project filtering: Only projects in the cache are accessible (projects with access restrictions return 404)
  • Authentication: Inherited from server configuration
  • Write operations: POST, PUT, PATCH, DELETE are blocked (405 Method Not Allowed)

Error Handling

All API endpoints return appropriate HTTP status codes. Error responses include a JSON object with an error field describing the issue: 

{
  "error": "Search term must be at least 2 characters"
}

Rate Limiting

API endpoints are protected by rate limiting to prevent DoS attacks and ensure the web interface remains responsive under heavy load. By default, rate limiting is enabled with the following configuration:

  • Default limit: 100 requests per hour per IP address
  • Scope: API endpoints (/api/*) and OBS proxy endpoints (/obs/*) are rate limited
  • Web interface: Unaffected by rate limits - always accessible
  • Response: HTTP 429 (Too Many Requests) when limit exceeded
  • IP Detection: Uses X-Forwarded-For header when behind a reverse proxy, falls back to direct connection IP

Rate limits can be configured in the server configuration file (config.ini) or via command-line arguments. Server administrators may adjust limits based on their deployment requirements.

For automated tools: Please implement exponential backoff when receiving 429 responses, and consider caching results when possible.

Authentication

Authentication is inherited from the server configuration. If the server is configured with OBS credentials, those credentials are used for backend requests. The API itself does not require separate authentication.