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:

If the file extension is one of .db, .files, .db.tar.gz or .files.tar.gz, it tries to serve the requested database file.
If the filename contains .pkg, it serves the package file.
Otherwise, it assumes filename is the name & version of a package inside the repository (e.g. vieter-0.3.0_alpha.2-1) & serves that package's desc file from inside the database archive.

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",
      "path" : "",
      "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.
query	Only return targets that have this substring in their URL, path or branch.
arch	Only return targets that publish to this arch.

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",
    "path": "",
    "repo": "bur",
    "schedule": "0 2",
    "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.
path	Subdirectory inside Git repository to use.
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.
path	Subdirectory inside Git repository to use.
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

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

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.

Remove a build log

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

Remove a build log from the server.

HTTP Request

DELETE /api/v1/logs/:id

URL Parameters

Parameter	Description
id	id of log to remove

Jobs

Manually schedule a job

curl \
  -H 'X-Api-Key: secret' \
  https://example.com/api/v1/jobs/queue?target=10&force&arch=x86_64

Manually schedule a job on the server.

HTTP Request

POST /api/v1/jobs/queue

Query Parameters

Parameter	Description
target	Id of target to schedule build for
arch	Architecture to build on
force	Whether it's a forced build (true if present)

Poll for new jobs

curl \
  -H 'X-Api-Key: secret' \
  https://example.com/api/v1/jobs/poll?arch=x86_64&max=2

JSON output format

{
  "message": "",
  "data": [
    {
      "target_id": 1,
      "kind": "git",
      "url": "https://aur.archlinux.org/discord-ptb.git",
      "branch": "master",
      "path": "",
      "repo": "bur",
      "base_image": "archlinux:base-devel",
      "force": true
    }
  ]
}

Poll the server for new builds.

HTTP Request

GET /api/v1/jobs/poll

Query Parameters

Parameter	Description
arch	For which architecture to receive jobs
max	How many jobs to receive at most