NAV
cURL

Introduction

Welcome to the Vieter API documentation! Here, you can find everything related to interacting with Vieter's HTTP API.

Authentication

curl -H 'X-Api-Key: secret' https://example.com/api/some/path

Don't forget to replace secret with your Vieter instance's secret.

Authentication is done by passing the HTTP header X-Api-Key: secret along with each request, where secret is replaced with your Vieter server's configured secret.

Repository

Besides providing a RESTful API, the Vieter server is also a Pacman-compatible repository server. This section describes the various routes that make this possible.

Get a package archive or database file

curl -L https://example.com/bur/x86_64/tuxedo-keyboard-3.0.10-1-x86_64.pkg.tar.zst

This endpoint is really the entire repository. It serves both the package archives & the database files for a specific arch-repo. It has three different behaviors, depending on filename:

HTTP Request

GET /:repo/:arch/:filename

URL Parameters

Parameter Description
repo Repository containing the package
arch Arch-repo containing the package
filename actual filename to request

Check whether file exists

curl -L https://example.com/bur/x86_64/tuxedo-keyboard-3.0.10-1-x86_64.pkg.tar.zst

The above request can also be performed as a HEAD request. The behavior is the same, except no data is returned besides an error 404 if the file doesn't exist & an error 200 otherwise.

HTTP Request

GET /:repo/:arch/:filename

URL Parameters

Parameter Description
repo Repository containing the package
arch Arch-repo containing the package
filename actual filename to request

Publish package

curl \
  -H 'X-Api-Key: secret' \
  -XPOST \
  -T tuxedo-keyboard-3.0.10-1-x86_64.pkg.tar.zst \
  https://example.com/some-repo/publish

This endpoint allows you to publish a new package archive to a given repo.

If the package's architecture is not any, it is added to that specific arch-repo. Otherwise, it is added to the configured default architecture & any other already present arch-repos.

HTTP Request

POST /:repo/publish

URL Parameters

Parameter Description
repo Repository to publish package to

Remove package from arch-repo

curl \
  -H 'X-Api-Key: secret' \
  -XDELETE \
  https://example.com/vieter/x86_64/mike

This endpoint allows you to remove a package from a given arch-repo.

HTTP Request

DELETE /:repo/:arch/:pkg

URL Parameters

Parameter Description
repo Repository to delete package from
arch Specific arch-repo to remove package from
pkg Name of package to remove (without any version information)

Remove arch-repo

curl \
  -H 'X-Api-Key: secret' \
  -XDELETE \
  https://example.com/vieter/x86_64

This endpoint allows removing an entire arch-repo.

HTTP Request

DELETE /:repo/:arch

URL Parameters

Parameter Description
repo Repository to delete arch-repo from
arch Specific architecture to remove

Remove repo

curl \
  -H 'X-Api-Key: secret' \
  -XDELETE \
  https://example.com/vieter

This endpoint allows removing an entire repo.

HTTP Request

DELETE /:repo

URL Parameters

Parameter Description
repo Repository to delete

Targets

Endpoints for interacting with the list of targets stored on the server.

List targets

curl \
  -H 'X-Api-Key: secret' \
  https://example.com/api/v1/targets?offset=10&limit=20

JSON output format

{
  "message": "",
  "data": [
    {
      "id": 1,
      "kind": "git",
      "url": "https://aur.archlinux.org/discord-ptb.git",
      "branch": "master",
      "repo": "bur",
      "schedule": "",
      "arch": [
        {
          "id": 1,
          "target_id": 1,
          "value": "x86_64"
        }
      ]
    }
  ]
}

Retrieve a list of targets.

HTTP Request

GET /api/v1/targets

Query Parameters

Parameter Description
limit Maximum amount of results to return.
offset Offset of results.
repo Limit results to targets that publish to the given repo.

Get specific target

curl \
  -H 'X-Api-Key: secret' \
  https://example.com/api/v1/targets/1

JSON output format

{
  "message": "",
  "data": {
    "id": 1,
    "kind": "git",
    "url": "https://aur.archlinux.org/discord-ptb.git",
    "branch": "master",
    "repo": "bur",
    "schedule": "0 3",
    "arch": [
      {
        "id": 1,
        "target_id": 1,
        "value": "x86_64"
      }
    ]
  }
}

Get info about a specific target.

HTTP Request

GET /api/v1/targets/:id

URL Parameters

Parameter Description
id id of requested target

Create a new target

JSON output format

{
  "message": "",
  "data": {
    "id": 15
  }
}

Create a new target with the given data.

HTTP Request

POST /api/v1/targets

Query Parameters

Parameter Description
kind Kind of target to add; one of 'git', 'url'.
url URL of the Git repository.
branch Branch of the Git repository.
repo Vieter repository to publish built packages to.
schedule Cron build schedule (syntax explained here)
arch Comma-separated list of architectures to build package on.

Modify a target

Modify the data of an existing target.

HTTP Request

PATCH /api/v1/targets/:id

URL Parameters

Parameter Description
id id of target to modify

Query Parameters

Parameter Description
kind Kind of target; one of 'git', 'url'.
url URL of the Git repository.
branch Branch of the Git repository.
repo Vieter repository to publish built packages to.
schedule Cron build schedule
arch Comma-separated list of architectures to build package on.

Remove a target

Remove a target from the server.

HTTP Request

DELETE /api/v1/targets/:id

URL Parameters

Parameter Description
id id of target to remove

Build Logs

Endpoints for interacting with stored build logs.

List logs

curl \
  -H 'X-Api-Key: secret' \
  https://example.com/api/v1/logs?offset=10&limit=20

JSON output format

{
  "message": "",
  "data": [
    {
      "id": 1,
      "target_id": 3,
      "start_time": 1652008554,
      "end_time": 1652008559,
      "arch": "x86_64",
      "exit_code": 0
    }
  ]
}

Retrieve a list of build logs.

HTTP Request

GET /api/v1/logs

Query Parameters

Parameter Description
limit Maximum amount of results to return.
offset Offset of results.
target Only return builds for this target id.
before Only return logs started before this time (UTC epoch)
after Only return logs started after this time (UTC epoch)
arch Only return logs built on this architecture
exit_codes Comma-separated list of exit codes to limit result to; using ! as a prefix makes it exclude that value. For example, 1,2 only returns logs with status code 1 or 2, while !1,!2 returns those that don't have 1 or 2 as the result.

Get build log

curl \
  -H 'X-Api-Key: secret' \
  https://example.com/api/v1/logs/1

JSON output format

{
  "message": "",
  "data": {
    "id": 1,
    "target_id": 3,
    "start_time": 1652008554,
    "end_time": 1652008559,
    "arch": "x86_64",
    "exit_code": 0
  }
}

Retrieve info about a specific build log.

HTTP Request

GET /api/v1/logs/:id

URL Parameters

Parameter Description
id ID of requested log

Get log contents

curl \
  -H 'X-Api-Key: secret' \
  https://example.com/api/v1/logs/15/content

Retrieve the contents of a build log. The response is the build log in plaintext.

HTTP Request

GET /api/v1/logs/:id/content

URL Parameters

Parameter Description
id ID of requested log

Publish build log

JSON output format

{
  "message": "",
  "data": {
    "id": 15
  }
}

Publish a new build log to the server.

HTTP Request

POST /api/v1/logs

Query parameters

Parameter Description
startTime Start time of the build (UTC epoch)
endTime End time of the build (UTC epoch)
arch Architecture on which the build was done
exitCode Exit code of the build container
target id of target this build is for

Request body

Plaintext contents of the build log.